[Gd-chatter] r11765 - trunk/libraries/utilities/peg-parser
agent at gwydiondylan.org
agent at gwydiondylan.org
Sat Mar 29 04:44:59 CET 2008
Author: agent
Date: Sat Mar 29 04:44:58 2008
New Revision: 11765
Modified:
trunk/libraries/utilities/peg-parser/parser-definers.dylan
trunk/libraries/utilities/peg-parser/parser-rules.dylan
trunk/libraries/utilities/peg-parser/parser-support.dylan
Log:
Job: minor
Improved comments.
Modified: trunk/libraries/utilities/peg-parser/parser-definers.dylan
==============================================================================
--- trunk/libraries/utilities/peg-parser/parser-definers.dylan (original)
+++ trunk/libraries/utilities/peg-parser/parser-definers.dylan Sat Mar 29 04:44:58 2008
@@ -1,10 +1,21 @@
module: peg-parser
synopsis: PEG parser macro definitions.
+// See parser-rules.dylan for a full explanation of rule parsers. Basically,
+// rule parsers parse a stream in a given context and return a value or sequence
+// of values called the "product."
/// SYNOPSIS: Defines an arbitrary 'rule parser'.
/// DISCUSSION: This macro defines a rule parser that includes support for
-/// debugging and other features described for rule parsers.
+/// debugging and other features described for rule parsers. The main part of
+/// the parser is Dylan code supplied by you.
+///
+/// [code]
+/// define parser-method char (stream, context)
+/// => (char :: false-or(<character>))
+/// read-element(stream, on-end-of-stream: #f)
+/// end
+/// [end code]
define macro parser-method-definer
{
define parser-method ?token:name
@@ -22,14 +33,14 @@
block()
?body
afterwards
- format-trace(?"token" ## " matched chars %x-%x",
+ format-trace(?"token" ## " matched stream pos %x-%x",
pos, ?stream.stream-position);
cleanup
outdent-trace();
exception (err :: <parse-failure>)
?stream.stream-position := pos;
indent-trace();
- format-trace(?"token" ## " no match, exp. %s at char %x",
+ format-trace(?"token" ## " no match, exp. %s at stream pos %x",
err.parse-expected, err.failure-position);
outdent-trace();
error(err)
@@ -45,7 +56,11 @@
/// SYNOPSIS: Defines a 'rule parser' and perhaps a token class for a given
/// token.
///
-/// The macro takes three forms. A form like
+/// The macro takes three forms: class, yield, and basic.
+///
+/// === Class form ===
+///
+/// This form creates a token class.
///
/// [code]
/// define parser t (<c>)
@@ -60,10 +75,12 @@
/// a slot named `content` (inherited from <c>) and a slot named `more-content`.
/// When <t-token> is initialized, `tokens` gets set to the product of the rule
/// `many(t2)`, `content` gets set to the expression `tokens[1]`, and
-/// `more-content` gets set to the expression `tokens[2]`, which must be a
-/// <string>.
+/// `more-content` gets set to the expression `tokens[2]` (which must be a
+/// <string>).
///
-/// A form like
+/// === Yield form ===
+///
+/// Yield form returns a value.
///
/// [code]
/// define parser t
@@ -75,7 +92,9 @@
/// defines a rule parser that returns `tokens[1]` directly, without defining
/// a `<t-token>` class.
///
-/// A form like
+/// === Basic form ===
+///
+/// This form returns a token symbol.
///
/// [code]
/// define parser t
@@ -85,11 +104,13 @@
///
/// defines a rule parser that return `#"t"`.
///
-/// All three forms allow two additional clauses, "afterwards" and "cleanup",
+/// === Affecting context ===
+///
+/// All three forms allow two additional clauses, "afterwards" and "cleanup,"
/// that perform actions after the rule parser matches or fails to match.
///
/// [code]
-/// define parser t
+/// define parser t ()
/// rule many(t2) => tokens;
/// slot t2 = tokens.count
/// afterwards (context, tokens)
@@ -106,8 +127,9 @@
/// define parser t
/// rule many(t2);
/// afterwards (context, tokens)
-/// // The product of this parser is #"t", but "tokens" will be the
-/// // product of many(t2).
+/// // The product of this parser is #"t" because this is a token symbol
+/// // parser, but the local variable 'tokens' will be the product of
+/// // many(t2).
/// ...
/// end parser;
/// [end code]
@@ -151,7 +173,7 @@
"match-" ## ?token-name
(context, ?token-name ## "-parser-rule" (stream, context))
afterwards
- format-trace(?"token-name" ## " matched chars %x-%x",
+ format-trace(?"token-name" ## " matched stream pos %x-%x",
pos, stream.stream-position);
cleanup
outdent-trace();
@@ -162,7 +184,7 @@
err.parse-expected :=
concatenate!(err.parse-expected, " in " ## ?"token-name");
indent-trace();
- format-trace(?"token-name" ## " no match, exp. %s at char %x",
+ format-trace(?"token-name" ## " no match, exp. %s at stream pos %x",
err.parse-expected, err.failure-position);
outdent-trace();
error(err)
@@ -204,7 +226,7 @@
"match-" ## ?token-name
(context, ?token-name ## "-parser-rule" (stream, context))
afterwards
- format-trace(?"token-name" ## " matched chars %x-%x",
+ format-trace(?"token-name" ## " matched stream pos %x-%x",
pos, stream.stream-position);
cleanup
outdent-trace();
@@ -215,7 +237,7 @@
err.parse-expected :=
concatenate!(err.parse-expected, " in " ## ?"token-name");
indent-trace();
- format-trace(?"token-name" ## " no match, exp. %s at char %x",
+ format-trace(?"token-name" ## " no match, exp. %s at stream pos %x",
err.parse-expected, err.failure-position);
outdent-trace();
error(err)
@@ -254,7 +276,7 @@
"match-" ## ?token-name
(context, ?token-name ## "-parser-rule" (stream, context))
afterwards
- format-trace(?"token-name" ## " matched chars %x-%x",
+ format-trace(?"token-name" ## " matched stream pos %x-%x",
pos, stream.stream-position);
cleanup
outdent-trace();
@@ -264,7 +286,7 @@
unless (err.failure-position) err.failure-position := pos end;
err.parse-expected :=
concatenate!(err.parse-expected, " in " ## ?"token-name");
- format-trace(" " ## ?"token-name" ## " no match, exp. %s at %x",
+ format-trace(" " ## ?"token-name" ## " no match, exp. %s at stream pos %x",
err.parse-expected, err.failure-position);
error(err)
end;
@@ -312,7 +334,8 @@
=> { inherited slot ?name = ?expression; ... }
{ ?body-clauses } => { ?body-clauses }
-// Optional.
+// Optional. Note that the body is turned into an expression, which is why the
+// 'user-functions' auxiliary macro takes an expression instead of a body.
body-clauses:
{ afterwards (?context:name, ?product:name) ?:body; ... }
=> { afterwards ?context, ?product, ?body; ... }
@@ -338,7 +361,7 @@
{ inherited slot ?:name = ?:expression; ... }
=> { inherited slot ?name; ... }
- // These are extra baggage to be ignored
+ // These are extra baggage to be ignored.
{ afterwards ?dummy:*; ... } => { ... }
{ cleanup ?dummy:*; ... } => { ... }
{ } => { }
@@ -358,7 +381,7 @@
?more:*) }
=> { ?token.?slot-name := ?expression; slot-initializers(?token; ?more) }
- // These are extra baggage to be ignored
+ // These are extra baggage to be ignored.
{ slot-initializers (?token:name; afterwards ?dummy:*; ?more:*) }
=> { slot-initializers(?token; ?more) }
{ slot-initializers (?token:name; cleanup ?dummy:*; ?more:*) }
@@ -371,7 +394,7 @@
// This auxiliary macro generates the match- and cleanup- functions.
define macro user-functions
- // Clean out any slot baggage.
+ // Slot declarations are extra baggage to be ignored.
{ user-functions(?token:name; slot ?dummy:*; ?more:*) }
=> { user-functions(?token; ?more) }
{ user-functions(?token:name; inherited slot ?dummy:*; ?more:*) }
Modified: trunk/libraries/utilities/peg-parser/parser-rules.dylan
==============================================================================
--- trunk/libraries/utilities/peg-parser/parser-rules.dylan (original)
+++ trunk/libraries/utilities/peg-parser/parser-rules.dylan Sat Mar 29 04:44:58 2008
@@ -8,8 +8,8 @@
/// SYNOPSIS: A function that partially parses a stream according to a rule.
///
/// Rule parsers are created by the 'seq', 'choice', 'many', 'opt', 'opt-seq',
-/// 'opt-choice', opt-many', 'req-next', and 'not-next' functions in the
-/// 'parser-definer' macro. They may also be created manually for efficiency
+/// 'opt-choice', opt-many', 'req-next', and 'not-next' functions used in
+/// 'parser-definer' macros. They may also be created manually for efficiency
/// or to support special behaviors via the 'parser-method-definer' macro.
///
/// Rule parsers must be named "parse-something" to work with the 'parser-definer'
@@ -17,9 +17,9 @@
/// after rolling back the position of the stream (so that another parser may
/// be tried).
///
-/// These things are done automatically (except for signalling <parse-failure>)
-/// when using 'parser-method-definer' or 'parser-definer' macros or the 'seq'
-/// etc. functions.
+/// Rollback and naming are done automatically when using 'parser-method-definer'
+/// or 'parser-definer' macros or the 'seq' etc. functions, but with the
+/// 'parser-method-definer' macro, you have to signal <parse-failure> on failure.
///
/// ARGUMENTS:
/// stream - An instance of <positionable-stream>.
@@ -31,6 +31,7 @@
/// SYNOPSIS: Builds a 'rule parser' matching a sequence of elements.
+/// Equivalent to PEG "p1 p2" operation.
/// ARGUMENTS:
/// "#rest sub-rules" - A series of 'rule parser's, all of which must succeed
/// for the returned parser to succeed.
@@ -60,6 +61,7 @@
/// SYNOPSIS: Builds a 'rule parser' matching one of several elements.
+/// Equivalent to PEG "p1 / p2" operation.
/// ARGUMENTS:
/// "#rest sub-rules" - A series of 'rule parser's, the first of which to
/// succeed supplies the parser's product.
@@ -92,6 +94,7 @@
/// SYNOPSIS: Builds a 'rule parser' matching one or more elements.
+/// Equivalent to PEG "p1+" operation.
/// ARGUMENTS:
/// sub-rule - A 'rule parser'.
/// VALUES:
@@ -122,6 +125,7 @@
/// SYNOPSIS: Builds a 'rule parser' matching zero or one element.
+/// Equivalent to PEG "p1?" operation.
/// ARGUMENTS:
/// sub-rule - A 'rule parser'.
/// VALUES:
@@ -143,6 +147,7 @@
/// SYNOPSIS: Builds a 'rule parser' matching zero or more elements.
+/// Equivalent to PEG "p1*" operation.
/// ARGUMENTS:
/// sub-rule - A 'rule parser'.
/// VALUES:
@@ -168,6 +173,7 @@
/// SYNOPSIS: Builds a 'rule parser' matching all elements or none of them.
+/// Equivalent to PEG "(p1 p2)?" operation.
/// ARGUMENTS:
/// "#rest sub-rules" - A series of 'rule parser's, all of which must match
/// for this parser to match.
@@ -184,7 +190,7 @@
/// SYNOPSIS: Builds a 'rule parser' matching one of the specified elements or
-/// none of them.
+/// none of them. Equivalent to PEG "(p1 / p2)?" operation.
/// ARGUMENTS:
/// "#rest sub-rules" - A series of 'rule parser's.
/// VALUES:
@@ -200,7 +206,7 @@
/// SYNOPSIS: Builds a 'rule parser' that looks ahead to match the sub-rule
-/// without consuming any elements.
+/// without consuming any elements. Equivalent to PEG "&p1" operation.
/// ARGUMENTS:
/// sub-rule - A 'rule parser'.
/// VALUES:
@@ -226,6 +232,7 @@
/// SYNOPSIS: Builds a 'rule parser' that looks ahead to ensure the sub-rule
/// does not match, but does not consume any elements in doing so.
+/// Equivalent to PEG "!p1" operation.
/// ARGUMENTS:
/// sub-rule - A 'rule parser'.
/// VALUES:
Modified: trunk/libraries/utilities/peg-parser/parser-support.dylan
==============================================================================
--- trunk/libraries/utilities/peg-parser/parser-support.dylan (original)
+++ trunk/libraries/utilities/peg-parser/parser-support.dylan Sat Mar 29 04:44:58 2008
@@ -1,5 +1,5 @@
module: peg-parser
-synopsis: Miscellaneous exports, tracing, and internal support.
+synopsis: The <token> class and miscellaneous exports and internal support.
/// SYNOPSIS: Names of parsers.
/// DISCUSSION: This is a table of <function> to <string>. Each 'rule parser'
@@ -28,8 +28,8 @@
/// DISCUSSION: Subclasses of <token> are created by 'parser-definer', but
/// tokens do not 'need' [em] to be of this class. Any object may be returned
/// by a 'rule parser', but the rule parsers created by 'seq', 'choice', etc.
-/// use #f to indicate an optional item not present or a token that doesn't
-/// consume any characters.
+/// use #f to indicate an optional item not present or a rule that doesn't
+/// consume any characters (i.e. all look-ahead rules).
define open abstract class <token> (<object>)
constant slot parse-start, required-init-keyword: #"start";
constant slot parse-end, required-init-keyword: #"end";
More information about the chatter
mailing list