Changeset trunk,13 for trunk

Timestamp:

06/23/2007 04:30:57 AM (19 years ago)

Author:

dsowen

revision id:

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

Message:

Added more documentation.

File:

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

trunk/parse3.lisp

@@ -1 @@
-(in-package #:dso-parse)
+;(in-package #:dso-parse)
 
 
@@ -29 +29 @@
   `(if (and (string/= "" ,input) (char= ,char (char ,input 0)))
     (let ((,next (substring ,input :start 1))
-          (,match '(,char)))
+          (,match ,char))
       ,then)
     ,else))
@@ -42 +42 @@
           (string= ,string (substring ,input :length ,len)))
       (let ((,next (substring ,input :start ,len))
-            (,match '(,string)))
+            (,match ,string))
         ,then)
       ,else)))
@@ -58 +58 @@
         (if ,start
             (let ((,next (substring ,input :start ,end))
-                  (,match (list (substring ,input :end ,end))))
+                  (,match (substring ,input :end ,end)))
               ,then)
             ,else)))))
@@ -86 +86 @@
           `(if-matches ,input ,head (,head-next ,head-match)
             (if-matches-sequence ,head-next ,tail (,next ,tail-match)
-              (let ((,match (cons ,head-match ,tail-match)))
+              (let ((,match (if ,head-match (cons ,head-match ,tail-match) ,tail-match)))
                 ,then)
               ,else)
@@ -92 +92 @@
         (with-gensyms (tail-match)
           `(if-matches ,input ,head (,next ,tail-match)
-            (let ((,match (list ,tail-match)))
+            (let ((,match (if ,tail-match (list ,tail-match) nil)))
               ,then)
             ,else)))))
@@ -110 +110 @@
           (if-matches ,next ,rule (,next2 ,match2)
             (setf ,next ,next2
-                  ,match (cons ,match2 ,match))
+                  ,match (if ,match2 (cons ,match2 ,match) ,match))
             (return-from ,r ,else)))
         (setf ,match (nreverse ,match))
@@ -131 +131 @@
                       (progn
                         (psetf ,next ,next2
-                               ,match (cons ,match2 ,match)
+                               ,match (if ,match2 (cons ,match2 ,match) ,match)
                                ,i (1+ ,i))
                         t)))))
@@ -152 +152 @@
       ,else)))
 
-;;; The required and forbidden rules don't quite work right, as using
-;;; a rule like (#\a (& #\b)) will put an extaneous NIL on the end of
-;;; the match tree.
-
 (defmacro if-matches-required (input rule (next match)
                                &body (&optional (then t) else))
+  "Matches if RULE matches against INPUT, but neither consumes input
+nor contributes to the parse tree."
   `(if-matches ,input ,rule (,(gensym) ,(gensym))
     (let ((,next ,input)
@@ -166 +164 @@
 (defmacro if-matches-forbidden (input rule (next match)
                                 &body (&optional (then t) else))
+  "Matches if RULE doesn't match against INPUT, but neither consumes
+input nor contributes to the parse tree."
   `(if-matches ,input ,rule (,(gensym) ,(gensym))
     ,else
@@ -174 +174 @@
 (defmacro if-matches-only (input rule (next match)
                            &body (&optional (then t) else))
-  (with-gensyms (match2)
-    `(if-matches ,input ,rule (,next ,match2)
-      (let ((,match nil))
-        ,then)
-      ,else)))
+  "Matches RULE against INPUT and consumes input, but doesn't
+contribute to the parse tree."
+  `(if-matches ,input ,rule (,next ,match)
+    (let ((,match nil))
+      ,then)
+    ,else))
 
 (defmacro if-matches (input rule (next match) &body (&optional (then t) else))
+  "Matches RULE against INPUT.  If the rule is matched, the THEN form
+is executed with NEXT bound to the remainder of the input after
+consumption (if any), and MATCH to the parse tree.
+
+Rules may be defined in a short-hand using this macro, and nested:
+
+* Characters and strings match themselves.
+
+* A regular expression is denoted as (^ regex).
+
+* A sequence is a list of rules (rule1 rule2) that doesn't begin with
+  a reserved mark.
+
+* An ordered choice is (/ rule1 rule2).
+
+* A Kleene-closure is (* rule).  + and ? may be used as well, and all
+  act as in regular expressions.
+
+* Range matching is ({} min max rule).  If MIN is NIL, it is treated
+  as 0.  If MAX is NIL, no limit is placed on matches.
+
+* Requiring a match without consuming or tree-building is done as (&
+  rule).  Forbidding a match likewise as (! rule).
+
+* Matching and consuming without tree-building is (= rule).
+
+If RULE is a symbol, that symbol will be used as the name of a parsing
+function.  The function will be given the input as its only argument,
+and is expected to return (VALUES T NEXT MATCH) (where NEXT refers to
+the remaining, unsonsumed input, and MATCH is the generated tree), or
+NIL otherwise."
   (etypecase rule
     (symbol `(if-matches-parser ,input ,rule (,next ,match) ,then ,else))