core/vocabs/parser/parser-docs.factor

   1 USING: help.markup help.syntax parser ;
   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 "The " { $vocab-link "qualified" } " vocabulary contains some tools for helping with shadowing." ;
  40
  41 ARTICLE: "vocabulary-search-errors"  "Word lookup errors"
  42 "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."
  43 $nl
  44 "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."
  45 $nl
  46 "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."
  47 $nl
  48 "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."
  49 { $subsection auto-use? } ;
  50
  51 ARTICLE: "vocabulary-search" "Vocabulary search path"
  52 "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."
  53 $nl
  54 "For a source file the vocabulary search path starts off with one vocabulary:"
  55 { $code "syntax" }
  56 "The " { $vocab-link "syntax" } " vocabulary consists of a set of parsing words for reading Factor data and defining new words."
  57 $nl
  58 "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."
  59 $nl
  60 "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" } "."
  61 $nl
  62 "Three parsing words deal with the vocabulary search path:"
  63 { $subsection POSTPONE: IN: }
  64 { $subsection POSTPONE: USE: }
  65 { $subsection POSTPONE: USING: }
  66 "There are some additional parsing words give more control over word lookup than is offered by " { $link POSTPONE: USE: } " and " { $link POSTPONE: USING: } ":"
  67 { $subsection POSTPONE: QUALIFIED: }
  68 { $subsection POSTPONE: QUALIFIED-WITH: }
  69 { $subsection POSTPONE: FROM: }
  70 { $subsection POSTPONE: EXCLUDE: }
  71 { $subsection POSTPONE: RENAME: }
  72 "These words are useful when there is no way to avoid using two vocabularies with identical word names in the same source file."
  73 $nl
  74 "Private words can be defined; note that this is just a convention and they can be called from other vocabularies anyway:"
  75 { $subsection POSTPONE: <PRIVATE }
  76 { $subsection POSTPONE: PRIVATE> }
  77 { $subsection "vocabulary-search-errors" }
  78 { $subsection "vocabulary-search-shadow" }
  79 { $see-also "words" } ;
  80
  81 ABOUT: "vocabulary-search"