basis/peg/parsers/parsers-docs.factor

   1 ! Copyright (C) 2008 Chris Double, Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax peg peg.parsers.private
   4 unicode.categories ;
   5 IN: peg.parsers
   6
   7 HELP: 1token
   8 { $values
   9     { "ch" "a character" }
  10     { "parser" "a parser" }
  11 } { $description
  12     "Calls 1string on a character and returns a parser that matches that character."
  13 } { $examples
  14     { $example "USING: peg peg.parsers prettyprint ;" "\"a\" CHAR: a 1token parse ." "\"a\"" }
  15 } { $see-also 'string' } ;
  16
  17 HELP: (list-of)
  18 { $values
  19     { "items" "a sequence" }
  20     { "separator" "a parser" }
  21     { "repeat1?" "a boolean" }
  22     { "parser" "a parser" }
  23 } { $description
  24     "Returns a parser that returns a list of items separated by the separator parser.  Does not hide the separators."
  25 } { $see-also list-of list-of-many } ;
  26
  27 HELP: list-of
  28 { $values
  29     { "items" "a sequence" }
  30     { "separator" "a parser" }
  31     { "parser" "a parser" }
  32 } { $description
  33     "Returns a parser that returns a list of items separated by the separator parser.  Hides the separators and matches a list of one or more items."
  34 } { $notes "Use " { $link list-of-many } " to ensure a list contains two or more items." }
  35 { $examples
  36     { $example "USING: peg peg.parsers prettyprint ;" "\"a\" \"a\" token \",\" token list-of parse  ." "V{ \"a\" }" }
  37     { $example "USING: peg peg.parsers prettyprint ;" "\"a,a,a,a\" \"a\" token \",\" token list-of parse ." "V{ \"a\" \"a\" \"a\" \"a\" }" }
  38 } { $see-also list-of-many } ;
  39
  40 HELP: list-of-many
  41 { $values
  42     { "items" "a sequence" }
  43     { "separator" "a parser" }
  44     { "parser" "a parser" }
  45 } { $description
  46     "Returns a parser that returns a list of items separated by the separator parser.  Hides the separators and matches a list of two or more items."
  47 } { $notes "Use " { $link list-of } " to return a list of only one item."
  48 } { $examples
  49     { $code "USING: peg peg.parsers prettyprint ;" "\"a\" \"a\" token \",\" token list-of-many parse => exception" }
  50     { $example "USING: peg peg.parsers prettyprint ;" "\"a,a,a,a\" \"a\" token \",\" token list-of-many parse ." "V{ \"a\" \"a\" \"a\" \"a\" }" }
  51 } { $see-also list-of } ;
  52
  53 HELP: epsilon
  54 { $values
  55     { "parser" "a parser" }
  56 } { $description
  57     "Returns a parser that matches the empty sequence."
  58 } ;
  59
  60 HELP: any-char
  61 { $values
  62     { "parser" "a parser" }
  63 } { $description
  64     "Returns a parser that matches the any single character."
  65 } ;
  66
  67 HELP: exactly-n
  68 { $values
  69     { "parser" "a parser" }
  70     { "n" "an integer" }
  71     { "parser'" "a parser" }
  72 } { $description
  73     "Returns a parser that matches an exact repetition of the input parser."
  74 } { $examples
  75     { $code "USING: peg peg.parsers prettyprint ;" "\"aaa\" \"a\" token 4 exactly-n parse => exception" }
  76     { $example "USING: peg peg.parsers prettyprint ;" "\"aaaa\" \"a\" token 4 exactly-n parse ." "V{ \"a\" \"a\" \"a\" \"a\" }" }
  77 } { $see-also at-least-n at-most-n from-m-to-n } ;
  78
  79 HELP: at-least-n
  80 { $values
  81     { "parser" "a parser" }
  82     { "n" "an integer" }
  83     { "parser'" "a parser" }
  84 } { $description
  85     "Returns a parser that matches n or more repetitions of the input parser."
  86 } { $examples
  87     { $code "USING: peg peg.parsers prettyprint ;" "\"aaa\" \"a\" token 4 at-least-n parse => exception"}
  88     { $example "USING: peg peg.parsers prettyprint ;" "\"aaaa\" \"a\" token 4 at-least-n parse ." "V{ \"a\" \"a\" \"a\" \"a\" }" }
  89     { $example "USING: peg peg.parsers prettyprint ;" "\"aaaaa\" \"a\" token 4 at-least-n parse ." "V{ \"a\" \"a\" \"a\" \"a\" \"a\" }" }
  90 } { $see-also exactly-n at-most-n from-m-to-n } ;
  91
  92 HELP: at-most-n
  93 { $values
  94     { "parser" "a parser" }
  95     { "n" "an integer" }
  96     { "parser'" "a parser" }
  97 } { $description
  98     "Returns a parser that matches n or fewer repetitions of the input parser."
  99 } { $examples
 100     { $example "USING: peg peg.parsers prettyprint ;" "\"aaaa\" \"a\" token 4 at-most-n parse ." "V{ \"a\" \"a\" \"a\" \"a\" }" }
 101     { $example "USING: peg peg.parsers prettyprint ;" "\"aaaaa\" \"a\" token 4 at-most-n parse ." "V{ \"a\" \"a\" \"a\" \"a\" }" }
 102 } { $see-also exactly-n at-least-n from-m-to-n } ;
 103
 104 HELP: from-m-to-n
 105 { $values
 106     { "parser" "a parser" }
 107     { "m" "an integer" }
 108     { "n" "an integer" }
 109     { "parser'" "a parser" }
 110 } { $description
 111     "Returns a parser that matches between and including m to n repetitions of the input parser."
 112 } { $examples
 113     { $example "USING: peg peg.parsers prettyprint ;" "\"aaa\" \"a\" token 3 4 from-m-to-n parse ." "V{ \"a\" \"a\" \"a\" }" }
 114     { $example "USING: peg peg.parsers prettyprint ;" "\"aaaa\" \"a\" token 3 4 from-m-to-n parse ." "V{ \"a\" \"a\" \"a\" \"a\" }" }
 115     { $example "USING: peg peg.parsers prettyprint ;" "\"aaaaa\" \"a\" token 3 4 from-m-to-n parse ." "V{ \"a\" \"a\" \"a\" \"a\" }" }
 116 } { $see-also exactly-n at-most-n at-least-n } ;
 117
 118 HELP: pack
 119 { $values
 120     { "begin" "a parser" }
 121     { "body" "a parser" }
 122     { "end" "a parser" }
 123     { "parser" "a parser" }
 124 } { $description
 125     "Returns a parser that parses the begin, body, and end parsers in order.  The begin and end parsers are hidden."
 126 } { $examples
 127     { $example "USING: peg peg.parsers prettyprint ;" "\"hi123bye\" \"hi\" token 'integer' \"bye\" token pack parse ." "123" }
 128 } { $see-also surrounded-by } ;
 129
 130 HELP: surrounded-by
 131 { $values
 132     { "parser" "a parser" }
 133     { "begin" "a string" }
 134     { "end" "a string" }
 135     { "parser'" "a parser" }
 136 } { $description
 137     "Calls token on begin and end to make them into string parsers.  Returns a parser that parses the begin, body, and end parsers in order.  The begin and end parsers are hidden."
 138 } { $examples
 139     { $example "USING: peg peg.parsers prettyprint ;" "\"hi123bye\" 'integer' \"hi\" \"bye\" surrounded-by parse ." "123" }
 140 } { $see-also pack } ;
 141
 142 HELP: 'digit'
 143 { $values
 144     { "parser" "a parser" }
 145 } { $description
 146     "Returns a parser that matches a single digit as defined by the " { $link digit? } " word."
 147 } { $see-also 'integer' } ;
 148
 149 HELP: 'integer'
 150 { $values
 151     { "parser" "a parser" }
 152 } { $description
 153     "Returns a parser that matches an integer composed of digits, as defined by the " { $link 'digit' } " word."
 154 } { $see-also 'digit' 'string' } ;
 155
 156 HELP: 'string'
 157 { $values
 158     { "parser" "a parser" }
 159 } { $description
 160     "Returns a parser that matches an string composed of a \", anything that is not \", and another \"."
 161 } { $see-also 'integer' } ;
 162
 163 HELP: range-pattern
 164 { $values
 165     { "pattern" "a string" }
 166     { "parser" "a parser" }
 167 } { $description
 168 "Returns a parser that matches a single character based on the set "
 169 "of characters in the pattern string."
 170 "Any single character in the pattern matches that character. "
 171 "If the pattern begins with a ^ then the set is negated "
 172 "(the element matches any character not in the set). Any pair "
 173 "of characters separated with a dash (-) represents the "
 174 "range of characters from the first to the second, inclusive."
 175 { $examples
 176     { $example "USING: peg peg.parsers prettyprint strings ;" "\"a\" \"_a-zA-Z\" range-pattern parse 1string ." "\"a\"" }
 177     { $code "USING: peg peg.parsers prettyprint ;\n\"0\" \"^0-9\" range-pattern parse => exception"}
 178 }
 179 }  ;