From 547dbd3850279f19bfb79bdbc2b4b0f649998c16 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Sun, 24 Sep 2023 18:45:01 -0400 Subject: [PATCH] Add user guide section for parser rules --- doc/user_guide.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-) diff --git a/doc/user_guide.md b/doc/user_guide.md index 3c04534..561d852 100644 --- a/doc/user_guide.md +++ b/doc/user_guide.md @@ -12,7 +12,7 @@ Propane is a LALR Parser Generator (LPG) which: * accepts LR(0), SLR, and LALR grammars * generates a built-in lexer to tokenize input * supports UTF-8 lexer inputs - * generates a table-driven parser to parse input in linear time + * generates a table-driven shift/reduce parser to parse input in linear time * target C or D language outputs * is MIT-licensed * is distributable as a standalone Ruby script @@ -112,6 +112,9 @@ White space in the grammar file is also ignored. It is convention to use the extension `.propane` for the Propane grammar file, however any file name is accepted by Propane. +This user guide follows the convention of beginning a token name with a +lowercase character and beginning a rule name with an uppercase character. + ##> User Code Blocks User code blocks begin with the line following a "<<" token and end with the @@ -466,6 +469,76 @@ In this example: * a reduced `Values`'s parser value has a type of `Value[]`. * a reduced `KeyValue`'s parser value has a type of `Value[string]`. +##> Specifying a parser rule - the rule statement + +Rule statements create parser rules which define the grammar that will be +parsed by the generated parser. + +Multiple rules with the same name can be specified. +Rules with the same name define a rule set for that name and act as +alternatives that the parser can accept when attempting to match a reference to +that rule. + +The grammar file must define a rule with the name `Start` which will be used as +the top-level starting rule that the parser attempts to reduce. + +Example: + +``` +ptype ulong; +token word /[a-z]+/ << + $$ = match.length; +>> +Start -> word << + $$ = $1; +>> +``` + +In the above example the `Start` rule is defined to match a single `word` +token. + +Example: + +``` +Start -> E1 << + $$ = $1; +>> +E1 -> E2 << + $$ = $1; +>> +E1 -> E1 plus E2 << + $$ = $1 + $3; +>> +E2 -> E3 << + $$ = $1; +>> +E2 -> E2 times E3 << + $$ = $1 * $3; +>> +E3 -> E4 << + $$ = $1; +>> +E3 -> E3 power E4 << + $$ = pow($1, $3); +>> +E4 -> integer << + $$ = $1; +>> +E4 -> lparen E1 rparen << + $$ = $2; +>> +``` + +A parser rule has zero or more terms on the right side of its definition. +Each of these terms is either a token name or a rule name. + +In a parser rule code block, parser values for the right side terms are +accessible as `$1` for the first term's parser value, `$2` for the second +term's parser value, etc... +The `$$` symbol accesses the output parser value for this rule. +The above examples demonstrate how the parser values for the rule components +can be used to produce the parser value for the accepted rule. + ##> Specifying the parser module name - the `module` statement The `module` statement can be used to specify the module name for a generated