Loading: 

Use asdf-install or asdf to compile cl-peg (see cl-peg.asd)

Usage:

First create a PEG grammar file, eg:

sentence <-  article? subject verb ( preposition? article? (object / object preposition object ))
spaces <- [ ]*
article <- spaces ("the" / "the two" / "a")
preposition <- spaces ("on" / "at" / "to" / "with")
subject <- spaces ("man" / "men" / "dog" / "dogs" / "cat")
verb <- spaces ("sat" / "saw" / "shot" / "gave")
object <- spaces ("cannon" / "hat" / "mat")

then create a grammar object and result object:

(require 'cl-peg)
(defvar *mygrammar*)
(defvar *parse-result*)

CL-USER> (setf *mygrammar* (cl-peg:create-peg-parser "example.peg"))
*MYGRAMMAR*

Now you can parse some input:

CL-USER> (setf *parse-result* (cl-peg:parse *mygrammar* "the cat sat on the mat"))
#S(CL-PEG:PARSE-RESULT
   :MATCHED T
   :MATCHED-WHOLE-INPUT T
   :ROOT-PARSE-NODE NIL
   :ORIGINAL-INPUT "the cat sat on the mat"
   :ORIGINAL-INPUT-OFFSET 0)

Once you have this parse-result you can check whether the parse succeeded:

CL-USER> (cl-peg:parse-result-matched *parse-result*)
T

whether all the input was matched (versus some prefix)

CL-USER> (cl-peg:parse-result-matched-whole-input *parse-result*)
T

To see the actual region that was matched, you have to save the parse tree when calling parse:

CL-USER> (setf *parse-result* (cl-peg:parse *mygrammar* "the cat sat on the mat" :save-parse-tree t))
<large tree>

To see the indices of the region matched:

CL-USER> (cl-peg:matched-region *parse-result*)
(0 22)

or the text:

CL-USER> (cl-peg:parse-result-original-input *parse-result*)
"the cat sat on the mat"

If you need to walk the parse tree, you can get the root parse-node with:

CL-USER> (cl-peg:parse-result-root-parse-node *parse-result*)
#S(PV :PE NT: |sentence| :CHILDREN (#S(PV :PE NT: |article| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
                                    (#S(PV :PE NT: |subject| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
                                     (#S(PV :PE NT: |verb| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
                                      (#S(PV :PE NT: |preposition| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
                                       (#S(PV :PE NT: |article| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
                                        #S(PV :PE NT: |object| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))))))))

Each parse node has a parse-element describing the part of the grammar related to it:

CL-USER> (cl-peg:parse-node-parse-element (cl-peg:parse-result-root-parse-node *parse-result*))
NT: |sentence|

and optional child nodes:

CL-USER> (cl-peg:parse-node-children (cl-peg:parse-result-root-parse-node *parse-result*))
(#S(PV :PE NT: |article| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
 (#S(PV :PE NT: |subject| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
  (#S(PV :PE NT: |verb| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
   (#S(PV :PE NT: |preposition| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
    (#S(PV :PE NT: |article| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL))
     #S(PV :PE NT: |object| :CHILDREN #S(PV :PE NT: |spaces| :CHILDREN NIL)))))))

John Leuner
jewel at subvert-the-dominant-paradigm.net
31 May 2006

--------------------------------------------------------------------------------

Implementation notes:

pegobjects.lisp implements the classes that make up the peg grammar tree. Most of this file is hashing and comparison routines for the genhash library.

matcher.lisp contains the methods that match in the input against the peg grammar. Some over-optimisation here.

yacc.lisp is cl-yacc. The reduce/reduce errors emitted while compiling the PEG grammar can be ignored, they are the result of the handling of MAGIC-DOT which matches any character (or the absence of any character, ie EOF).