basis/peg/peg-docs.factor

   1 ! Copyright (C) 2007 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel quotations strings words ;
   4 IN: peg
   5
   6 HELP: parse
   7 { $values
   8   { "input" string }
   9   { "parser" parser }
  10   { "ast" object }
  11 }
  12 { $description
  13     "Given the input string, parse it using the given parser. The result is the abstract "
  14     "syntax tree returned by the parser." }
  15 { $see-also compile } ;
  16
  17 HELP: compile
  18 { $values
  19   { "parser" parser }
  20   { "word" word }
  21 }
  22 { $description
  23     "Compile the parser to a word. The word will have stack effect ( -- ast )."
  24 }
  25 { $see-also parse } ;
  26
  27 HELP: token
  28 { $values
  29   { "string" string }
  30   { "parser" parser }
  31 }
  32 { $description
  33     "Returns a parser that matches the given string." } ;
  34
  35 HELP: satisfy
  36 { $values
  37   { "quot" quotation }
  38   { "parser" parser }
  39 }
  40 { $description
  41     "Returns a parser that calls the quotation on the first character of the input string, "
  42     "succeeding if that quotation returns true. The AST is the character from the string." } ;
  43
  44 HELP: range
  45 { $values
  46   { "min" "a character" }
  47   { "max" "a character" }
  48   { "parser" parser }
  49 }
  50 { $description
  51     "Returns a parser that matches a single character that lies within the range of characters given, inclusive." }
  52 { $examples { $code ": digit ( -- parser ) CHAR: 0 CHAR: 9 range ;" } } ;
  53
  54 HELP: seq
  55 { $values
  56   { "seq" "a sequence of parsers" }
  57   { "parser" parser }
  58 }
  59 { $description
  60     "Returns a parser that calls all parsers in the given sequence, in order. The parser succeeds if "
  61     "all the parsers succeed, otherwise it fails. The AST produced is a sequence of the AST produced by "
  62     "the individual parsers." } ;
  63
  64 HELP: choice
  65 { $values
  66   { "seq" "a sequence of parsers" }
  67   { "parser" parser }
  68 }
  69 { $description
  70     "Returns a parser that will try all the parsers in the sequence, in order, until one succeeds. "
  71     "The resulting AST is that produced by the successful parser." } ;
  72
  73 HELP: repeat0
  74 { $values
  75   { "parser" parser }
  76 }
  77 { $description
  78     "Returns a parser that parses 0 or more instances of the " { $snippet "parser" } ". The AST produced is "
  79     "an array of the AST produced by the " { $snippet "parser" } ". An empty array indicates 0 instances were "
  80     "parsed." } ;
  81
  82 HELP: repeat1
  83 { $values
  84   { "parser" parser }
  85 }
  86 { $description
  87     "Returns a parser that parses 1 or more instances of the " { $snippet "parser" } ". The AST produced is "
  88     "an array of the AST produced by the " { $snippet "parser" } "." } ;
  89
  90 HELP: optional
  91 { $values
  92   { "parser" parser }
  93 }
  94 { $description
  95     "Returns a parser that parses 0 or 1 instances of the " { $snippet "parser" } ". The AST produced is "
  96     { $link f } " if 0 instances are parsed, otherwise it is the AST produced by " { $snippet "parser" } "." } ;
  97
  98 HELP: semantic
  99 { $values
 100   { "parser" parser }
 101   { "quot" { $quotation ( object -- ? ) } }
 102 }
 103 { $description
 104     "Returns a parser that succeeds if the " { $snippet "parser" } " succeeds and the quotation called with "
 105     "the AST produced by " { $snippet "parser" } " on the stack returns true." }
 106 { $examples
 107   { $example "USING: kernel math peg prettyprint ;" "\"C\" [ drop t ] satisfy [ 66 > ] semantic parse ." "67" }
 108 } ;
 109
 110 HELP: ensure
 111 { $values
 112   { "parser" parser }
 113 }
 114 { $description
 115     "Returns a parser that succeeds if the " { $snippet "parser" } " succeeds but does not add anything to the "
 116     "AST and does not move the location in the input string. This can be used for lookahead and "
 117     "disambiguation, along with the " { $link ensure-not } " word." }
 118 { $examples { $code "\"0\" token ensure octal-parser" } } ;
 119
 120 HELP: ensure-not
 121 { $values
 122   { "parser" parser }
 123 }
 124 { $description
 125     "Returns a parser that succeeds if the " { $snippet "parser" } " fails but does not add anything to the "
 126     "AST and does not move the location in the input string. This can be used for lookahead and "
 127     "disambiguation, along with the " { $link ensure } " word." }
 128 { $code "\"+\" token \"=\" token ensure-not \"+=\" token 3array seq" } ;
 129
 130 HELP: action
 131 { $values
 132   { "parser" parser }
 133   { "quot" { $quotation ( ast -- ast ) } }
 134 }
 135 { $description
 136     "Returns a parser that calls the " { $snippet "parser" } " and applies the quotation to the AST resulting "
 137     "from that parse. The result of the quotation is then used as the final AST. This can be used "
 138     "for manipulating the parse tree to produce a AST better suited for the task at hand rather than "
 139     "the default AST. If the quotation returns " { $link fail } " then the parser fails." }
 140 { $code "CHAR: 0 CHAR: 9 range [ to-digit ] action" } ;
 141
 142 HELP: sp
 143 { $values
 144   { "parser" parser }
 145 }
 146 { $description
 147     "Returns a parser that calls the original " { $snippet "parser" } " after stripping any whitespace "
 148     " from the left of the input string." } ;
 149
 150 HELP: hide
 151 { $values
 152   { "parser" parser }
 153 }
 154 { $description
 155     "Returns a parser that succeeds if the original parser succeeds, but does not "
 156     "put any result in the AST. Useful for ignoring 'syntax' in the AST." }
 157 { $code "\"[\" token hide number \"]\" token hide 3array seq" } ;
 158
 159 HELP: delay
 160 { $values
 161   { "quot" quotation }
 162   { "parser" parser }
 163 }
 164 { $description
 165     "Delays the construction of a parser until it is actually required to parse. This "
 166     "allows for calling a parser that results in a recursive call to itself. The quotation "
 167     "should return the constructed parser and is called the first time the parser is run. "
 168     "The compiled result is memoized for future runs. See " { $link box } " for a word "
 169     "that calls the quotation at compile time." } ;
 170
 171 HELP: box
 172 { $values
 173   { "quot" quotation }
 174   { "parser" parser }
 175 }
 176 { $description
 177     "Delays the construction of a parser until the parser is compiled. The quotation "
 178     "should return the constructed parser and is called when the parser is compiled. "
 179     "The compiled result is memoized for future runs. See " { $link delay } " for a word "
 180     "that calls the quotation at runtime." } ;
 181
 182 HELP: PEG:
 183 { $syntax "PEG: word ( stack -- effect ) definition... ;" }
 184 { $description "Defines a word that when called will parse a string using the syntax"
 185     "defined by the parser created by the definition. The definition should have stack"
 186     "effect " { $snippet "( -- parser )" } " and the created word "
 187     { $snippet "( string -- ast )" } ". In contrast to calling the parser resulting from"
 188     "the definition with " { $link parse } ", the parser is pre-compiled and not compiled"
 189     "for each invocation of " { $link parse } ". If the parsing fails, the word throws an"
 190     "exception." } ;