X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/020b9e2b4364c61a668d47c4c5405295349817d8..6213be581b6fd4836c19af2f7970ecead5f8ae97:/doc/parsing.tex

diff --git a/doc/parsing.tex b/doc/parsing.tex
index adcc9e1..17f0ecb 100644
--- 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}
@@ -71,18 +106,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}
 
@@ -95,6 +133,9 @@ consumed any input items.
        {warning-with-location (condition-with-location warning) \\ \>
          \&key :location}
      \dhead{cls}
+       {information-with-location (condition-with-location information) \\ \>
+         \&key :location}
+     \dhead{cls}
        {enclosing-error-with-location
            (enclosing-error-with-location error)                \\ \>
          \&key :condition :location}
@@ -103,6 +144,10 @@ consumed any input items.
            (enclosing-condition-with-location warning)          \\ \>
          \&key :condition :location}
      \dhead{cls}
+       {enclosing-information-with-location
+           (enclosing-condition-with-location information)      \\ \>
+         \&key :condition :location}
+     \dhead{cls}
        {simple-condition-with-location
            (condition-with-location simple-condition)           \\ \>
          \&key :format-control :format-arguments :location}
@@ -113,9 +158,17 @@ consumed any input items.
      \dhead{cls}
        {simple-warning-with-location
            (warning-with-location simple-warning)               \\ \>
+         \&key :format-control :format-arguments :location}
+     \dhead{cls}
+       {simple-information-with-location
+           (information-with-location simple-information)       \\ \>
          \&key :format-control :format-arguments :location}}
 \end{describe*}
 
+\begin{describe}{gf}
+    {enclosing-condition-with-location-type @<condition> @> @<symbol>}
+\end{describe}
+
 \begin{describe}{fun}
     {make-condition-with-location @<default-type> @<floc>
                                   @<datum> \&rest @<arguments>
@@ -130,11 +183,52 @@ consumed any input items.
      \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}{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>}
@@ -190,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
-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
@@ -219,10 +313,10 @@ the scanner and read that data again.  Therefore it's possible to
 \begin{describe}{mac}
     {with-scanner-place (@<place> @<scanner>) @<declarations>^* @<form>^*
       @> @<value>^*}
-  Capture the @<scanner>'s current position as a place, evaluate the
-  @<body-form>s as an implicit progn with the variable @<place> bound to the captured
-  place.  When control leaves the @<body-form>s, the place is released.  The return
-  values are the values of the final @<body-form>.
+  Capture the @<scanner>'s current position as a place, evaluate the @<form>s
+  as an implicit progn with the variable @<place> bound to the captured
+  place.  When control leaves the @<form>s, the place is released.  The
+  return values are the values of the final @<form>.
 \end{describe}
 
 \subsection{Scanner file-location protocol} \label{sec:parsing.scanner.floc}
@@ -276,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
-  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}
 
@@ -370,7 +464,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
@@ -386,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
-  @<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.
 
@@ -485,9 +579,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> @!             \+\\
@@ -539,7 +630,7 @@ file-location protocols.
 \begin{describe}{parseform}
     {seq (@{ @<atomic-parser-spec> @!
              (@[@<var>@] @<parser>) @}^*)                       \\ \ind
-      @<body-form>^*}
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{parseform}{and @<parser>^*}
@@ -597,7 +688,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}
@@ -625,10 +716,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}
@@ -658,10 +749,7 @@ file-location protocols.
 \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}
@@ -764,18 +852,34 @@ file-location protocols.
 \begin{describe}{fun}{define-indicator @<indicator> @<description>}
 \end{describe}
 
-\begin{describe}{fun}{syntax-error @<scanner> @<expected> \&key :continuep}
+\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}
-    {lexer-error @<char-scanner> @<expected> @<consumed-flag>}
+    {lexer-error @<char-scanner> @<expected> \&key :location}
 \end{describe}
 
 \begin{describe}{parseform}
     {skip-until (@[[ :keep-end @<keep-end-flag> @]]) @<token-type>^*}
 \end{describe}
 
-\begin{describe}{parseform}{error () @<sub-parser> @<recover-parser>}
+\begin{describe}{parseform}
+    {error (@[[ :ignore-unconsumed @<flag> @!
+                :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}