doc/SYMBOLS: Distinguish c-type and parser (atomic) specifiers and forms.
[sod] / doc / parsing.tex
index 439d6d9..17f0ecb 100644 (file)
@@ -51,6 +51,41 @@ 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}{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 +106,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}
 
@@ -145,11 +183,52 @@ consumed any input items.
      \dhead{fun}{warn-with-location @<floc> @<datum> \&rest @<arguments>}}
 \end{describe*}
 
      \dhead{fun}{warn-with-location @<floc> @<datum> \&rest @<arguments>}}
 \end{describe*}
 
+\begin{describe*}
+    {\dhead{cls}{parser-error (error) \\ \ind
+                    \&key :expected :found \-}
+     \dhead{gf}{parser-error-expected @<condition> @> @<list>}
+     \dhead{gf}{parser-error-found @<condition> @> @<value>}}
+\end{describe*}
+
+\begin{describe}{fun}
+    {report-parser-error @<error> @<stream> @<show-expected> @<show-found>}
+\end{describe}
+
+\begin{describe*}
+    {\quad\=\kill
+     \dhead{cls}{base-lexer-error (error-with-location) \&key :location}
+     \dhead{cls}{simple-lexer-error
+                      (base-lexer-error simple-error-with-location) \\\>
+                    \&key :format-control :format-arguments :location}
+     \dhead{cls}{base-syntax-error (error-with-location) \&key :location}
+     \dhead{cls}{simple-syntax-error
+                      (base-syntax-error simple-error-with-location) \\\>
+                    \&key :format-control :format-arguments :location}}
+\end{describe*}
+
 \begin{describe}{mac}
     {with-default-error-location (@<floc>) @<declaration>^* @<form>^*
       @> @<value>^*}
 \end{describe}
 
 \begin{describe}{mac}
     {with-default-error-location (@<floc>) @<declaration>^* @<form>^*
       @> @<value>^*}
 \end{describe}
 
+\begin{describe}{gf}{classify-condition @<condition> @> @<string>}
+  \begin{describe*}
+      {\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}
+
 \begin{describe}{mac}
     {count-and-report-errors () @<declaration>^* @<form>^*
       @> @<value> @<n-errors> @<n-warnings>}
 \begin{describe}{mac}
     {count-and-report-errors () @<declaration>^* @<form>^*
       @> @<value> @<n-errors> @<n-warnings>}
@@ -205,7 +284,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
 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
 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
@@ -291,7 +370,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
 \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}
 
   stepped; or @<character> was not the previous current character.
 \end{describe}
 
@@ -385,7 +464,7 @@ file-location protocols.
 
 \begin{describe}{gf}
     {charbuf-scanner-map @<scanner> @<func> \&optional @<fail>
 
 \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
   Read characters from the @<scanner>'s buffers.
 
   This is intended to be an efficient and versatile interface for reading
@@ -401,7 +480,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
   @<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.
 
   @<used> \le @<end>$: the function has consumed the buffer as far as @<used>
   (exclusive) and has completed successfully.
 
@@ -500,9 +579,6 @@ file-location protocols.
 \begin{describe}{gf}{parser-step @<context> @> @<form>}
 \end{describe}
 
 \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> @!             \+\\
 \begin{describe}{mac}
     {if-parse (@[[ \=:result @<result-var> @!
                      :expected @<expected-var> @!             \+\\
@@ -612,7 +688,7 @@ file-location protocols.
 \end{describe}
 
 \begin{describe}{gf}
 \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}
 \end{describe}
 
 \begin{describe}{mac}
@@ -640,10 +716,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}
@@ -673,10 +749,7 @@ 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>}
-\end{describe}
-
-\begin{describe}[string]{parse}{@<string>}
+\begin{describe}{parse}[atom]{@<atom>}
 \end{describe}
 
 \begin{describe}{cls}{scanner-context () \&key :scanner}
 \end{describe}
 
 \begin{describe}{cls}{scanner-context () \&key :scanner}
@@ -779,6 +852,13 @@ file-location protocols.
 \begin{describe}{fun}{define-indicator @<indicator> @<description>}
 \end{describe}
 
 \begin{describe}{fun}{define-indicator @<indicator> @<description>}
 \end{describe}
 
+\begin{describe*}
+    {\dhead{cls}{lexer-error (parser-error base-lexer-error) \\ \ind
+                    \&key :expected :found :location \-}
+     \dhead{cls}{syntax-error (parser-error base-syntax-error) \\ \ind
+                    \&key :expected :found :location \-}}
+\end{describe*}
+
 \begin{describe}{fun}
     {syntax-error @<scanner> @<expected> \&key :continuep :location}
 \end{describe}
 \begin{describe}{fun}
     {syntax-error @<scanner> @<expected> \&key :continuep :location}
 \end{describe}
@@ -793,8 +873,13 @@ file-location protocols.
 
 \begin{describe}{parseform}
     {error (@[[ :ignore-unconsumed @<flag> @!
 
 \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>@]}
 \end{describe}
 
 \begin{describe}{fun}
 \end{describe}
 
 \begin{describe}{fun}