steve
/
factor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

peg.ebnf: add a note for bug #23 and prefix articles with EBNF.

locals-and-roots
John Benediktsson 2016-03-30 13:30:30 -07:00
parent dcf8aa16c7
commit c4f67577f1
1 changed files with 20 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
basis/peg/ebnf/ebnf-docs.factor
View File

@ -58,7 +58,7 @@ HELP: EBNF:
} }
} ; } ;
ARTICLE: "peg.ebnf.strings" "Strings" ARTICLE: "peg.ebnf.strings" "EBNF Rule: Strings"
"A string in a rule will match that sequence of characters from the input string. " "A string in a rule will match that sequence of characters from the input string. "
"The string is delimited by matching single or double quotes. " "The string is delimited by matching single or double quotes. "
"Factor's escape sequences are interpreted: " { $link "escape" } ". " "Factor's escape sequences are interpreted: " { $link "escape" } ". "
@ -87,7 +87,7 @@ ARTICLE: "peg.ebnf.strings" "Strings"
} }
} ; } ;
ARTICLE: "peg.ebnf.any" "Any" ARTICLE: "peg.ebnf.any" "EBNF Rule: Any"
"A full stop character (.) will match any single token in the input string. " "A full stop character (.) will match any single token in the input string. "
"The AST resulting from this is the token itself." "The AST resulting from this is the token itself."
{ $examples { $examples
@ -98,7 +98,7 @@ ARTICLE: "peg.ebnf.any" "Any"
} }
} ; } ;
ARTICLE: "peg.ebnf.sequence" "Sequence" ARTICLE: "peg.ebnf.sequence" "EBNF Rule: Sequence"
"Any white space separated rule element is considered a sequence. Each rule " "Any white space separated rule element is considered a sequence. Each rule "
"in the sequence is matched from the input stream, consuming the input as it " "in the sequence is matched from the input stream, consuming the input as it "
"goes. The AST result is a vector containing the results of each rule element in " "goes. The AST result is a vector containing the results of each rule element in "
@ -112,7 +112,7 @@ ARTICLE: "peg.ebnf.sequence" "Sequence"
} }
; ;
ARTICLE: "peg.ebnf.grouping" "Group" ARTICLE: "peg.ebnf.grouping" "EBNF Rule: Group"
"Any sequence of rules may be grouped using parentheses (" { $snippet "()" } "). " "Any sequence of rules may be grouped using parentheses (" { $snippet "()" } "). "
"The parenthesized sequence can then be modified as a group. Parentheses also " "The parenthesized sequence can then be modified as a group. Parentheses also "
"delimit sets of choices separated by pipe (|) characters." "delimit sets of choices separated by pipe (|) characters."
@ -134,8 +134,8 @@ $nl
} }
; ;
ARTICLE: "peg.ebnf.choice" "Choice" ARTICLE: "peg.ebnf.choice" "EBNF Rule: Choice"
"Any rule element separated by a pipe character (|) is considered a choice. Choices " "Any rule element separated by a pipe character (|) is considered a " { $strong "choice" } ". Choices "
"are matched against the input stream in order. If a match succeeds then the remaining " "are matched against the input stream in order. If a match succeeds then the remaining "
"choices are discarded and the result of the match is the AST result of the choice." "choices are discarded and the result of the match is the AST result of the choice."
{ $examples { $examples
@ -155,9 +155,10 @@ ARTICLE: "peg.ebnf.choice" "Choice"
"Peg parsing error at character position 0.\nExpected 'a' or 'b' or 'c'\nGot 'd'" "Peg parsing error at character position 0.\nExpected 'a' or 'b' or 'c'\nGot 'd'"
} }
} }
{ $notes "Due to parser caching, rules can't re-use parsers that have already failed earlier in the choice." }
; ;
ARTICLE: "peg.ebnf.ignore" "Ignore" ARTICLE: "peg.ebnf.ignore" "EBNF Rule: Ignore"
"Any rule element followed by a tilde (~) will be matched, and its results " "Any rule element followed by a tilde (~) will be matched, and its results "
"discarded from the AST." "discarded from the AST."
{ $examples { $examples
@ -169,7 +170,7 @@ ARTICLE: "peg.ebnf.ignore" "Ignore"
} }
; ;
ARTICLE: "peg.ebnf.option" "Option" ARTICLE: "peg.ebnf.option" "EBNF Rule: Option"
"Any rule element followed by a question mark (?) is considered optional. The " "Any rule element followed by a question mark (?) is considered optional. The "
"rule is tested against the input. If it succeeds the result is stored in the AST. " "rule is tested against the input. If it succeeds the result is stored in the AST. "
"If it fails then the parse still succeeds and false (f) is stored in the AST." "If it fails then the parse still succeeds and false (f) is stored in the AST."
@ -187,7 +188,7 @@ ARTICLE: "peg.ebnf.option" "Option"
} }
; ;
ARTICLE: "peg.ebnf.character-class" "Character Class" ARTICLE: "peg.ebnf.character-class" "EBNF Rule: Character Class"
"Character class matching can be done using a range of characters defined in " "Character class matching can be done using a range of characters defined in "
"square brackets. Multiple ranges can be included in a single character class " "square brackets. Multiple ranges can be included in a single character class "
"definition. The syntax for the range is a start character, followed by a minus " "definition. The syntax for the range is a start character, followed by a minus "
@ -203,7 +204,7 @@ ARTICLE: "peg.ebnf.character-class" "Character Class"
} }
; ;
ARTICLE: "peg.ebnf.one-or-more" "One or more" ARTICLE: "peg.ebnf.one-or-more" "EBNF Rule: One or more"
"Any rule element followed by a plus (+) matches one or more instances of the rule " "Any rule element followed by a plus (+) matches one or more instances of the rule "
"from the input string. The AST result is the vector of the AST results from " "from the input string. The AST result is the vector of the AST results from "
"the matched rule." "the matched rule."
@ -216,7 +217,7 @@ ARTICLE: "peg.ebnf.one-or-more" "One or more"
} }
; ;
ARTICLE: "peg.ebnf.zero-or-more" "Zero or more" ARTICLE: "peg.ebnf.zero-or-more" "EBNF Rule: Zero or more"
"Any rule element followed by an asterisk (*) matches zero or more instances of the rule " "Any rule element followed by an asterisk (*) matches zero or more instances of the rule "
"from the input string. The AST result is the vector of the AST results from " "from the input string. The AST result is the vector of the AST results from "
"the matched rule. This will be empty if there are no matches." "the matched rule. This will be empty if there are no matches."
@ -234,7 +235,7 @@ ARTICLE: "peg.ebnf.zero-or-more" "Zero or more"
} }
; ;
ARTICLE: "peg.ebnf.and" "And" ARTICLE: "peg.ebnf.and" "EBNF Rule: And"
"Any rule element prefixed by an ampersand (&) performs the Parsing Expression " "Any rule element prefixed by an ampersand (&) performs the Parsing Expression "
"Grammar 'And Predicate' match. It attempts to match the rule against the input " "Grammar 'And Predicate' match. It attempts to match the rule against the input "
"string. It will cause the parse to succeed or fail depending on if the rule " "string. It will cause the parse to succeed or fail depending on if the rule "
@ -250,7 +251,7 @@ ARTICLE: "peg.ebnf.and" "And"
} }
; ;
ARTICLE: "peg.ebnf.not" "Not" ARTICLE: "peg.ebnf.not" "EBNF Rule: Not"
"Any rule element prefixed by an exclamation mark (!) performs the Parsing Expression " "Any rule element prefixed by an exclamation mark (!) performs the Parsing Expression "
"Grammar 'Not Predicate' match. It attempts to match the rule against the input " "Grammar 'Not Predicate' match. It attempts to match the rule against the input "
"string. It will cause the parse to succeed if the rule match fails, and to fail " "string. It will cause the parse to succeed if the rule match fails, and to fail "
@ -266,7 +267,7 @@ ARTICLE: "peg.ebnf.not" "Not"
} }
; ;
ARTICLE: "peg.ebnf.action" "Action" ARTICLE: "peg.ebnf.action" "EBNF Action"
"An action is a quotation that is run after a rule matches. The quotation " "An action is a quotation that is run after a rule matches. The quotation "
"consumes the AST of the rule match and leaves a new AST as the result. " "consumes the AST of the rule match and leaves a new AST as the result. "
"The stack effect of the action can be " { $snippet "( ast -- ast )" } " or " "The stack effect of the action can be " { $snippet "( ast -- ast )" } " or "
@ -292,7 +293,7 @@ ARTICLE: "peg.ebnf.action" "Action"
} }
; ;
ARTICLE: "peg.ebnf.semantic-action" "Semantic Action" ARTICLE: "peg.ebnf.semantic-action" "EBNF Semantic Action"
"Semantic actions allow providing a quotation that gets run on the AST of a " "Semantic actions allow providing a quotation that gets run on the AST of a "
"matched rule that returns success or failure. The result of the parse is decided by " "matched rule that returns success or failure. The result of the parse is decided by "
"the result of the semantic action. The stack effect for the quotation is " "the result of the semantic action. The stack effect for the quotation is "
@ -312,7 +313,7 @@ ARTICLE: "peg.ebnf.semantic-action" "Semantic Action"
} }
; ;
ARTICLE: "peg.ebnf.variable" "Variable" ARTICLE: "peg.ebnf.variable" "EBNF Variable"
"Variables names can be suffixed to a rule element using the colon character (:) " "Variables names can be suffixed to a rule element using the colon character (:) "
"followed by the variable name. These can then be used in rule actions to refer to " "followed by the variable name. These can then be used in rule actions to refer to "
"the AST result of the rule element with that variable name." "the AST result of the rule element with that variable name."
@ -325,8 +326,8 @@ ARTICLE: "peg.ebnf.variable" "Variable"
} }
; ;
ARTICLE: "peg.ebnf.foreign-rules" "Foreign Rules" ARTICLE: "peg.ebnf.foreign-rules" "EBNF Foreign Rules"
"Rules can call out to other peg.ebnf defined parsers. The result of " "Rules can call out to other " { $vocab-link "peg.ebnf" } " defined parsers. The result of "
"the foreign call then becomes the AST of the successful parse. Foreign rules " "the foreign call then becomes the AST of the successful parse. Foreign rules "
"are invoked using '<foreign word-name>' or '<foreign word-name rule>'. The " "are invoked using '<foreign word-name>' or '<foreign word-name rule>'. The "
"latter allows calling a specific rule in a previously designed peg.ebnf parser. " "latter allows calling a specific rule in a previously designed peg.ebnf parser. "
@ -357,7 +358,7 @@ ARTICLE: "peg.ebnf.foreign-rules" "Foreign Rules"
} }
; ;
ARTICLE: "peg.ebnf.tokenizers" "Tokenizers" ARTICLE: "peg.ebnf.tokenizers" "EBNF Tokenizers"
"It is possible to override the tokenizer in an EBNF defined parser. " "It is possible to override the tokenizer in an EBNF defined parser. "
"Usually the input sequence to be parsed is an array of characters or a string. " "Usually the input sequence to be parsed is an array of characters or a string. "
"Terminals in a rule match successive characters in the array or string. " "Terminals in a rule match successive characters in the array or string. "