core/namespaces/namespaces-docs.factor

   1 USING: help.markup help.syntax kernel kernel.private
   2 sequences words namespaces.private quotations vectors
   3 math.parser math ;
   4 IN: namespaces
   5
   6 ARTICLE: "namespaces-combinators" "Namespace combinators"
   7 { $subsection make-assoc }
   8 { $subsection with-scope }
   9 { $subsection with-variable }
  10 { $subsection bind } ;
  11
  12 ARTICLE: "namespaces-change" "Changing variable values"
  13 { $subsection on }
  14 { $subsection off }
  15 { $subsection inc }
  16 { $subsection dec }
  17 { $subsection change } ;
  18
  19 ARTICLE: "namespaces-global" "Global variables"
  20 { $subsection namespace }
  21 { $subsection global }
  22 { $subsection get-global }
  23 { $subsection set-global } ;
  24
  25 ARTICLE: "namespaces.private" "Namespace implementation details"
  26 "The namestack holds namespaces."
  27 { $subsection namestack }
  28 { $subsection set-namestack }
  29 { $subsection namespace }
  30 "A pair of words push and pop namespaces on the namestack."
  31 { $subsection >n }
  32 { $subsection ndrop } ;
  33
  34 ARTICLE: "namespaces" "Variables and namespaces"
  35 "The " { $vocab-link "namespaces" } " vocabulary implements simple dynamically-scoped variables."
  36 $nl
  37 "A variable is an entry in an assoc of bindings, where the assoc is implicit rather than passed on the stack. These assocs are termed " { $emphasis "namespaces" } ". Nesting of scopes is implemented with a search order on namespaces, defined by a " { $emphasis "namestack" } ". Since namespaces are just assoc, any object can be used as a variable, however by convention, variables are keyed by symbols (see " { $link "symbols" } ")."
  38 $nl
  39 "The " { $link get } " and " { $link set } " words read and write variable values. The " { $link get } " word searches up the chain of nested namespaces, while " { $link set } " always sets variable values in the current namespace only. Namespaces are dynamically scoped; when a quotation is called from a nested scope, any words called by the quotation also execute in that scope."
  40 { $subsection get }
  41 { $subsection set }
  42 "Various utility words abstract away common variable access patterns:"
  43 { $subsection "namespaces-change" }
  44 { $subsection "namespaces-combinators" }
  45 { $subsection "namespaces-global" }
  46 "Implementation details your code probably does not care about:"
  47 { $subsection "namespaces.private" }
  48 "An alternative to dynamic scope is lexical scope. Lexically-scoped values and closures are implemented in the " { $vocab-link "locals" } " vocabulary." ;
  49
  50 ABOUT: "namespaces"
  51
  52 HELP: get
  53 { $values { "variable" "a variable, by convention a symbol" } { "value" "the value, or " { $link f } } }
  54 { $description "Searches the name stack for a namespace containing the variable, and outputs the associated value. If no such namespace is found, outputs " { $link f } "." } ;
  55
  56 HELP: set
  57 { $values { "value" "the new value" } { "variable" "a variable, by convention a symbol" } }
  58 { $description "Assigns a value to the variable in the namespace at the top of the name stack." }
  59 { $side-effects "variable" } ;
  60
  61 HELP: off
  62 { $values { "variable" "a variable, by convention a symbol" } }
  63 { $description "Assigns a value of " { $link f } " to the variable." }
  64 { $side-effects "variable" } ;
  65
  66 HELP: on
  67 { $values { "variable" "a variable, by convention a symbol" } }
  68 { $description "Assigns a value of " { $link t } " to the variable." }
  69 { $side-effects "variable" } ;
  70
  71 HELP: change
  72 { $values { "variable" "a variable, by convention a symbol" } { "quot" "a quotation with stack effect " { $snippet "( old -- new )" } } }
  73 { $description "Applies the quotation to the old value of the variable, and assigns the resulting value to the variable." }
  74 { $side-effects "variable" } ;
  75
  76 HELP: +@
  77 { $values { "n" "a number" } { "variable" "a variable, by convention a symbol" } }
  78 { $description "Adds " { $snippet "n" } " to the value of the variable. A variable value of " { $link f } " is interpreted as being zero." }
  79 { $side-effects "variable" }
  80 { $examples
  81     { $example "USING: namespaces prettyprint ;" "IN: scratchpad" "SYMBOL: foo\n1 foo +@\n10 foo +@\nfoo get ." "11" }
  82 } ;
  83
  84 HELP: inc
  85 { $values { "variable" "a variable, by convention a symbol" } }
  86 { $description "Increments the value of the variable by 1. A variable value of " { $link f } " is interpreted as being zero." }
  87 { $side-effects "variable" } ;
  88
  89 HELP: dec
  90 { $values { "variable" "a variable, by convention a symbol" } }
  91 { $description "Decrements the value of the variable by 1. A variable value of " { $link f } " is interpreted as being zero." }
  92 { $side-effects "variable" } ;
  93
  94 HELP: counter
  95 { $values { "variable" "a variable, by convention a symbol" } { "n" integer } }
  96 { $description "Increments the value of the variable by 1, and returns its new value." }
  97 { $notes "This word is useful for generating (somewhat) unique identifiers. For example, the " { $link gensym } " word uses it." }
  98 { $side-effects "variable" } ;
  99
 100 HELP: with-scope
 101 { $values { "quot" quotation } }
 102 { $description "Calls the quotation in a new namespace. Any variables set by the quotation are discarded when it returns." } ;
 103
 104 HELP: with-variable
 105 { $values { "value" object } { "key" "a variable, by convention a symbol" } { "quot" quotation } }
 106 { $description "Calls the quotation in a new namespace where " { $snippet "key" } " is set to " { $snippet "value" } "." }
 107 { $examples "The following two phrases are equivalent:"
 108     { $code "[ 3 x set foo ] with-scope" }
 109     { $code "3 x [ foo ] with-variable" }
 110 } ;
 111
 112 HELP: make-assoc
 113 { $values { "quot" quotation } { "exemplar" "an assoc" } { "hash" "a new hashtable" } }
 114 { $description "Calls the quotation in a new namespace of the same type as " { $snippet "exemplar" } ", and outputs this namespace when the quotation returns. Useful for quickly building assocs." } ;
 115
 116 HELP: bind
 117 { $values { "ns" "a hashtable" } { "quot" quotation } }
 118 { $description "Calls the quotation in the dynamic scope of " { $snippet "ns" } ". When variables are looked up by the quotation, " { $snippet "ns" } " is checked first, and setting variables in the quotation stores them in " { $snippet "ns" } "." } ;
 119
 120 HELP: namespace
 121 { $values { "namespace" "an assoc" } }
 122 { $description "Outputs the current namespace. Calls to " { $link set } " modify this namespace." } ;
 123
 124 HELP: global
 125 { $values { "g" "an assoc" } }
 126 { $description "Outputs the global namespace. The global namespace is always checked last when looking up variable values." } ;
 127
 128 HELP: get-global
 129 { $values { "variable" "a variable, by convention a symbol" } { "value" "the value" } }
 130 { $description "Outputs the value of a variable in the global namespace." } ;
 131
 132 HELP: set-global
 133 { $values { "value" "the new value" } { "variable" "a variable, by convention a symbol" } }
 134 { $description "Assigns a value to the variable in the global namespace." }
 135 { $side-effects "variable" } ;
 136
 137 HELP: namestack*
 138 { $values { "namestack" "a vector of assocs" } }
 139 { $description "Outputs the current name stack." } ;
 140
 141 HELP: namestack
 142 { $values { "namestack" "a vector of assocs" } }
 143 { $description "Outputs a copy of the current name stack." } ;
 144
 145 HELP: set-namestack
 146 { $values { "namestack" "a vector of assocs" } }
 147 { $description "Replaces the name stack with a copy of the given vector." } ;
 148
 149 HELP: >n
 150 { $values { "namespace" "an assoc" } }
 151 { $description "Pushes a namespace on the name stack." } ;
 152
 153 HELP: ndrop
 154 { $description "Pops a namespace from the name stack." } ;
 155
 156 HELP: init-namespaces
 157 { $description "Resets the name stack to its initial state, holding a single copy of the global namespace." }
 158 $low-level-note ;