core/lexer/lexer-docs.factor

   1 USING: help.markup help.syntax kernel math sequences strings
   2 words quotations ;
   3 IN: lexer
   4
   5 HELP: lexer
   6 { $var-description "Stores the current " { $link lexer } " instance." }
   7 { $class-description "An object for tokenizing parser input. It has the following slots:"
   8     { $list
   9         { { $snippet "text" } " - the lines being parsed; an array of strings" }
  10         { { $snippet "line" } " - the line number being parsed; unlike most indices this is 1-based for friendlier error reporting and integration with text editors" }
  11         { { $snippet "column" } " - the current column position, zero-based" }
  12     }
  13 "Custom lexing can be implemented by delegating a tuple to an instance of this class and implementing the " { $link skip-word } " and " { $link skip-blank } " generic words." } ;
  14
  15 HELP: <lexer>
  16 { $values { "text" { $sequence string } } { "lexer" lexer } }
  17 { $description "Creates a new lexer for tokenizing the given sequence of lines." } ;
  18
  19 HELP: next-line
  20 { $values { "lexer" lexer } }
  21 { $description "Advances the lexer to the next input line, discarding the remainder of the current line." } ;
  22
  23 HELP: lexer-error
  24 { $error-description "Thrown when the lexer encounters invalid input. A lexer error wraps an underlying error together with line and column numbers." } ;
  25
  26 HELP: <lexer-error>
  27 { $values { "msg" "an error" } { "error" lexer-error } }
  28 { $description "Creates a new " { $link lexer-error } ", filling in the location information from the current " { $link lexer } "." } ;
  29
  30 HELP: skip
  31 { $values { "i" "a starting index" } { "seq" sequence } { "?" boolean } { "n" integer } }
  32 { $description "Skips to the first space character (if " { $snippet "boolean" } " is " { $link f } ") or the first non-space character (otherwise). Tabulations used as separators instead of spaces will be flagged as an error." } ;
  33
  34 HELP: change-lexer-column
  35 { $values { "lexer" lexer } { "quot" { $quotation ( ..a col line -- ..b newcol ) } } }
  36 { $description "Applies a quotation to the current column and line text to produce a new column, and moves the lexer position." } ;
  37
  38 HELP: skip-blank
  39 { $values { "lexer" lexer } }
  40 { $contract "Skips whitespace characters." }
  41 { $notes "Custom lexers can implement this generic word." } ;
  42
  43 HELP: skip-word
  44 { $values { "lexer" lexer } }
  45 { $contract
  46     "Skips until the end of the current token."
  47     $nl
  48     "The default implementation treats a single " { $snippet "\"" } " as a word by itself; otherwise it searches forward until a whitespace character or the end of the line."
  49 }
  50 { $notes "Custom lexers can implement this generic word." } ;
  51
  52 HELP: still-parsing-line?
  53 { $values { "lexer" lexer } { "?" boolean } }
  54 { $description "Outputs " { $link f } " if the end of the current line has been reached, " { $link t } " otherwise." } ;
  55
  56 HELP: parse-token
  57 { $values { "lexer" lexer } { "str/f" { $maybe string } } }
  58 { $description "Reads the next token from the lexer. Tokens are delimited by whitespace, with the exception that " { $snippet "\"" } " is treated like a single token even when not followed by whitespace." } ;
  59
  60 HELP: ?scan-token
  61 { $values { "str/f" { $maybe string } } }
  62 { $description "Reads the next token from the lexer. Tokens are delimited by whitespace, with the exception that " { $snippet "\"" } " is treated like a single token even when not followed by whitespace. This word outputs " { $link f } " on end of input. To throw an error on end of input, use " { $link scan-token } " instead." }
  63 $parsing-note ;
  64
  65 HELP: scan-token
  66 { $values { "str" string } }
  67 { $description "Reads the next token from the lexer. Tokens are delimited by whitespace, with the exception that " { $snippet "\"" } " is treated like a single token even when not followed by whitespace. This word throws " { $link unexpected-eof } " on end of input. To output " { $link f } " on end of input, use " { $link ?scan-token } " instead." }
  68 $parsing-note ;
  69
  70 HELP: still-parsing?
  71 { $values { "lexer" lexer } { "?" boolean } }
  72 { $description "Outputs " { $link f } " if end of input has been reached, " { $link t } " otherwise." } ;
  73
  74 HELP: each-token
  75 { $values { "end" string } { "quot" { $quotation ( ... token -- ... ) } } }
  76 { $description "Reads a sequence of tokens until the first occurrence of " { $snippet "end" } ". " { $snippet "quot" } " is called on each token as it is read." }
  77 { $examples "This word is used to implement " { $link POSTPONE: USING: } "." }
  78 $parsing-note ;
  79
  80 HELP: map-tokens
  81 { $values { "end" string } { "quot" { $quotation ( ... token -- ... elt ) } } { "seq" { $sequence object } } }
  82 { $description "Reads a sequence of tokens until the first occurrence of " { $snippet "end" } ". " { $snippet "quot" } " is called on each token as it is read, and the results are collected into a new output sequence." }
  83 $parsing-note ;
  84
  85 HELP: parse-tokens
  86 { $values { "end" string } { "seq" { $sequence string } } }
  87 { $description "Reads a sequence of tokens until the first occurrence of " { $snippet "end" } ". The tokens remain as strings and are not processed in any way. This word is equivalent to " { $link map-tokens } " with an empty quotation." }
  88 $parsing-note ;
  89
  90 HELP: unexpected
  91 { $values { "want" { $maybe word } } { "got" word } }
  92 { $description "Throws an " { $link unexpected } " error." }
  93 { $error-description "Thrown by the parser if an unmatched closing delimiter is encountered." }
  94 { $examples
  95     "Parsing the following snippet will throw this error:"
  96     { $code "[ 1 2 3 }" }
  97 } ;
  98
  99 HELP: unexpected-eof
 100 { $values { "word" "a " { $link word } } }
 101 { $description "Throws an " { $link unexpected } " error indicating the parser was looking for an occurrence of " { $snippet "word" } " but encountered end of file." } ;
 102
 103 HELP: with-lexer
 104 { $values { "lexer" lexer } { "quot" quotation } { "newquot" quotation } }
 105 { $description "Calls the quotation with the " { $link lexer } " variable set to the given lexer. The quotation can make use of words such as " { $link scan-token } ". Any errors thrown by the quotation are wrapped in " { $link lexer-error } " instances." } ;
 106
 107 ARTICLE: "parser-lexer" "The lexer"
 108 "A variable that encapsulate internal parser state:"
 109 { $subsections lexer }
 110 "Creating a default lexer:"
 111 { $subsections <lexer> }
 112 "A word to test of the end of input has been reached:"
 113 { $subsections still-parsing? }
 114 "A word to advance the lexer to the next line:"
 115 { $subsections next-line }
 116 "Two generic words to override the lexer's token boundary detection:"
 117 { $subsections
 118     skip-blank
 119     skip-word
 120 }
 121 "Utility combinator:"
 122 { $subsections with-lexer } ;