X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/40d95de71fca4c3b7b145d5ba73d1420e8854673..d5fdd49e70b734b791eb907706f92da5775e2a8b:/doc/parsing.tex

diff --git a/doc/parsing.tex b/doc/parsing.tex
index c91c74b..22960ee 100644
--- a/doc/parsing.tex
+++ b/doc/parsing.tex
@@ -51,6 +51,46 @@ consumed any input items.
 \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}
@@ -71,18 +111,21 @@ consumed any input items.
 \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}
-  \begin{describe}{meth}{file-location (@<stream> stream) @> @<floc>}
+  \begin{describe}{meth}{stream}
+      {file-location (@<stream> stream) @> @<floc>}
   \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}
 
-\begin{describe}{meth}
+\begin{describe}{meth}{condition-with-location}
     {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}
+       {enclosing-condition-with-location (condition)           \\ \>
+         \&key :location}
+     \dhead{cls}
        {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}{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*}
@@ -175,14 +222,19 @@ consumed any input items.
 
 \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}
 
@@ -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.
 
+
 \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}
 
+
 \subsection{Place-capture scanner protocol} \label{sec:parsing.scanner.place}
 
 The place-capture protocol allows rewinding to an earlier point in the
@@ -241,7 +295,7 @@ depends on the type of scanner.  Given a captured place, the scanner can be
 rewound to the position held in it.
 
 Depending on how the scanner works, holding onto a captured place might
-consume a lot of memory or case poor performance.  For example, if the
+consume a lot of memory or cause poor performance.  For example, if the
 scanner is reading from an input stream, having a captured place means that
 data from that point on must be buffered in case the program needs to rewind
 the scanner and read that data again.  Therefore it's possible to
@@ -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}
 
+
 \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*}
 
+
 \subsection{Character scanners} \label{sec:parsing.scanner.char}
 
 Character scanners are scanners which read sequences of characters.
@@ -327,7 +383,7 @@ Character scanners are scanners which read sequences of characters.
 \begin{describe}{gf}{scanner-unread @<scanner> @<character>}
   Rewind the @<scanner> by one step.  The @<chararacter> must be the previous
   current character, and becomes the current character again.  It is an error
-  if: the @<scanner> has reached end-of-file; the @<scanner> is never been
+  if: the @<scanner> has reached end-of-file; the @<scanner> has never been
   stepped; or @<character> was not the previous current character.
 \end{describe}
 
@@ -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}
 
+
 \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}
 
+
 \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}
 
+\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}
@@ -421,7 +483,7 @@ file-location protocols.
 
 \begin{describe}{gf}
     {charbuf-scanner-map @<scanner> @<func> \&optional @<fail>
-      \nlret @<result> @<successp> @<consumedp>}
+      \nlret @<result> @<success-flag> @<consumed-flag>}
   Read characters from the @<scanner>'s buffers.
 
   This is intended to be an efficient and versatile interface for reading
@@ -437,7 +499,7 @@ file-location protocols.
   @<start> (inclusive) and @<end> (exclusive) should be processed.  If
   @<func>'s return value @<donep> is nil then @<used> is ignored: the
   function has consumed the entire buffer and wishes to read more.  If
-  @<donep> is non-nil, then it must be a fixnum such that $@<start> \le
+  @<donep> is non-nil, then @<used> must be a fixnum such that $@<start> \le
   @<used> \le @<end>$: the function has consumed the buffer as far as @<used>
   (exclusive) and has completed successfully.
 
@@ -457,12 +519,18 @@ file-location protocols.
   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}
 
+\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}
 
@@ -479,6 +547,7 @@ file-location protocols.
     {token-scanner-place-p @<value> @> @<generalized-boolean>}
 \end{describe}
 
+
 \subsection{List scanners}
 
 \begin{describe}{ty}{list-scanner}
@@ -491,7 +560,18 @@ file-location protocols.
 \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}
@@ -511,14 +591,6 @@ file-location protocols.
      \-\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}
@@ -536,9 +608,6 @@ file-location protocols.
 \begin{describe}{gf}{parser-step @<context> @> @<form>}
 \end{describe}
 
-\begin{describe}{sym}{it}
-\end{describe}
-
 \begin{describe}{mac}
     {if-parse (@[[ \=:result @<result-var> @!
                      :expected @<expected-var> @!             \+\\
@@ -563,6 +632,12 @@ file-location protocols.
      \-\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}
 
@@ -638,6 +713,9 @@ file-location protocols.
       @<form>^*}
 \end{describe}
 
+
+\subsection{Place-capture protocol} \label{sec:parsing.syntax.place}
+
 \begin{describe}{gf}{parser-capture-place @<context> @> @<form>}
 \end{describe}
 
@@ -648,7 +726,7 @@ file-location protocols.
 \end{describe}
 
 \begin{describe}{gf}
-    {parser-places-must-be-released-p @<context> @> @<generalized-boolean>>}
+    {parser-places-must-be-released-p @<context> @> @<generalized-boolean>}
 \end{describe}
 
 \begin{describe}{mac}
@@ -663,12 +741,19 @@ file-location protocols.
 \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}
+    {string-parser (character-parser-context) \&key :string :index :length}
+\end{describe}
+
 \begin{describe}{parseform}
     {if-char (@[@<result-var>@]) @<condition> @<consequent> @<alternative>}
 \end{describe}
@@ -676,10 +761,10 @@ file-location protocols.
 \begin{describe}{parseform}{char @<character>}
 \end{describe}
 
-\begin{describe}[char]{parse}{@<character>}
+\begin{describe}{parse}[char]{@<character>}
 \end{describe}
 
-\begin{describe}[string]{parse}{@<string>}
+\begin{describe}{parse}[string]{@<string>}
 \end{describe}
 
 \begin{describe}{parse}{:any}
@@ -709,16 +794,16 @@ file-location protocols.
 \begin{describe}{parseform}{token @<type> @[@<value>@] @[:peekp @<peek>@]}
 \end{describe}
 
-\begin{describe}[atom]{parse}{@<atom>}
+\begin{describe}{parse}[atom]{@<atom>}
 \end{describe}
 
-\begin{describe}[string]{parse}{@<string>}
-\end{describe}
+
+\subsection{Scanner contexts} \label{sec:parsing.syntax.scanner}
 
 \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}
@@ -731,14 +816,8 @@ file-location protocols.
       \&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}
@@ -794,8 +873,7 @@ file-location protocols.
 \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*}
 
@@ -805,7 +883,7 @@ file-location protocols.
 \end{describe*}
 
 %%%-------------------------------------------------------------------------
-\section{Lexical analyser}
+\section{Lexical analyser} \label{sec:parsing.lexical}
 
 \begin{describe}{cls}
     {sod-token-scanner (token-scanner)
@@ -836,8 +914,10 @@ file-location protocols.
 
 \begin{describe}{parseform}
     {error (@[[ :ignore-unconsumed @<flag> @!
-                :force-process @<flag> @]])                     \\ \ind
-      @<sub-parser> @<recover-parser>}
+                :force-process @<flag> @]])                     \\ \ind\ind
+        @<sub-parser> @<recover-parser>                       \-\\
+      @<declaration>^*                                          \\
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{parseform}{must @<sub-parser> @[@<default>@]}