6.18.2 PEG API Reference

Define Macros

The most straightforward way to define a PEG is by using one of the
define macros (both of these macroexpand into define
expressions). These macros bind parsing functions to variables. These
parsing functions may be invoked by match-pattern or
search-for-pattern, which return a PEG match record. Raw data can be
retrieved from this record with the PEG match deconstructor functions.
More complicated (and perhaps enlightening) examples can be found in the
tutorial.

Scheme Macro: define-peg-string-patternspeg-string

Defines all the nonterminals in the PEG peg-string. More
precisely, define-peg-string-patterns takes a superset of PEGs. A normal PEG
has a <- between the nonterminal and the pattern.
define-peg-string-patterns uses this symbol to determine what information it
should propagate up the parse tree. The normal <- propagates the
matched text up the parse tree, <-- propagates the matched text
up the parse tree tagged with the name of the nonterminal, and <
discards that matched text and propagates nothing up the parse tree.
Also, nonterminals may consist of any alphanumeric character or a “-”
character (in normal PEGs nonterminals can only be alphabetic).

Parsing & Matching Functions

For our purposes, “parsing” means parsing a string into a tree
starting from the first character, while “matching” means searching
through the string for a substring. In practice, the only difference
between the two functions is that match-pattern gives up if it can’t
find a valid substring starting at index 0 and search-for-pattern keeps
looking. They are both equally capable of “parsing” and “matching”
given those constraints.

Scheme Procedure: match-patternnonterm string

Parses string using the PEG stored in nonterm. If no match
was found, match-pattern returns false. If a match was found, a PEG
match record is returned.

The capture-type argument to define-peg-pattern allows you to
choose what information to hold on to while parsing. The options are:

Searches through string looking for a matching subexpression.
nonterm-or-peg can either be a nonterminal or a literal PEG
pattern. When a literal PEG pattern is provided, search-for-pattern works
very similarly to the regular expression searches many hackers are used
to. If no match was found, search-for-pattern returns false. If a match
was found, a PEG match record is returned.

Miscellaneous

Scheme Procedure: context-flattentst lst

Takes a predicate tst and a list lst. Flattens lst
until all elements are either atoms or satisfy tst. If lst
itself satisfies tst, (list lst) is returned (this is a
flat list whose only element satisfies tst).