src/method-{proto,impl}.lisp: Abstract out the receiver type.

[sod] / doc / parsing.tex

diff --git a/doc/parsing.tex b/doc/parsing.tex
index c91c74b..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


@@ -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
 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


@@ -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.


@@ -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
 \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}
 


@@ -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}


@@ -421,7 +483,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


@@ -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
   @<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.
 


@@ -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}


@@ -536,9 +608,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> @!             \+\\


@@ -563,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}
 


@@ -638,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}
 


@@ -648,7 +726,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}


@@ -663,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}


@@ -676,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}


@@ -709,16 +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}
 

-\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}{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}


@@ -731,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}


@@ -794,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*}
 


@@ -805,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)


@@ -836,8 +914,10 @@ 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}{parseform}{must @<sub-parser> @[@<default>@]}