doc/misc.tex: Clarify that `augment-options' is in `sod-frontend'.

[sod] / doc / parsing.tex

diff --git a/doc/parsing.tex b/doc/parsing.tex
index 8aeb26b..c694ef8 100644 (file)
--- a/doc/parsing.tex
+++ b/doc/parsing.tex
@@ -51,6 +51,41 @@ 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}{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}
@@ -217,6 +252,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
@@ -237,6 +273,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
@@ -284,6 +321,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
@@ -317,6 +355,7 @@ here.
   return nil.
 \end{describe*}
 
+
 \subsection{Character scanners} \label{sec:parsing.scanner.char}
 
 Character scanners are scanners which read sequences of characters.
@@ -377,6 +416,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
@@ -401,6 +441,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
@@ -465,6 +506,7 @@ file-location protocols.
   at least once, or with $@<used> > @<start>$.
 \end{describe}
 
+
 \subsection{Token scanners} \label{sec:parsing.scanner.token}
 
 \begin{describe}{cls}
@@ -487,6 +529,7 @@ file-location protocols.
     {token-scanner-place-p @<value> @> @<generalized-boolean>}
 \end{describe}
 
+
 \subsection{List scanners}
 
 \begin{describe}{ty}{list-scanner}
@@ -499,7 +542,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}
@@ -519,14 +573,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}
@@ -568,6 +614,9 @@ file-location protocols.
      \-\nlret @<value>^*}
 \end{describe}
 
+
+\subsection{Basic parser syntax} \label{sec:parsing.syntax.basic}
+
 \begin{describe}{parse}{:eof}
 \end{describe}
 
@@ -643,6 +692,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}
 
@@ -668,6 +720,9 @@ 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}
 
@@ -717,6 +772,9 @@ file-location protocols.
 \begin{describe}{parse}[atom]{@<atom>}
 \end{describe}
 
+
+\subsection{Scanner contexts} \label{sec:parsing.syntax.scanner}
+
 \begin{describe}{cls}{scanner-context () \&key :scanner}
 \end{describe}
 
@@ -733,6 +791,9 @@ file-location protocols.
       \&key :scanner}
 \end{describe}
 
+
+\subsection{Expression parsing} \label{sec:parsing.syntax.expression}
+
 \begin{describe}{gf}{push-operator @<operator> @<state>}
 \end{describe}
 
@@ -807,7 +868,7 @@ file-location protocols.
 \end{describe*}
 
 %%%-------------------------------------------------------------------------
-\section{Lexical analyser}
+\section{Lexical analyser} \label{sec:parsing.lexical}
 
 \begin{describe}{cls}
     {sod-token-scanner (token-scanner)