diff --git a/extra/peg/peg-docs.factor b/extra/peg/peg-docs.factor index ec4a5d304d..40743132f3 100644 --- a/extra/peg/peg-docs.factor +++ b/extra/peg/peg-docs.factor @@ -2,10 +2,112 @@ ! See http://factorcode.org/license.txt for BSD license. USING: help.markup help.syntax peg ; +HELP: parse +{ $values + { "string" "a string" } + { "parse" "a parser" } + { "result" "a or f" } +} +{ $description + "Given the input string, parse it using the given parser. The result is a object if " + "the parse was successful, otherwise it is f." } ; + HELP: token { $values - { "string" "a string" } } + { "string" "a string" } + { "parser" "a parser" } +} { $description - "A parser generator that returns a parser that matches the given string." } -{ $example "\"begin foo end\" \"begin\" token parse" "result-here" } ; + "Returns a parser that matches the given string." } ; + +HELP: range +{ $values + { "min" "a character" } + { "max" "a character" } + { "parser" "a parser" } +} +{ $description + "Returns a parser that matches a single character that lies within the range of characters given, inclusive." } +{ $example ": digit ( -- parser ) CHAR: 0 CHAR: 9 range ;" } ; + +HELP: seq +{ $values + { "seq" "a sequence of parsers" } + { "parser" "a parser" } +} +{ $description + "Returns a parser that calls all parsers in the given sequence, in order. The parser succeeds if " + "all the parsers succeed, otherwise it fails. The AST produced is a sequence of the AST produced by " + "the individual parsers." } ; + +HELP: choice +{ $values + { "seq" "a sequence of parsers" } + { "parser" "a parser" } +} +{ $description + "Returns a parser that will try all the parsers in the sequence, in order, until one succeeds. " + "The resulting AST is that produced by the successful parser." } ; + +HELP: repeat0 +{ $values + { "p1" "a parser" } + { "p2" "a parser" } +} +{ $description + "Returns a parser that parses 0 or more instances of the 'p1' parser. The AST produced is " + "an array of the AST produced by the 'p1' parser. An empty array indicates 0 instances were " + "parsed." } ; + +HELP: repeat1 +{ $values + { "p1" "a parser" } + { "p2" "a parser" } +} +{ $description + "Returns a parser that parses 1 or more instances of the 'p1' parser. The AST produced is " + "an array of the AST produced by the 'p1' parser." } ; + +HELP: optional +{ $values + { "p1" "a parser" } + { "p2" "a parser" } +} +{ $description + "Returns a parser that parses 0 or 1 instances of the 'p1' parser. The AST produced is " + "'f' if 0 instances are parsed the AST produced is 'f', otherwise it is the AST produced by 'p1'." } ; + +HELP: ensure +{ $values + { "p1" "a parser" } + { "p2" "a parser" } +} +{ $description + "Returns a parser that succeeds if the 'p1' parser succeeds but does not add anything to the " + "AST and does not move the location in the input string. This can be used for lookahead and " + "disambiguation, along with the " { $link ensure-not } " word." } +{ $example "\"0\" token ensure octal-parser" } ; + +HELP: ensure-not +{ $values + { "p1" "a parser" } + { "p2" "a parser" } +} +{ $description + "Returns a parser that succeeds if the 'p1' parser fails but does not add anything to the " + "AST and does not move the location in the input string. This can be used for lookahead and " + "disambiguation, along with the " { $link ensure } " word." } +{ $example "\"+\" token \"=\" token ensure-not \"+=\" token 3array seq" } ; + +HELP: action +{ $values + { "p1" "a parser" } + { "quot" "a quotation with stack effect ( ast -- ast )" } +} +{ $description + "Returns a parser that calls the 'p1' parser and applies the quotation to the AST resulting " + "from that parse. The result of the quotation is then used as the final AST. This can be used " + "for manipulating the parse tree to produce a AST better suited for the task at hand rather than " + "the default AST." } +{ $example "CHAR: 0 CHAR: 9 range [ to-digit ] action" } ; diff --git a/extra/peg/peg-tests.factor b/extra/peg/peg-tests.factor index 9becc81b56..7648819a8c 100644 --- a/extra/peg/peg-tests.factor +++ b/extra/peg/peg-tests.factor @@ -1,7 +1,7 @@ ! Copyright (C) 2007 Chris Double. ! See http://factorcode.org/license.txt for BSD license. ! -USING: kernel tools.test strings namespaces arrays sequences peg ; +USING: kernel tools.test strings namespaces arrays sequences peg peg.private ; IN: temporary { 0 1 2 } [ diff --git a/extra/peg/peg.factor b/extra/peg/peg.factor index 34c17448fb..1fb8e7860d 100644 --- a/extra/peg/peg.factor +++ b/extra/peg/peg.factor @@ -3,10 +3,14 @@ USING: kernel sequences strings namespaces math assocs shuffle vectors combinators.lib ; IN: peg -SYMBOL: ignore - TUPLE: parse-result remaining ast ; +GENERIC: parse ( state parser -- result ) + + ( remaining ast -- parse-result ) parse-result construct-boa ; @@ -20,8 +24,6 @@ TUPLE: parser id ; : init-parser ( parser -- parser ) get-next-id parser construct-boa over set-delegate ; -GENERIC: parse ( state parser -- result ) - TUPLE: token-parser symbol ; M: token-parser parse ( state parser -- result ) @@ -31,9 +33,6 @@ M: token-parser parse ( state parser -- result ) 2drop f ] if ; -: token ( string -- parser ) - token-parser construct-boa init-parser ; - TUPLE: range-parser min max ; M: range-parser parse ( state parser -- result ) @@ -48,9 +47,6 @@ M: range-parser parse ( state parser -- result ) ] if ] if ; -: range ( min max -- parser ) - range-parser construct-boa init-parser ; - TUPLE: seq-parser parsers ; : do-seq-parser ( result parser -- result ) @@ -71,9 +67,6 @@ TUPLE: seq-parser parsers ; M: seq-parser parse ( state parser -- result ) seq-parser-parsers [ V{ } clone ] dip (seq-parser) ; -: seq ( seq -- parser ) - seq-parser construct-boa init-parser ; - TUPLE: choice-parser parsers ; : (choice-parser) ( state parsers -- result ) @@ -90,9 +83,6 @@ TUPLE: choice-parser parsers ; M: choice-parser parse ( state parser -- result ) choice-parser-parsers (choice-parser) ; -: choice ( seq -- parser ) - choice-parser construct-boa init-parser ; - TUPLE: repeat0-parser p1 ; : (repeat-parser) ( parser result -- result ) @@ -115,25 +105,16 @@ M: repeat0-parser parse ( state parser -- result ) drop V{ } clone ] if* ; -: repeat0 ( parser -- parser ) - repeat0-parser construct-boa init-parser ; - TUPLE: repeat1-parser p1 ; M: repeat1-parser parse ( state parser -- result ) repeat1-parser-p1 tuck parse dup [ clone-result (repeat-parser) ] [ nip ] if ; -: repeat1 ( parser -- parser ) - repeat1-parser construct-boa init-parser ; - TUPLE: optional-parser p1 ; M: optional-parser parse ( state parser -- result ) dupd optional-parser-p1 parse swap f or ; -: optional ( parser -- parser ) - optional-parser construct-boa init-parser ; - TUPLE: ensure-parser p1 ; M: ensure-parser parse ( state parser -- result ) @@ -143,9 +124,6 @@ M: ensure-parser parse ( state parser -- result ) drop f ] if ; -: ensure ( parser -- parser ) - ensure-parser construct-boa init-parser ; - TUPLE: ensure-not-parser p1 ; M: ensure-not-parser parse ( state parser -- result ) @@ -155,9 +133,6 @@ M: ensure-not-parser parse ( state parser -- result ) ignore ] if ; -: ensure-not ( parser -- parser ) - ensure-not-parser construct-boa init-parser ; - TUPLE: action-parser p1 quot ; M: action-parser parse ( state parser -- result ) @@ -168,5 +143,34 @@ M: action-parser parse ( state parser -- result ) nip ] if ; +PRIVATE> + +: token ( string -- parser ) + token-parser construct-boa init-parser ; + +: range ( min max -- parser ) + range-parser construct-boa init-parser ; + +: seq ( seq -- parser ) + seq-parser construct-boa init-parser ; + +: choice ( seq -- parser ) + choice-parser construct-boa init-parser ; + +: repeat0 ( parser -- parser ) + repeat0-parser construct-boa init-parser ; + +: repeat1 ( parser -- parser ) + repeat1-parser construct-boa init-parser ; + +: optional ( parser -- parser ) + optional-parser construct-boa init-parser ; + +: ensure ( parser -- parser ) + ensure-parser construct-boa init-parser ; + +: ensure-not ( parser -- parser ) + ensure-not-parser construct-boa init-parser ; + : action ( parser quot -- parser ) action-parser construct-boa init-parser ;