src/class-make-{proto,impl}.lisp: Don't always add initializers to classes.

[sod] / doc / parsing.tex

diff --git a/doc/parsing.tex b/doc/parsing.tex
index 4386b4c..22960ee 100644 (file)
--- a/doc/parsing.tex
+++ b/doc/parsing.tex
@@ -51,6 +51,46 @@ consumed any input items.
 \end{describe}
 
 %%%--------------------------------------------------------------------------
 \end{describe}
 
 %%%--------------------------------------------------------------------------

+\section{Streams} \label{sec:parsing.streams}
+
+\begin{describe*}
+    {\dhead{cls}{position-aware-stream \&key :file :line :column}
+     \dhead{gf}{position-aware-stream-file @<stream> @> @<pathname>}
+     \dhead{gf}{setf (position-aware-stream-file @<stream>) @<pathname>}
+     \dhead{gf}{position-aware-stream-line @<stream> @> @<fixnum>}
+     \dhead{gf}{setf (position-aware-stream-line @<stream>) @<fixnum>}
+     \dhead{gf}{position-aware-stream-column @<stream> @> @<fixnum>}
+     \dhead{gf}{setf (position-aware-stream-column @<stream>) @<fixnum>}}
+\end{describe*}
+
+\begin{describe*}
+    {\dhead{cls}{position-aware-input-stream \&key :file :line :column}
+     \dhead{cls}{position-aware-output-stream \&key :file :line :column}}
+\end{describe*}
+
+\begin{describe}{gf}{stream-pathname @<stream> @> @<pathname-or-nil>}
+  \begin{describe}{meth}{stream}
+      {stream-pathname (@<stream> stream) @> nil}
+  \end{describe}
+  \begin{describe}{meth}{file-stream}
+      {stream-pathname (@<stream> file-stream) @> @<pathname>}
+  \end{describe}
+  \begin{describe}{meth}{position-aware-stream}
+      {stream-pathname (@<stream> position-aware-stream) @> @<pathname>}
+  \end{describe}
+\end{describe}
+
+\begin{describe}{gf}{stream-line-and-column @<stream> @> @<line> @<column>}
+  \begin{describe}{meth}{stream}
+      {stream-line-and-column (@<stream> stream) @> nil nil}
+  \end{describe}
+  \begin{describe}{meth}{position-aware-stream}
+      {stream-line-and-column (@<stream> position-aware-stream)
+        \nlret @<line> @<column>}
+  \end{describe}
+\end{describe}
+
+%%%--------------------------------------------------------------------------

 \section{File locations} \label{sec:parsing.floc}
 
 \begin{describe}{cls}{file-location}
 \section{File locations} \label{sec:parsing.floc}
 
 \begin{describe}{cls}{file-location}


@@ -71,18 +111,21 @@ consumed any input items.
 \end{describe*}
 
 \begin{describe}{gf}{file-location @<object> @> @<floc>}
 \end{describe*}
 
 \begin{describe}{gf}{file-location @<object> @> @<floc>}

-  \begin{describe}{meth}{file-location (@<floc> file-location) @> @<floc>}
+  \begin{describe}{meth}{file-location}
+      {file-location (@<floc> file-location) @> @<floc>}

   \end{describe}
   \end{describe}

-  \begin{describe}{meth}{file-location (@<stream> stream) @> @<floc>}
+  \begin{describe}{meth}{stream}
+      {file-location (@<stream> stream) @> @<floc>}

   \end{describe}
   \end{describe}

-  \begin{describe}{meth}{file-location (@<any> t) @> @<floc>}
+  \begin{describe}{meth}{t}
+      {file-location (@<any> t) @> @<floc>}

   \end{describe}
 \end{describe}
 
 \begin{describe}{cls}{condition-with-location (condition) \&key :location}
 \end{describe}
 
   \end{describe}
 \end{describe}
 
 \begin{describe}{cls}{condition-with-location (condition) \&key :location}
 \end{describe}
 

-\begin{describe}{meth}
+\begin{describe}{meth}{condition-with-location}

     {file-location (@<condition> condition-with-location) @> @<floc>}
 \end{describe}
 
     {file-location (@<condition> condition-with-location) @> @<floc>}
 \end{describe}
 


@@ -98,6 +141,9 @@ consumed any input items.
        {information-with-location (condition-with-location information) \\ \>
          \&key :location}
      \dhead{cls}
        {information-with-location (condition-with-location information) \\ \>
          \&key :location}
      \dhead{cls}

+       {enclosing-condition-with-location (condition)           \\ \>
+         \&key :location}
+     \dhead{cls}

        {enclosing-error-with-location
            (enclosing-error-with-location error)                \\ \>
          \&key :condition :location}
        {enclosing-error-with-location
            (enclosing-error-with-location error)                \\ \>
          \&key :condition :location}


@@ -142,7 +188,8 @@ consumed any input items.
      \dhead{fun}{cerror-with-location @<floc> @<continue-string>
                                       @<datum> \&rest @<arguments>}
      \dhead{fun}{cerror*-with-location @<floc> @<datum> \&rest @<arguments>}
      \dhead{fun}{cerror-with-location @<floc> @<continue-string>
                                       @<datum> \&rest @<arguments>}
      \dhead{fun}{cerror*-with-location @<floc> @<datum> \&rest @<arguments>}

-     \dhead{fun}{warn-with-location @<floc> @<datum> \&rest @<arguments>}}
+     \dhead{fun}{warn-with-location @<floc> @<datum> \&rest @<arguments>}
+     \dhead{fun}{info-with-location @<floc> @<datum> \&rest @<arguments>}}

 \end{describe*}
 
 \begin{describe*}
 \end{describe*}
 
 \begin{describe*}


@@ -175,14 +222,19 @@ consumed any input items.
 
 \begin{describe}{gf}{classify-condition @<condition> @> @<string>}
   \begin{describe*}
 
 \begin{describe}{gf}{classify-condition @<condition> @> @<string>}
   \begin{describe*}

-      {\dhead{meth}{classify-condition (@<condition> error) @> @<string>}
-       \dhead{meth}{classify-condition (@<condition> warning) @> @<string>}
-       \dhead{meth}{classify-condition (@<condition> information)
-                       @> @<string>}
-       \dhead{meth}{classify-condition (@<condition> base-lexer-error)
-                       @> @<string>}
-       \dhead{meth}{classify-condition (@<condition> base-syntax-error)
-                       @> @<string>}}
+      {\dhead{meth}{error}
+         {classify-condition (@<condition> error) @> @<string>}
+       \dhead{meth}{warning}
+         {classify-condition (@<condition> warning) @> @<string>}
+       \dhead{meth}{information}
+         {classify-condition (@<condition> information)
+             @> @<string>}
+       \dhead{meth}{base-lexer-error}
+         {classify-condition (@<condition> base-lexer-error)
+             @> @<string>}
+       \dhead{meth}{base-syntax-error}
+         {classify-condition (@<condition> base-syntax-error)
+             @> @<string>}}

   \end{describe*}
 \end{describe}
 
   \end{describe*}
 \end{describe}
 


@@ -209,6 +261,7 @@ Some scanners support an additional \emph{place-capture} protocol which
 allows rewinding the scanner to an earlier point in the input so that it can
 be scanned again.
 
 allows rewinding the scanner to an earlier point in the input so that it can
 be scanned again.
 

+

 \subsection{Basic scanner protocol} \label{sec:parsing.scanner.basic}
 
 The basic protocol supports stepping the scanner forward through its input
 \subsection{Basic scanner protocol} \label{sec:parsing.scanner.basic}
 
 The basic protocol supports stepping the scanner forward through its input


@@ -229,6 +282,7 @@ sequence, and detecting the end of the sequence.
   step the scanner.
 \end{describe}
 
   step the scanner.
 \end{describe}
 

+

 \subsection{Place-capture scanner protocol} \label{sec:parsing.scanner.place}
 
 The place-capture protocol allows rewinding to an earlier point in the
 \subsection{Place-capture scanner protocol} \label{sec:parsing.scanner.place}
 
 The place-capture protocol allows rewinding to an earlier point in the


@@ -276,6 +330,7 @@ the scanner and read that data again.  Therefore it's possible to
   return values are the values of the final @<form>.
 \end{describe}
 
   return values are the values of the final @<form>.
 \end{describe}
 

+

 \subsection{Scanner file-location protocol} \label{sec:parsing.scanner.floc}
 
 Some scanners participate in the file-location protocol
 \subsection{Scanner file-location protocol} \label{sec:parsing.scanner.floc}
 
 Some scanners participate in the file-location protocol


@@ -309,6 +364,7 @@ here.
   return nil.
 \end{describe*}
 
   return nil.
 \end{describe*}
 

+

 \subsection{Character scanners} \label{sec:parsing.scanner.char}
 
 Character scanners are scanners which read sequences of characters.
 \subsection{Character scanners} \label{sec:parsing.scanner.char}
 
 Character scanners are scanners which read sequences of characters.


@@ -369,6 +425,7 @@ operations to the sequence of characters held by a character scanner.
   character scanner protocols is suitable.  See @|make-scanner-stream|.
 \end{describe}
 
   character scanner protocols is suitable.  See @|make-scanner-stream|.
 \end{describe}
 

+

 \subsection{String scanners} \label{sec:parsing.scanner.string}
 
 A \emph{string scanner} is a simple kind of character scanner which reads
 \subsection{String scanners} \label{sec:parsing.scanner.string}
 
 A \emph{string scanner} is a simple kind of character scanner which reads


@@ -393,6 +450,7 @@ and place-capture protocols.
   to the end of the @<string>).
 \end{describe}
 
   to the end of the @<string>).
 \end{describe}
 

+

 \subsection{Character buffer scanners} \label{sec:parsing.scanner.charbuf}
 
 A \emph{character buffer scanner}, or \emph{charbuf scanner} for short, is an
 \subsection{Character buffer scanners} \label{sec:parsing.scanner.charbuf}
 
 A \emph{character buffer scanner}, or \emph{charbuf scanner} for short, is an


@@ -409,6 +467,10 @@ file-location protocols.
   the scanner will update the location as it reads its input.
 \end{describe}
 
   the scanner will update the location as it reads its input.
 \end{describe}
 

+\begin{describe}{cls}
+    {charbuf-scanner-stream (character-scanner-stream) \&key :scanner}
+\end{describe}
+

 \begin{describe}{cls}{charbuf-scanner-place}
   The class of place objects captured by a charbuf scanner.
 \end{describe}
 \begin{describe}{cls}{charbuf-scanner-place}
   The class of place objects captured by a charbuf scanner.
 \end{describe}


@@ -457,12 +519,18 @@ file-location protocols.
   at least once, or with $@<used> > @<start>$.
 \end{describe}
 
   at least once, or with $@<used> > @<start>$.
 \end{describe}
 

+

 \subsection{Token scanners} \label{sec:parsing.scanner.token}
 
 \begin{describe}{cls}
     {token-scanner () \&key :filename (:line 1) (:column 0)}
 \end{describe}
 
 \subsection{Token scanners} \label{sec:parsing.scanner.token}
 
 \begin{describe}{cls}
     {token-scanner () \&key :filename (:line 1) (:column 0)}
 \end{describe}
 

+\begin{describe*}
+    {\dhead{gf}{setf (scanner-line @<scanner>) @<fixnum>}
+     \dhead{gf}{setf (scanner-column @<scanner>) @<fixnum>}}
+\end{describe*}
+

 \begin{describe}{gf}{token-type @<scanner> @> @<type>}
 \end{describe}
 
 \begin{describe}{gf}{token-type @<scanner> @> @<type>}
 \end{describe}
 


@@ -479,6 +547,7 @@ file-location protocols.
     {token-scanner-place-p @<value> @> @<generalized-boolean>}
 \end{describe}
 
     {token-scanner-place-p @<value> @> @<generalized-boolean>}
 \end{describe}
 

+

 \subsection{List scanners}
 
 \begin{describe}{ty}{list-scanner}
 \subsection{List scanners}
 
 \begin{describe}{ty}{list-scanner}


@@ -491,7 +560,18 @@ file-location protocols.
 \end{describe}
 
 %%%--------------------------------------------------------------------------
 \end{describe}
 
 %%%--------------------------------------------------------------------------

-\section{Parsing syntax}
+\section{Parser contexts and parser syntax} \label{sec:parsing.syntax}
+
+
+\subsection{Parser contexts} \label{sec:parsing.syntax.contexts}
+
+\begin{describe}{mac}
+    {with-parser-context
+        (@<context-class> @{ @<init-keyword> @<value> @}^*)     \\ \ind
+      @<declaration>^*                                          \\
+      @<form>^*
+     \-\nlret @<value>^*}
+\end{describe}

 
 \begin{describe}{gf}{expand-parser-spec @<context> @<spec> @> @<form>}
 \end{describe}
 
 \begin{describe}{gf}{expand-parser-spec @<context> @<spec> @> @<form>}
 \end{describe}


@@ -511,14 +591,6 @@ file-location protocols.
      \-\nlret @<name>}
 \end{describe}
 
      \-\nlret @<name>}
 \end{describe}
 

-\begin{describe}{mac}
-    {with-parser-context
-        (@<context-class> @{ @<init-keyword> @<value> @}^*)     \\ \ind
-      @<declaration>^*                                          \\
-      @<form>^*
-     \-\nlret @<value>^*}
-\end{describe}
-

 \begin{describe}{lmac}
     {parse @<parser> @> @<result> @<success-flag> @<consumed-flag>}
 \end{describe}
 \begin{describe}{lmac}
     {parse @<parser> @> @<result> @<success-flag> @<consumed-flag>}
 \end{describe}


@@ -560,6 +632,12 @@ file-location protocols.
      \-\nlret @<value>^*}
 \end{describe}
 
      \-\nlret @<value>^*}
 \end{describe}
 

+\begin{describe}{cls}{list-parser () \&key :var}
+\end{describe}
+
+
+\subsection{Basic parser syntax} \label{sec:parsing.syntax.basic}
+

 \begin{describe}{parse}{:eof}
 \end{describe}
 
 \begin{describe}{parse}{:eof}
 \end{describe}
 


@@ -635,6 +713,9 @@ file-location protocols.
       @<form>^*}
 \end{describe}
 
       @<form>^*}
 \end{describe}
 

+
+\subsection{Place-capture protocol} \label{sec:parsing.syntax.place}
+

 \begin{describe}{gf}{parser-capture-place @<context> @> @<form>}
 \end{describe}
 
 \begin{describe}{gf}{parser-capture-place @<context> @> @<form>}
 \end{describe}
 


@@ -660,12 +741,19 @@ file-location protocols.
 \begin{describe}{parseform}{commit}
 \end{describe}
 
 \begin{describe}{parseform}{commit}
 \end{describe}
 

+
+\subsection{Character parsers} \label{sec:parsing.syntax.character}
+

 \begin{describe}{cls}{character-parser-context () \&key}
 \end{describe}
 
 \begin{describe}{gf}{parser-current-char @<context> @> @<form>}
 \end{describe}
 
 \begin{describe}{cls}{character-parser-context () \&key}
 \end{describe}
 
 \begin{describe}{gf}{parser-current-char @<context> @> @<form>}
 \end{describe}
 

+\begin{describe}{cls}
+    {string-parser (character-parser-context) \&key :string :index :length}
+\end{describe}
+

 \begin{describe}{parseform}
     {if-char (@[@<result-var>@]) @<condition> @<consequent> @<alternative>}
 \end{describe}
 \begin{describe}{parseform}
     {if-char (@[@<result-var>@]) @<condition> @<consequent> @<alternative>}
 \end{describe}


@@ -673,10 +761,10 @@ file-location protocols.
 \begin{describe}{parseform}{char @<character>}
 \end{describe}
 
 \begin{describe}{parseform}{char @<character>}
 \end{describe}
 

-\begin{describe}[char]{parse}{@<character>}
+\begin{describe}{parse}[char]{@<character>}

 \end{describe}
 
 \end{describe}
 

-\begin{describe}[string]{parse}{@<string>}
+\begin{describe}{parse}[string]{@<string>}

 \end{describe}
 
 \begin{describe}{parse}{:any}
 \end{describe}
 
 \begin{describe}{parse}{:any}


@@ -706,13 +794,16 @@ file-location protocols.
 \begin{describe}{parseform}{token @<type> @[@<value>@] @[:peekp @<peek>@]}
 \end{describe}
 
 \begin{describe}{parseform}{token @<type> @[@<value>@] @[:peekp @<peek>@]}
 \end{describe}
 

-\begin{describe}[atom]{parse}{@<atom>}
+\begin{describe}{parse}[atom]{@<atom>}

 \end{describe}
 
 \end{describe}
 

+
+\subsection{Scanner contexts} \label{sec:parsing.syntax.scanner}
+

 \begin{describe}{cls}{scanner-context () \&key :scanner}
 \end{describe}
 
 \begin{describe}{cls}{scanner-context () \&key :scanner}
 \end{describe}
 

-\begin{describe}{gf}{parse-scanner @<context> @> @<symbol>}
+\begin{describe}{gf}{parser-scanner @<context> @> @<symbol>}

 \end{describe}
 
 \begin{describe}{cls}
 \end{describe}
 
 \begin{describe}{cls}


@@ -725,14 +816,8 @@ file-location protocols.
       \&key :scanner}
 \end{describe}
 
       \&key :scanner}
 \end{describe}
 

-\begin{describe}{gf}{push-operator @<operator> @<state>}
-\end{describe}
-
-\begin{describe}{gf}{push-value @<value> @<state>}
-\end{describe}

 
 

-\begin{describe}{gf}{apply-operator @<operator> @<state>}
-\end{describe}
+\subsection{Expression parsing} \label{sec:parsing.syntax.expression}

 
 \begin{describe}{gf}{operator-push-action @<left> @<right>}
 \end{describe}
 
 \begin{describe}{gf}{operator-push-action @<left> @<right>}
 \end{describe}


@@ -788,8 +873,7 @@ file-location protocols.
 \end{describe*}
 
 \begin{describe*}
 \end{describe*}
 
 \begin{describe*}

-    {\dhead{cls}{parenthesis () \&key :tag}
-     \dhead{cls}{open-parenthesis (parenthesis prefix-operator) \&key :tag}
+    {\dhead{cls}{open-parenthesis (parenthesis prefix-operator) \&key :tag}

      \dhead{cls}{close-parenthesis (parenthesis) \&key :tag}}
 \end{describe*}
 
      \dhead{cls}{close-parenthesis (parenthesis) \&key :tag}}
 \end{describe*}
 


@@ -799,7 +883,7 @@ file-location protocols.
 \end{describe*}
 
 %%%-------------------------------------------------------------------------
 \end{describe*}
 
 %%%-------------------------------------------------------------------------

-\section{Lexical analyser}
+\section{Lexical analyser} \label{sec:parsing.lexical}

 
 \begin{describe}{cls}
     {sod-token-scanner (token-scanner)
 
 \begin{describe}{cls}
     {sod-token-scanner (token-scanner)