extra/sequences/parser/parser-docs.factor

   1 ! Copyright (C) 2024 Aleksander Sabak.
   2 ! See https://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.markup help.syntax kernel math quotations sequences
   4 sequences.parser ;
   5 IN: sequences.parser
   6
   7 HELP: <safe-slice>
   8 { $values
   9     { "from" integer } { "to" integer } { "seq" sequence }
  10     { "slice/f" { $maybe slice } }
  11 } ;
  12
  13 HELP: <sequence-parser>
  14 { $values
  15     { "sequence" sequence }
  16     { "sequence-parser" sequence-parser }
  17 }
  18 { $description
  19   "Creates a new sequence-parser parsing " { $snippet "sequence" } "."
  20 }
  21 { $see-also advance current offset }
  22 ;
  23
  24 { advance current consume next offset } related-words
  25
  26 HELP: advance
  27 { $values
  28     { "sequence-parser" sequence-parser }
  29 }
  30 { $description "Advances the parser by one element." } ;
  31
  32 HELP: consume
  33 { $values
  34     { "sequence-parser" sequence-parser }
  35     { "obj/f" { $maybe object } }
  36 }
  37 { $description "Returns the current element and advances the parser." } ;
  38
  39 HELP: current
  40 { $values
  41     { "sequence-parser" sequence-parser }
  42     { "obj/f" { $maybe object } }
  43 }
  44 { $description "Returns the current element." } ;
  45
  46 HELP: next
  47 { $values
  48     { "sequence-parser" sequence-parser }
  49     { "obj/f" { $maybe object } }
  50 }
  51 { $description "Advances the parser and returns the new current element." } ;
  52
  53 HELP: offset
  54 { $values
  55     { "sequence-parser" sequence-parser } { "offset" object }
  56     { "obj/f" { $maybe object } }
  57 }
  58 { $description "Return the element of the parsed sequence offset from the current position of the parser. Negative offsets will yield already parsed elements." } ;
  59
  60 { parse-sequence with-sequence-parser } related-words
  61
  62 HELP: parse-sequence
  63 { $values
  64     { "sequence" sequence } { "quot" { $quotation ( ..a parser -- ..b ) } }
  65 }
  66 { $description "Runs the quotation on a sequence-parser parsing the " { $snippet "sequence" } "." } ;
  67
  68 HELP: peek-next
  69 { $values
  70     { "sequence-parser" sequence-parser }
  71     { "obj/f" { $maybe object } }
  72 }
  73 { $description "Return the element of the sequence after the current position of the parser." } ;
  74
  75 HELP: previous
  76 { $values
  77     { "sequence-parser" sequence-parser }
  78     { "obj/f" { $maybe object } }
  79 }
  80 { $description "Return the element of the sequence before the current position of the parser." } ;
  81
  82 HELP: sequence-parse-end?
  83 { $values
  84     { "sequence-parser" sequence-parser }
  85     { "?" boolean }
  86 }
  87 { $description "Retruns " { $link POSTPONE: t } " if the parser has exhausted the sequence, otherwise " { $link POSTPONE: f } "." } ;
  88
  89 HELP: sequence-parser
  90 { $class-description "A class for keeping the state of a parser on a sequence." }
  91 { $see-also <sequence-parser> }
  92 ;
  93
  94 HELP: skip-until
  95 { $values
  96     { "sequence-parser" sequence-parser } { "quot" quotation }
  97 } ;
  98
  99 HELP: skip-whitespace
 100 { $values
 101     { "sequence-parser" sequence-parser }
 102 } ;
 103
 104 HELP: skip-whitespace-eol
 105 { $values
 106     { "sequence-parser" sequence-parser }
 107 } ;
 108
 109 HELP: sort-tokens
 110 { $values
 111     { "seq" sequence }
 112     { "seq'" sequence }
 113 } ;
 114
 115 HELP: take-first-matching
 116 { $values
 117     { "sequence-parser" sequence-parser } { "seq" sequence }
 118 } ;
 119
 120 HELP: take-integer
 121 { $values
 122     { "sequence-parser" sequence-parser }
 123     { "n/f" { $maybe integer } }
 124 } ;
 125
 126 HELP: take-longest
 127 { $values
 128     { "sequence-parser" sequence-parser } { "seq" sequence }
 129 } ;
 130
 131 HELP: take-n
 132 { $values
 133     { "sequence-parser" sequence-parser } { "n" integer }
 134     { "seq/f" { $maybe sequence } }
 135 } ;
 136
 137 HELP: take-rest
 138 { $values
 139     { "sequence-parser" sequence-parser }
 140     { "sequence" sequence }
 141 } ;
 142
 143 HELP: take-rest-slice
 144 { $values
 145     { "sequence-parser" sequence-parser }
 146     { "sequence/f" { $maybe sequence } }
 147 } ;
 148
 149 HELP: take-sequence
 150 { $values
 151     { "sequence-parser" sequence-parser } { "sequence" sequence }
 152     { "obj/f" { $maybe object } }
 153 } ;
 154
 155 HELP: take-sequence*
 156 { $values
 157     { "sequence-parser" sequence-parser } { "sequence" sequence }
 158 } ;
 159
 160 HELP: take-until
 161 { $values
 162     { "sequence-parser" sequence-parser } { "quot" quotation }
 163     { "sequence/f" { $maybe sequence } }
 164 } ;
 165
 166 HELP: take-until-object
 167 { $values
 168     { "sequence-parser" sequence-parser } { "obj" object }
 169     { "sequence" sequence }
 170 } ;
 171
 172 HELP: take-until-sequence
 173 { $values
 174     { "sequence-parser" sequence-parser } { "sequence" sequence }
 175     { "sequence'/f" { $maybe sequence } }
 176 } ;
 177
 178 HELP: take-until-sequence*
 179 { $values
 180     { "sequence-parser" sequence-parser } { "sequence" sequence }
 181     { "sequence'/f" { $maybe sequence } }
 182 } ;
 183
 184 HELP: take-while
 185 { $values
 186     { "sequence-parser" sequence-parser } { "quot" quotation }
 187     { "sequence/f" { $maybe sequence } }
 188 } ;
 189
 190 HELP: with-sequence-parser
 191 { $values
 192     { "sequence-parser" sequence-parser } { "quot" { $quotation ( ..a parser -- ..b obj/f ) } }
 193     { "obj/f" { $maybe object } }
 194 }
 195 { $description "Saves the position of the parser and calls the quotation on it. If the quotation returns " { $link POSTPONE: f } " the parser is rewound to the saved position." } ;
 196
 197 HELP: write-full
 198 { $values
 199     { "sequence-parser" sequence-parser }
 200 } ;
 201
 202 HELP: write-rest
 203 { $values
 204     { "sequence-parser" sequence-parser }
 205 } ;
 206
 207 ARTICLE: "sequences.parser" "Sequence parser"
 208 { $vocab-link "sequences.parser" }
 209 ;
 210
 211 ABOUT: "sequences.parser"