core/vocabs/parser/parser-docs.factor

   1 USING: help.markup help.syntax parser strings words ;
   2 IN: vocabs.parser
   3
   4 ARTICLE: "vocabulary-search-shadow" "Shadowing word names"
   5 "If adding a vocabulary to the search path results in a word in another vocabulary becoming inaccessible due to the new vocabulary defining a word with the same name, we say that the old word has been " { $emphasis "shadowed" } "."
   6 $nl
   7 "Here is an example where shadowing occurs:"
   8 { $code
   9     "IN: foe"
  10     "USING: sequences io ;"
  11     ""
  12     ": append"
  13     "    \"foe::append calls sequences:append\" print  append ;"
  14     ""
  15     "IN: fee"
  16     ""
  17     ": append"
  18     "    \"fee::append calls fee:append\" print  append ;"
  19     ""
  20     "IN: fox"
  21     "USE: foe"
  22     ""
  23     ": append"
  24     "    \"fox::append calls foe:append\" print  append ;"
  25     ""
  26     "\"1234\" \"5678\" append print"
  27     ""
  28     "USE: fox"
  29     "\"1234\" \"5678\" append print"
  30 }
  31 "When placed in a source file and run, the above code produces the following output:"
  32 { $code
  33     "foe:append calls sequences:append"
  34     "12345678"
  35     "fee:append calls foe:append"
  36     "foe:append calls sequences:append"
  37     "12345678"
  38 } ;
  39
  40 ARTICLE: "vocabulary-search-errors"  "Word lookup errors"
  41 "If the parser cannot not find a word in the current vocabulary search path, it attempts to look for the word in all loaded vocabularies."
  42 $nl
  43 "If " { $link auto-use? } " mode is off, a restartable error is thrown with a restart for each vocabulary in question, together with a restart which defers the word in the current vocabulary, as if " { $link POSTPONE: DEFER: } " was used."
  44 $nl
  45 "If " { $link auto-use? } " mode is on and only one vocabulary has a word with this name, the vocabulary is added to the search path and parsing continues."
  46 $nl
  47 "If any restarts were invoked, or if " { $link auto-use? } " is on, the parser will print the correct " { $link POSTPONE: USING: } " after parsing completes. This form can be copy and pasted back into the source file."
  48 { $subsection auto-use? } ;
  49
  50 ARTICLE: "vocabulary-search" "Vocabulary search path"
  51 "When the parser reads a token, it attempts to look up a word named by that token. The lookup is performed by searching each vocabulary in the search path, in order."
  52 $nl
  53 "For a source file the vocabulary search path starts off with one vocabulary:"
  54 { $code "syntax" }
  55 "The " { $vocab-link "syntax" } " vocabulary consists of a set of parsing words for reading Factor data and defining new words."
  56 $nl
  57 "In the listener, the " { $vocab-link "scratchpad" } " is the default vocabulary for new word definitions. However, when loading source files, there is no default vocabulary. Defining words before declaring a vocabulary with " { $link POSTPONE: IN: } " results in an error."
  58 $nl
  59 "At the interactive listener, the default search path contains many more vocabularies. Details on the default search path and parser invocation are found in " { $link "parser" } "."
  60 $nl
  61 "Three parsing words deal with the vocabulary search path:"
  62 { $subsection POSTPONE: IN: }
  63 { $subsection POSTPONE: USE: }
  64 { $subsection POSTPONE: USING: }
  65 "There are some additional parsing words give more control over word lookup than is offered by " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } ":"
  66 { $subsection POSTPONE: QUALIFIED: }
  67 { $subsection POSTPONE: QUALIFIED-WITH: }
  68 { $subsection POSTPONE: FROM: }
  69 { $subsection POSTPONE: EXCLUDE: }
  70 { $subsection POSTPONE: RENAME: }
  71 "These words are useful when there is no way to avoid using two vocabularies with identical word names in the same source file."
  72 $nl
  73 "Private words can be defined; note that this is just a convention and they can be called from other vocabularies anyway:"
  74 { $subsection POSTPONE: <PRIVATE }
  75 { $subsection POSTPONE: PRIVATE> }
  76 { $subsection "vocabulary-search-errors" }
  77 { $subsection "vocabulary-search-shadow" }
  78 { $see-also "words" } ;
  79
  80 ABOUT: "vocabulary-search"
  81
  82 HELP: use
  83 { $var-description "A variable holding the current vocabulary search path as a sequence of assocs." } ;
  84
  85 HELP: in
  86 { $var-description "A variable holding the name of the current vocabulary for new definitions." } ;
  87
  88 HELP: current-vocab
  89 { $values { "str" "a vocabulary" } }
  90 { $description "Returns the vocabulary stored in the " { $link in } " symbol. Throws an error if the current vocabulary is " { $link f } "." } ;
  91
  92 HELP: (add-use)
  93 { $values { "vocab" "an assoc mapping strings to words" } }
  94 { $description "Adds an assoc at the front of the search path." }
  95 $parsing-note ;
  96
  97 HELP: add-use
  98 { $values { "vocab" string } }
  99 { $description "Adds a new vocabulary at the front of the search path after loading it if necessary. Subsequent word lookups by the parser will search this vocabulary first." }
 100 $parsing-note
 101 { $errors "Throws an error if the vocabulary does not exist." } ;
 102
 103 HELP: set-use
 104 { $values { "seq" "a sequence of strings" } }
 105 { $description "Sets the vocabulary search path. Later vocabularies take precedence." }
 106 { $errors "Throws an error if one of the vocabularies does not exist." }
 107 $parsing-note ;
 108
 109 HELP: set-in
 110 { $values { "name" string } }
 111 { $description "Sets the current vocabulary where new words will be defined, creating the vocabulary first if it does not exist." }
 112 $parsing-note ;
 113
 114 HELP: search
 115 { $values { "str" string } { "word/f" { $maybe word } } }
 116 { $description "Searches for a word by name in the current vocabulary search path. If no such word could be found, outputs " { $link f } "." }
 117 $parsing-note ;