core/lexer/lexer-docs.factor

   1 IN: lexer
   2 USING: help.markup help.syntax kernel math sequences strings
   3 words quotations ;
   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" "a sequence of strings" } { "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 } { "?" "a 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 "( col line -- 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 } { "?" "a 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
  61 { $values { "str/f" { $maybe string } } }
  62 { $description "Reads the next token from the lexer. See " { $link parse-token } " for details." }
  63 $parsing-note ;
  64
  65 HELP: still-parsing?
  66 { $values { "lexer" lexer } { "?" "a boolean" } }
  67 { $description "Outputs " { $link f } " if end of input has been reached, " { $link t } " otherwise." } ;
  68
  69 HELP: each-token
  70 { $values { "end" string } { "quot" { $quotation "( ... token -- ... )" } } }
  71 { $description "Reads a sequence of tokens until the first occurrence of " { $snippet "end" } ". " { $snippet "quot" } " is called on each token as it is read." }
  72 { $examples "This word is used to implement " { $link POSTPONE: USING: } "." }
  73 $parsing-note ;
  74
  75 HELP: map-tokens
  76 { $values { "end" string } { "quot" { $quotation "( ... token -- ... elt )" } } { "seq" "a new sequence of " { $snippet "object" } "s" } }
  77 { $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." }
  78 $parsing-note ;
  79
  80 HELP: parse-tokens
  81 { $values { "end" string } { "seq" "a new sequence of strings" } }
  82 { $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." }
  83 $parsing-note ;
  84
  85 HELP: unexpected
  86 { $values { "want" { $maybe word } } { "got" word } }
  87 { $description "Throws an " { $link unexpected } " error." }
  88 { $error-description "Thrown by the parser if an unmatched closing delimiter is encountered." }
  89 { $examples
  90     "Parsing the following snippet will throw this error:"
  91     { $code "[ 1 2 3 }" }
  92 } ;
  93
  94 HELP: unexpected-eof
  95 { $values { "word" "a " { $link word } } }
  96 { $description "Throws an " { $link unexpected } " error indicating the parser was looking for an occurrence of " { $snippet "word" } " but encountered end of file." } ;
  97
  98 HELP: with-lexer
  99 { $values { "lexer" lexer } { "quot" quotation } { "newquot" quotation } }
 100 { $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 } ". Any errors thrown by the quotation are wrapped in " { $link lexer-error } " instances." } ;
 101
 102 HELP: lexer-factory
 103 { $var-description "A variable holding a quotation with stack effect " { $snippet "( lines -- lexer )" } ". This quotation is called by the parser to create " { $link lexer } " instances. This variable can be rebound to a quotation which outputs a custom tuple delegating to " { $link lexer } " to customize syntax." } ;
 104
 105
 106 ARTICLE: "parser-lexer" "The lexer"
 107 "A variable that encapsulate internal parser state:"
 108 { $subsections lexer }
 109 "Creating a default lexer:"
 110 { $subsections <lexer> }
 111 "A word to test of the end of input has been reached:"
 112 { $subsections still-parsing? }
 113 "A word to advance the lexer to the next line:"
 114 { $subsections next-line }
 115 "Two generic words to override the lexer's token boundary detection:"
 116 { $subsections
 117     skip-blank
 118     skip-word
 119 }
 120 "Utility combinator:"
 121 { $subsections with-lexer } ;