Hey,
I just looked through the EBNF docs, and although the content is
really great, it doesn't look great in the ui browser. Here's a patch
that fixes a typo, replaces $subsection by klazuka's new $subsections
and fixes examples
Also, the new $subsections doesn't appear in the "Block elements" help
article, is that on purpose ?
More remarks :
- In examples, the USING: ... line is not greyed (this is done in word
definitions, so I guess it would be easy to do it here?) whichs makes
it hard to read.
- What's the difference between $unchecked-example and $example ?
- There are two articles that still need work : "Tokenizers" and
"Foreign Rules". I didn't know what to do with long parser, make the
$example or $code...
cheers,
On Mon, Oct 19, 2009 at 2:33 PM, Chris Double <[email protected]> wrote:
> I've finally written some documentation for the peg.ebnf vocabulary.
> This documents the various ways of using it (EBNF:, [EBNF ... ENBF]
> and <EBNF ... EBNF>) as well as the syntax for the EBNF language. Let
> me know (or provide patches!) if I left anything out or if anything is
> badly written.
>
> You can get it now from the 'ebnf' branch of
> git://double.co.nz/git/factor.git or when it gets pulled into the main
> Factor repository. When loaded you can read the help from within
> factor with:
>
> "peg.ebnf" about
>
> Chris.
> --
> http://www.bluishcoder.co.nz
>
> ------------------------------------------------------------------------------
> Come build with us! The BlackBerry(R) Developer Conference in SF, CA
> is the only developer event you need to attend this year. Jumpstart your
> developing skills, take BlackBerry mobile applications to market and stay
> ahead of the curve. Join us from November 9 - 12, 2009. Register now!
> http://p.sf.net/sfu/devconference
> _______________________________________________
> Factor-talk mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/factor-talk
>
--
Jon Harper
diff --git a/basis/peg/ebnf/ebnf-docs.factor b/basis/peg/ebnf/ebnf-docs.factor
index 5057693..93f709a 100644
--- a/basis/peg/ebnf/ebnf-docs.factor
+++ b/basis/peg/ebnf/ebnf-docs.factor
@@ -102,8 +102,12 @@ ARTICLE: "peg.ebnf.choice" "Choice"
"USING: prettyprint peg.ebnf ;"
"\"a\" [EBNF rule=\"a\" | \"b\" | \"c\" EBNF] ."
"\"a\""
+ }
+ { $unchecked-example
"\"b\" [EBNF rule=\"a\" | \"b\" | \"c\" EBNF] ."
"\"b\""
+ }
+ { $unchecked-example
"\"d\" [EBNF rule=\"a\" | \"b\" | \"c\" EBNF] ."
"Peg parsing error at character position 0. Expected token 'c' or token 'b' or token 'a'"
}
@@ -119,6 +123,8 @@ ARTICLE: "peg.ebnf.option" "Option"
"USING: prettyprint peg.ebnf ;"
"\"abc\" [EBNF rule=\"a\" \"b\"? \"c\" EBNF] ."
"V{ \"a\" \"b\" \"c\" }"
+ }
+ { $unchecked-example
"\"ac\" [EBNF rule=\"a\" \"b\"? \"c\" EBNF] ."
"V{ \"a\" f \"c\" }"
}
@@ -163,6 +169,8 @@ ARTICLE: "peg.ebnf.zero-or-more" "Zero or more"
"USING: prettyprint peg.ebnf ;"
"\"aab\" [EBNF rule=\"a\"* \"b\" EBNF] ."
"V{ V{ \"a\" \"a\" } \"b\" }"
+ }
+ { $unchecked-example
"\"b\" [EBNF rule=\"a\"* \"b\" EBNF] ."
"V{ V{ } \"b\" }"
}
@@ -218,6 +226,8 @@ ARTICLE: "peg.ebnf.action" "Action"
"USING: prettyprint peg.ebnf math.parser ;"
"\"<abcd>\" [EBNF rule=\"<\" ((!(\">\") .)* => [[ >string ]]) \">\" EBNF] ."
"V{ \"<\" \"abcd\" \">\" }"
+ }
+ { $unchecked-example
"\"123\" [EBNF rule=[0-9]+ => [[ string>number ]] EBNF] ."
"123"
}
@@ -235,6 +245,8 @@ ARTICLE: "peg.ebnf.semantic-action" "Semantic Action"
"USING: prettyprint peg.ebnf ;"
"\"1\" [EBNF rule=[0-9] ?[ digit> odd? ]? EBNF] ."
"49"
+ }
+ { $unchecked-example
"\"2\" [EBNF rule=[0-9] ?[ digit> odd? ]? EBNF] ."
"..error.."
}
@@ -255,7 +267,7 @@ ARTICLE: "peg.ebnf.variable" "Variable"
;
ARTICLE: "peg.ebnf.foreign-rules" "Foreign Rules"
-"Rules can call outto other peg.ebnf defined parsers. The result of "
+"Rules can call out to other peg.ebnf defined parsers. The result of "
"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 "
"latter allows calling a specific rule in a previously designed peg.ebnf parser. "
@@ -264,24 +276,43 @@ ARTICLE: "peg.ebnf.foreign-rules" "Foreign Rules"
{ $vocab-link "peg" } " defined parser and it will be called to perform the parse "
"for that rule."
{ $examples
+ "Using a peg.ebnf defined parser (the following two examples are equivalent) :"
+ { $list
{ $unchecked-example
"USING: prettyprint peg.ebnf ;"
"EBNF: parse-string"
"StringBody = (!('\"') .)*"
"String= '\"' StringBody:b '\"' => [[ b >string ]]"
";EBNF"
+ ""
"EBNF: parse-two-strings"
- "TwoStrings = <foreign parse-string String> <foreign parse-string String>"
+ "TwoStrings = <foreign parse-string String> <foreign parse-string String>"
+ ";EBNF"
+ " \"\"abc\"\"def\"\" parse-two-strings"
+ "V{ \"abc\" \"def\" }"
+ }
+ { $unchecked-example
+ "USING: prettyprint peg.ebnf ;"
+ "EBNF: parse-string"
+ "StringBody = (!('\"') .)*"
+ "String= '\"' StringBody:b '\"' => [[ b >string ]]"
";EBNF"
+ ""
"EBNF: parse-two-strings"
"TwoString = <foreign parse-string> <foreign parse-string>"
";EBNF"
+ "V{ \"abc\" \"def\" }"
}
+ }
+ "Using a word returning a peg-parser"
{ $unchecked-example
+ "USING: prettyprint peg.ebnf peg ;"
": a-token ( -- parser ) \"a\" token ;"
"EBNF: parse-abc"
"abc = <foreign a-token> 'b' 'c'"
";EBNF"
+ "\"abc\" parse-abc"
+ "V{ \"a\" \"b\" \"c\" }"
}
}
;
@@ -291,7 +322,7 @@ ARTICLE: "peg.ebnf.tokenizers" "Tokenizers"
"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. "
{ $examples
- { $unchecked-example
+ { $code
"EBNF: foo"
"rule = \"++\" \"--\""
";EBNF"
@@ -302,7 +333,7 @@ ARTICLE: "peg.ebnf.tokenizers" "Tokenizers"
"If you want to add whitespace handling to the grammar you need to put it "
"between the terminals: "
{ $examples
- { $unchecked-example
+ { $code
"EBNF: foo"
"space = (\" \" | \"\\r\" | \"\\t\" | \"\\n\")"
"spaces = space* => [[ drop ignore ]]"
@@ -315,7 +346,7 @@ ARTICLE: "peg.ebnf.tokenizers" "Tokenizers"
"have the grammar operate on these tokens. This is how the previous example "
"might look: "
{ $examples
- { $unchecked-example
+ { $code
"EBNF: foo"
"space = (\" \" | \"\\r\" | \"\\t\" | \"\\n\")"
"spaces = space* => [[ drop ignore ]]"
@@ -334,7 +365,7 @@ ARTICLE: "peg.ebnf.tokenizers" "Tokenizers"
"string comparison against successive items in the sequence. This can be used "
"to match an AST from a tokenizer: "
{ $examples
- { $unchecked-example
+ { $code
"TUPLE: ast-number value ;"
"TUPLE: ast-string value ;"
""
@@ -379,7 +410,7 @@ ARTICLE: "peg.ebnf.tokenizers" "Tokenizers"
"switch tokenizers multiple times during a grammar. Rules use the tokenizer that "
"was defined lexically before the rule. This is usefull in the JavaScript grammar: "
{ $examples
- { $unchecked-example
+ { $code
"EBNF: javascript"
"tokenizer = default"
"nl = \"\\r\" \"\\n\" | \"\\n\""
@@ -402,7 +433,7 @@ ARTICLE: "peg.ebnf.tokenizers" "Tokenizers"
"rule (managed by the 'Sc' rule here). If there is a newline, the semicolon can "
"be optional in places. "
{ $examples
- { $unchecked-example
+ { $code
"\"do\" Stmt:s \"while\" \"(\" Expr:c \")\" Sc => [[ s c ast-do-while boa ]]"
}
}
@@ -415,32 +446,36 @@ ARTICLE: "peg.ebnf" "EBNF"
"This vocubalary provides a DSL that allows writing PEG parsers that look like "
"EBNF syntax. It provides three parsing words described below. These words all "
"accept the same EBNF syntax. The difference is in how they are used. "
-{ $subsection POSTPONE: <EBNF }
-{ $subsection POSTPONE: [EBNF }
-{ $subsection POSTPONE: EBNF: }
+{ $subsections
+ POSTPONE: <EBNF
+ POSTPONE: [EBNF
+ POSTPONE: EBNF: }
"The EBNF syntax is composed of a series of rules of the form: "
{ $code
"rule1 = ..."
"rule2 = ..."
}
+$nl
"The last defined rule is the main rule for the EBNF. It is the first one run "
"and it is expected that the remaining rules are used by that rule. Rules may be "
"left recursive. "
"Each rule can contain the following: "
-{ $subsection "peg.ebnf.strings" }
-{ $subsection "peg.ebnf.any" }
-{ $subsection "peg.ebnf.sequence" }
-{ $subsection "peg.ebnf.choice" }
-{ $subsection "peg.ebnf.option" }
-{ $subsection "peg.ebnf.one-or-more" }
-{ $subsection "peg.ebnf.zero-or-more" }
-{ $subsection "peg.ebnf.and" }
-{ $subsection "peg.ebnf.not" }
-{ $subsection "peg.ebnf.character-class" }
-{ $subsection "peg.ebnf.foreign-rules" }
-{ $subsection "peg.ebnf.action" }
-{ $subsection "peg.ebnf.semantic-action" }
-{ $subsection "peg.ebnf.variable" }
+{ $subsections
+ "peg.ebnf.strings"
+ "peg.ebnf.any"
+ "peg.ebnf.sequence"
+ "peg.ebnf.choice"
+ "peg.ebnf.option"
+ "peg.ebnf.one-or-more"
+ "peg.ebnf.zero-or-more"
+ "peg.ebnf.and"
+ "peg.ebnf.not"
+ "peg.ebnf.character-class"
+ "peg.ebnf.foreign-rules"
+ "peg.ebnf.action"
+ "peg.ebnf.semantic-action"
+ "peg.ebnf.variable" }
+
"Grammars defined in EBNF need to handle each character, or sequence of "
"characters in the input. This can be tedious for dealing with whitespace in "
"grammars that have 'tokens' separated by whitespace. You can define your "
@@ -448,7 +483,7 @@ ARTICLE: "peg.ebnf" "EBNF"
"those tokens, allowing you to ignore the whitespace issue. The tokenizer "
"can be changed at various parts in the grammar as needed. The JavaScript grammar "
"does this to define the optional semicolon rule for example."
-{ $subsection "peg.ebnf.tokenizers" }
+{ $subsections "peg.ebnf.tokenizers" }
;
-ABOUT: "peg.ebnf"
\ No newline at end of file
+ABOUT: "peg.ebnf"
------------------------------------------------------------------------------
Come build with us! The BlackBerry(R) Developer Conference in SF, CA
is the only developer event you need to attend this year. Jumpstart your
developing skills, take BlackBerry mobile applications to market and stay
ahead of the curve. Join us from November 9 - 12, 2009. Register now!
http://p.sf.net/sfu/devconference
_______________________________________________
Factor-talk mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/factor-talk
