Changeset trunk,12 for trunk/parse3.lisp

Timestamp:

06/21/2007 05:15:55 AM (19 years ago)

Author:

dsowen

revision id:

svn-v3-trunk0:2948df59-2b31-0410-8e06-c40c0b09d5b6:trunk:12

Message:

Added some documentation to parse3.
Modified csv example for better tree output.

File:

• trunk/parse3.lisp (modified) (10 diffs)

trunk/parse3.lisp

@@ +1 @@
+(in-package #:dso-parse)
+
+
+
 (defmacro while (cond &body body)
   `(do ()
@@ -6 +10 @@
 (defmacro if-matches-parser (input parser (next match)
                              &body (&optional (then t) else))
+  "Matches if the function named by PARSER accepts the input.  Such a
+parser must return T, the remaining unmatched input, and the accepted
+input as values (in that order), or NIL if matching fails.
+
+NOTE: A parser that accepts a portion of input but does not wish to
+emit it may do so.  For example, a parser may return the values T,
+\"blah....\", NIL."
   (declare (symbol parser next match))
   (with-gensyms (ok)
@@ -13 +24 @@
 (defmacro if-matches-char (input char (next match)
                            &body (&optional (then t) else))
+  "Matches if the first character of INPUT is CHAR."
   (declare (symbol next match)
            (character char))
@@ -23 +35 @@
 (defmacro if-matches-string (input string (next match)
                              &body (&optional (then t) else))
+  "Matches if INPUT is prefixed by STRING."
   (declare (symbol next match)
            (string string))
@@ -35 +48 @@
 (defmacro if-matches-regex (input regex (next match)
                             &body (&optional (then t) else))
+  "Matches if REGEX matches the beginning of INPUT (REGEX is modified
+to anchor to the beginning automatically)."
   (declare (string regex)
            (symbol next match))
@@ -51 +66 @@
   (declare (symbol next match)
            (list alts))
+  "Matches if any of ALTS match INPUT.  The first rule in ALTS that
+matches is used to consume input and build the parse tree."
   (if alts
       `(if-matches ,input ,(first alts) (,next ,match)
@@ -61 +78 @@
 (defmacro if-matches-sequence (input seq (next match)
                                &body (&optional (then t) else))
+  "Matches if all of the rules in SEQ match INPUT in sequence (ie, the
+second rule matches what is left of the input after the first rule has
+matched, and so on)."
   (destructuring-bind (head . tail) seq
     (if tail
@@ -78 +98 @@
 (defmacro if-matches-eqcount (input count rule (next match)
                               &body (&optional (then t) else))
-  "WARNING: ELSE code executes in an anonymous block!"
+  "Matches if RULE matches INPUT exactly COUNT times in sequence.
+
+WARNING: ELSE code executes in an anonymous block!"
   (declare ((or null (integer 0)) count)
            (symbol next match))
@@ -95 +117 @@
 (defmacro if-matches-maxcount (input count rule (next match)
                                &body (&optional (then t) else))
+  "Always matches INPUT, but attempts to match RULE up to COUNT times
+in sequence (ie, RULE is matched against INPUT from 0 to COUNT times).
+If COUNT is NIL, RULE is matched as often as it will."
   (declare ((or null (integer 0)) count)
            (symbol next match)
@@ -114 +139 @@
 (defmacro if-matches-count (input mincount maxcount rule (next match)
                             &body (&optional (then t) else))
+  "Matches RULE against INPUT from MINCOUNT to MAXCOUNT times
+sequentially.  If MINCOUNT is NIL, it is treated as 0.  If MAXCOUNT is
+NIL, RULE is matched as often as it will (after the MINCOUNT is
+satisfied)."
   (when (and maxcount mincount) (setf maxcount (- maxcount mincount)))
   (with-gensyms (next2 match2)