X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/cac85e0be5833902081c903f75e348b949294fb9..ae7a3c8fb42e457933efbbb9127d5a745096825a:/doc/parsing.tex

diff --git a/doc/parsing.tex b/doc/parsing.tex
index 2bf9105..0d3487d 100644
--- a/doc/parsing.tex
+++ b/doc/parsing.tex
@@ -7,7 +7,7 @@
 
 %%%----- Licensing notice ---------------------------------------------------
 %%%
-%%% This file is part of the Sensble Object Design, an object system for C.
+%%% This file is part of the Sensible Object Design, an object system for C.
 %%%
 %%% SOD is free software; you can redistribute it and/or modify
 %%% it under the terms of the GNU General Public License as published by
@@ -43,6 +43,13 @@ consumed any input items.
 \begin{describe}{fun}{combine-parser-failures @<failures> @> @<list>}
 \end{describe}
 
+\begin{describe}{fun}{parse-empty \&optional @<value> @> @<function>}
+\end{describe}
+
+\begin{describe}{fun}
+    {parse-fail @<indicator> \&optional @<consumedp> @> @<function>}
+\end{describe}
+
 %%%--------------------------------------------------------------------------
 \section{File locations} \label{sec:parsing.floc}
 
@@ -82,33 +89,48 @@ consumed any input items.
 \begin{describe*}
     {\quad\=\quad\=\kill
      \dhead{cls}
-      {error-with-location (condition-with-location error) \\ \>
-        \&key :location}
-    \dhead{cls}
-      {warning-with-location (condition-with-location warning) \\ \>
-        \&key :location}
-    \dhead{cls}
-      {enclosing-error-with-location
-          (enclosing-error-with-location error) \\ \>
-        \&key :condition :location}
-    \dhead{cls}
-      {enclosing-warning-with-location
-          (enclosing-condition-with-location warning) \\ \>
-        \&key :condition :location}
+       {error-with-location (condition-with-location error)     \\ \>
+         \&key :location}
+     \dhead{cls}
+       {warning-with-location (condition-with-location warning) \\ \>
+         \&key :location}
+     \dhead{cls}
+       {information-with-location (condition-with-location information) \\ \>
+         \&key :location}
      \dhead{cls}
-      {simple-condition-with-location
-          (condition-with-location simple-condition) \\ \>
-        \&key :format-control :format-arguments :location}
+       {enclosing-error-with-location
+           (enclosing-error-with-location error)                \\ \>
+         \&key :condition :location}
      \dhead{cls}
-      {simple-error-with-location
-          (error-with-location simple-error) \\ \>
-        \&key :format-control :format-arguments :location}
-    \dhead{cls}
-      {simple-warning-with-location
-          (warning-with-location simple-warning) \\ \>
-        \&key :format-control :format-arguments :location}}
+       {enclosing-warning-with-location
+           (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}
+     \dhead{cls}
+       {simple-error-with-location
+           (error-with-location simple-error)                   \\ \>
+         \&key :format-control :format-arguments :location}
+     \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>
@@ -212,10 +234,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}
@@ -370,8 +392,8 @@ file-location protocols.
   characters from a scanner in bulk.  The function @<func> is invoked
   repeatedly, as if by
   \begin{prog}
-    (multiple-value-bind (@<donep> @<used>) \\ \ind\ind
-        (funcall @<func> @<buf> @<start> @<end>) \- \\
+    (multiple-value-bind (@<donep> @<used>)                     \\ \ind\ind
+        (funcall @<func> @<buf> @<start> @<end>)              \-\\
       \textrm\ldots)
   \end{prog}
   The argument @<buf> is a simple string; @<start> and @<end> are two
@@ -387,8 +409,8 @@ file-location protocols.
   fails: the @<fail> function is called with no arguments, and is expected to
   return two values.  If omitted, @<fail> defaults to
   \begin{prog}
-    (lambda () \\ \ind
-      (values nil nil))%
+    (lambda ()                                                  \\ \ind
+      (values nil nil))
   \end{prog}
 
   The @|charbuf-scanner-map| function returns three values.  The first value
@@ -447,24 +469,31 @@ file-location protocols.
 
 \begin{describe}{mac}
     {defparse @<name> (@[[ :context (@<var> @<context-class>) @]]
-                       @<destructuring-lambda-list-item>^*) \\ \ind
-      @[[ @<declaration>^* @! @<doc-string> @]] \\
-      @<form>^* \-
-     \nlret @<name>}
+                       @<destructuring-lambda-list-item>^*)     \\ \ind
+      @[[ @<declaration>^* @! @<doc-string> @]]                 \\
+      @<form>^*
+     \-\nlret @<name>}
 \end{describe}
 
 \begin{describe}{mac}
     {with-parser-context
-        (@<context-class> @{ @<init-keyword> @<value> @}^*) \\ \ind
-      @<declaration>^* \\
-      @<form>^* \-
-     \nlret @<value>^*}
+        (@<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}{mac}
+    {parser @<lambda-list>
+      @[[ @<declaration>^* @! @<doc-string> @]]
+      @<parser>
+      @> @<function>}
+\end{describe}
+
 \begin{describe}{gf}{parser-at-eof-p @<context> @> @<form>}
 \end{describe}
 
@@ -476,26 +505,26 @@ file-location protocols.
 
 \begin{describe}{mac}
     {if-parse (@[[ \=:result @<result-var> @!
-                     :expected @<expected-var> @! \+ \\
-                     :consumedp @<consumed-var> @]]) \- \\ \ind\ind
-        @<parser> \- \\
-      @<consequent> \\
-      @[@<alternatve>@] \-
-     \nlret @<value>^*}
+                     :expected @<expected-var> @!             \+\\
+                     :consumedp @<consumed-var> @]])          \-\\ \ind\ind
+        @<parser>                                             \-\\
+      @<consequent>                                             \\
+      @[@<alternatve>@]
+     \-\nlret @<value>^*}
 \end{describe}
 
 \begin{describe}{mac}
-    {when-parse (@[@<result-var>@]) @<parser> \\ \ind
-      @<form>^* \-
-     \nlret @<value>^*}
+    {when-parse (@[@<result-var>@]) @<parser>                   \\ \ind
+      @<form>^*
+     \-\nlret @<value>^*}
 \end{describe}
 
 \begin{describe}{mac}
     {cond-parse (@[[ \=:result @<result-var> @!
-                       :expected @<expected-var> @! \+ \\
-                       :consumedp @<consumed-var> @]]) \- \\ \ind
-      @{ (@<parser> @<form>^*) @}^* \-
-     \nlret @<value>^*}
+                       :expected @<expected-var> @!           \+\\
+                       :consumedp @<consumed-var> @]])        \-\\ \ind
+      @{ (@<parser> @<form>^*) @}^*
+     \-\nlret @<value>^*}
 \end{describe}
 
 \begin{describe}{parse}{:eof}
@@ -523,8 +552,9 @@ file-location protocols.
 \end{describe}
 
 \begin{describe}{parseform}
-    {seq (@{ @<atomic-parser-spec> @! (@[@<var>@] @<parser>) @}^*) \\ \ind
-      @<body-form>^*}
+    {seq (@{ @<atomic-parser-spec> @!
+             (@[@<var>@] @<parser>) @}^*)                       \\ \ind
+      @<form>^*}
 \end{describe}
 
 \begin{describe}{parseform}{and @<parser>^*}
@@ -537,22 +567,22 @@ file-location protocols.
 \end{describe}
 
 \begin{describe}{parseform}
-    {many (\=@<accumulator-var> @<init-form> @<update-form> \+ \\
-           @[[ \=:new @<new-var> @! :final @<final-form> @! \+ \\
-                 :min @<minimum> @! :max @<maximum> @! \\
-                 :commitp @<commitp> @]]) \-\- \\ \ind
+    {many (\=@<accumulator-var> @<init-form> @<update-form>   \+\\
+           @[[ \=:new @<new-var> @! :final @<final-form> @!   \+\\
+                 :min @<minimum> @! :max @<maximum> @!          \\
+                 :commitp @<commitp> @]])                   \-\-\\ \ind
       @<item-parser> @[@<sep-parser>@]}
 \end{describe}
 
 \begin{describe}{parseform}
     {list (@[[ :min @<minimum> @! :max @<maximum> @!
-               :commitp @<commitp> @]])\\ \ind
+               :commitp @<commitp> @]])                         \\ \ind
       @<item-parser> @[@<sep-parser>@]}
 \end{describe}
 
 \begin{describe}{parseform}
     {skip-many (@[[ :min @<minimum> @! :max @<maximum> @!
-                    :commitp @<commitp> @]])\\ \ind
+                    :commitp @<commitp> @]])                    \\ \ind
       @<item-parser> @[@<sep-parser>@]}
 \end{describe}
 
@@ -594,6 +624,9 @@ file-location protocols.
 \begin{describe}{parseform}{peek @<parser>}
 \end{describe}
 
+\begin{describe}{parseform}{commit}
+\end{describe}
+
 \begin{describe}{cls}{character-parser-context () \&key}
 \end{describe}
 
@@ -675,7 +708,7 @@ file-location protocols.
 \end{describe}
 
 \begin{describe}{parseform}
-    {expr \=(@[[ :nestedp @<nestedp-var> @]]) \+ \\
+    {expr \=(@[[ :nestedp @<nestedp-var> @]])                 \+\\
             @<operand-parser> @<binop-parser>
             @<preop-parser> @<postop-parser>}
 \end{describe}
@@ -701,12 +734,13 @@ file-location protocols.
 
 \begin{describe*}
     {\quad\=\kill
-     \dhead{cls}{simple-binary-operator (simple-operator) \\ \>
-                  \&key :name :function :lprec :rprec :associativity}
+     \dhead{cls}{simple-binary-operator (simple-operator)       \\ \>
+                  \&key :name :function
+                        :lprec :rprec :associativity}
      \dhead{cls}{simple-postfix-operator (simple-unary-operator) \\ \>
                   \&key :name :function :lprec :rprec}
      \dhead{cls}{simple-prefix-operator
-                    (prefix-operator simple-unary-operator) \\ \>
+                    (prefix-operator simple-unary-operator)     \\ \>
                   \&key :name :function :rprec}}
 \end{describe*}
 
@@ -745,18 +779,25 @@ file-location protocols.
 \begin{describe}{fun}{define-indicator @<indicator> @<description>}
 \end{describe}
 
-\begin{describe}{fun}{syntax-error @<scanner> @<expected> \&key :continuep}
+\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
+      @<sub-parser> @<recover-parser>}
+\end{describe}
+
+\begin{describe}{parseform}{must @<sub-parser> @[@<default>@]}
 \end{describe}
 
 \begin{describe}{fun}