extra/state-parser/state-parser-docs.factor

   1 USING: help.markup help.syntax ;
   2 IN: state-parser
   3
   4 ABOUT: { "state-parser" "main" }
   5
   6 ARTICLE: { "state-parser" "main" } "State-based parsing"
   7     "This module defines a state-based parsing mechanism. It was originally created for libs/xml, but is also used in libs/csv and can be easily used in new libraries or applications."
   8     { $subsection spot }
   9     { $subsection skip-until }
  10     { $subsection take-until }
  11     { $subsection take-char }
  12     { $subsection take-string }
  13     { $subsection next }
  14     { $subsection state-parse }
  15     { $subsection get-char }
  16     { $subsection take-rest }
  17     { $subsection string-parse }
  18     { $subsection expect }
  19     { $subsection expect-string }
  20     { $subsection parsing-error } ;
  21
  22 HELP: get-char
  23 { $values { "char" "the current character" } }
  24 { $description "Accesses the current character of the stream that is being parsed" } ;
  25
  26 HELP: take-rest
  27 { $values { "string" "the rest of the parser input" } }
  28 { $description "Exausts the stream of the parser input and returns a string representing the rest of the input" } ;
  29
  30 HELP: string-parse
  31 { $values { "input" "a string" } { "quot" "a quotation ( -- )" } }
  32 { $description "Calls the given quotation using the given string as parser input" }
  33 { $see-also state-parse } ;
  34
  35 HELP: expect
  36 { $values { "ch" "a number representing a character" } }
  37 { $description "Asserts that the current character is the given ch, and moves to the next spot" }
  38 { $see-also expect-string } ;
  39
  40 HELP: expect-string
  41 { $values { "string" "a string" } }
  42 { $description "Asserts that the current parsing spot is followed by the given string, and skips the parser past that string" }
  43 { $see-also expect } ;
  44
  45 HELP: spot
  46 { $var-description "This variable represents the location in the program. It is a tuple T{ spot f char column line next } where char is the current character, line is the line number, column is the column number, and line-str is the full contents of the line, as a string. The contents shouldn't be accessed directly but rather with the proxy words get-char set-char get-line etc." } ;
  47
  48 HELP: skip-until
  49 { $values { "quot" "a quotation ( -- ? )" } }
  50 { $description "executes " { $link next } " until the quotation yields false. Usually, the quotation will call " { $link get-char } " in its test, but not always." }
  51 { $see-also take-until } ;
  52
  53 HELP: take-until
  54 { $values { "quot" "a quotation ( -- ? )" } { "string" "a string" } }
  55 { $description "like " { $link skip-until } " but records what it passes over and outputs the string." }
  56 { $see-also skip-until take-char take-string } ;
  57
  58 HELP: take-char
  59 { $values { "ch" "a character" } { "string" "a string" } }
  60 { $description "records the document from the current spot to the first instance of the given character. Outputs the content between those two points." }
  61 { $see-also take-until take-string } ;
  62
  63 HELP: take-string
  64 { $values { "match" "a string to match" } { "string" "the portion of the XML document" } }
  65 { $description "records the document from the current spot to the first instance of the given character. Outputs the content between those two points." }
  66 { $notes "match may not contain a newline" } ;
  67
  68 HELP: next
  69 { $description "originally written as " { $code "spot inc" } ", code that would no longer run, this word moves the state of the XML parser to the next place in the source file, keeping track of appropriate debugging information." } ;
  70
  71 HELP: parsing-error
  72 { $class-description "class from which parsing errors inherit, containing information about which line and column the error occured on, and what the line was. Contains three slots, line, an integer, column, another integer, and line-str, a string" } ;