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