basis/peg/peg-docs.factor

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