Updated CPGrammar documentation.

mysteriouspants · Oct 23, 2011 · 7a1fcae · 7a1fcae
1 parent a73a8f6
commit 7a1fcae
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 15 deletions.
diff --git a/CoreParse.xcodeproj/project.pbxproj b/CoreParse.xcodeproj/project.pbxproj
@@ -651,7 +651,7 @@
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
-			shellScript = "appledoc --logformat xcode \\\n         --exit-threshold 4 \\\n         --create-html \\\n         --no-create-docset \\\n         -o $SOURCE_ROOT/../CoreParseDocs/ \\\n         --project-name CoreParse \\\n         --project-version 0.9 \\\n         --project-company Beelsebob \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceAction.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceState.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceActionTable.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceGotoTable.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPItem.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPLR1Item.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceParserProtectedMethods.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Grammar/CPGrammar.m \\\n         $SOURCE_ROOT/CoreParse\n";
+			shellScript = "appledoc --logformat xcode \\\n         --exit-threshold 4 \\\n         --create-html \\\n         --no-create-docset \\\n         -o $SOURCE_ROOT/../CoreParseDocs/ \\\n         --project-name CoreParse \\\n         --project-version 0.9 \\\n         --project-company Beelsebob \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceAction.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceState.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceActionTable.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceGotoTable.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPItem.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPLR1Item.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Parsers/CPShiftReduceParsers/CPShiftReduceParserProtectedMethods.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Grammar/CPRHSItem.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Grammar/CPRHSItemResult.h \\\n         --ignore $SOURCE_ROOT/CoreParse/Grammar/CPGrammar.m \\\n         $SOURCE_ROOT/CoreParse\n";
 		};
 /* End PBXShellScriptBuildPhase section */
 

diff --git a/CoreParse/Grammar/CPGrammar.h b/CoreParse/Grammar/CPGrammar.h
@@ -63,29 +63,43 @@
  *
  * The BNF is expressed using rules in the form `nonTerminal ::= <subNonTerminal> "subTerminal" <subNonTerminal>;`.  Rules may optionally be prefixed with a number indicating their tag.
  * This allows you to quickly construct grammars in a readable form.
+ * You may also use EBNF to construct grammars.  This allows you to use the symbols "*", "+", and "?" to indicate that a construction may appear 0 or more; 1 or more; and 0 or 1 times respectively.
+ * You may also parenthesise subrules.
+ * 
+ * When you use any of the above EBNF constructs or parentheses, the parser will return the contents in an NSArray.
  *
  * The grammar used for parsing the BNF can be expressed as follows:
  * 
- *     0  ruleset       ::= &lt;ruleset&gt; &lt;rule&gt;;<br />
- *     1  ruleset       ::= &lt;rule&gt;;
+ *     0  ruleset           ::= &lt;ruleset&gt; &lt;rule&gt;;<br />
+ *     1  ruleset           ::= &lt;rule&gt;;
  *     
- *     2  rule          ::= "Number" &lt;unNumbered&gt;;<br />
- *     3  rule          ::= &lt;unNumbered&gt;;
+ *     2  rule              ::= "Number" &lt;unNumbered&gt;;<br />
+ *     3  rule              ::= &lt;unNumbered&gt;;
  *     
- *     4  unNumbered    ::= "Identifier" "::=" &lt;rightHandSide&gt; ";";
+ *     4  unNumbered        ::= "Identifier" "::=" &lt;rightHandSide&gt; ";";
  *     
- *     5  rightHandSide ::= &lt;rightHandSide> "|" &lt;sumset&gt;;<br />
- *     6  rightHandSide ::= &lt;rightHandSide> "|";<br />
- *     7  rightHandSide ::= &lt;sumset>;
+ *     5  rightHandSide     ::= &lt;rightHandSide> "|" &lt;sumset&gt;;<br />
+ *     6  rightHandSide     ::= &lt;rightHandSide> "|";<br />
+ *     7  rightHandSide     ::= &lt;sumset>;
  *     
- *     8  sumset        ::= &lt;sumset&gt; &lt;grammarSymbol&gt;;<br />
- *     9  sumset        ::= &lt;grammarSymbol&gt;;
+ *     8  sumset            ::= &lt;sumset&gt; &lt;rightHandSideItem&gt;;<br />
+ *     9  sumset            ::= &lt;rightHandSideItem&gt;;
+ *
+ *     10 rightHandSideItem ::= &lt;unit&gt;;<br />
+ *     11 rightHandSideItem ::= &lt;unit&gt; &lt;repeatSymbol&gt;;
+ *
+ *     12 unit              ::= &lt;gramarSymbol&gt;;<br />
+ *     13 unit              ::= "(" &lt;sumset&gt; ")";
+ *
+ *     14 repeatSymbol      ::= "*";<br />
+ *     15 repeatSymbol      ::= "+";<br />
+ *     16 repeatSymbol      ::= "?";
  *     
- *     10 grammarSymbol ::= &lt;nonTerminal&gt;;<br />
- *     11 grammarSymbol ::= &lt;terminal&gt;;
+ *     17 grammarSymbol     ::= &lt;nonTerminal&gt;;<br />
+ *     18 grammarSymbol     ::= &lt;terminal&gt;;
  *     
- *     12 nonTerminal   ::= "&lt;" "Identifier" "&gt;";<br />
- *     13 terminal      ::= String;
+ *     19 nonTerminal       ::= "&lt;" "Identifier" "&gt;";<br />
+ *     20 terminal          ::= String;
  * 
  * @param start The non-terminal that all parses must reduce to.
  * @param bnf   BNF for the grammar.