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 words.symbol assocs ;
   4 IN: namespaces
   5
   6 ARTICLE: "namespaces-combinators" "Namespace combinators"
   7 { $subsections
   8     with-scope
   9     with-variable
  10     with-variables
  11 } ;
  12
  13 ARTICLE: "namespaces-change" "Changing variable values"
  14 { $subsections
  15     on
  16     off
  17     inc
  18     dec
  19     change
  20     change-global
  21     toggle
  22 } ;
  23
  24 ARTICLE: "namespaces-global" "Global variables"
  25 { $subsections
  26     namespace
  27     global
  28     get-global
  29     set-global
  30     initialize
  31     with-global
  32 } ;
  33
  34 ARTICLE: "namespaces.private" "Namespace implementation details"
  35 "The namestack holds namespaces."
  36 { $subsections
  37     namestack
  38     set-namestack
  39     namespace
  40 }
  41 "A pair of words push and pop namespaces on the namestack."
  42 { $subsections
  43     >n
  44     ndrop
  45 } ;
  46
  47 ARTICLE: "namespaces" "Dynamic variables"
  48 "The " { $vocab-link "namespaces" } " vocabulary implements dynamically-scoped variables."
  49 $nl
  50 "A dynamic 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 assocs, any object can be used as a variable. By convention, variables are keyed by " { $link "words.symbol" } "."
  51 $nl
  52 "The " { $link get } " and " { $link set } " words read and write variable values. The " { $link get } " word searches 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."
  53 { $subsections
  54     get
  55     set
  56 }
  57 "Various utility words provide common variable access patterns:"
  58 { $subsections
  59     "namespaces-change"
  60     "namespaces-combinators"
  61 }
  62 "Implementation details your code probably does not care about:"
  63 { $subsections "namespaces.private" }
  64 "Dynamic variables complement " { $link "locals" } "." ;
  65
  66 ABOUT: "namespaces"
  67
  68 HELP: get
  69 { $values { "variable" "a variable, by convention a symbol" } { "value" "the value, or " { $link f } } }
  70 { $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 } "." } ;
  71
  72 HELP: set
  73 { $values { "value" "the new value" } { "variable" "a variable, by convention a symbol" } }
  74 { $description "Assigns a value to the variable in the namespace at the top of the name stack." }
  75 { $side-effects "variable" } ;
  76
  77 HELP: off
  78 { $values { "variable" "a variable, by convention a symbol" } }
  79 { $description "Assigns a value of " { $link f } " to the variable." }
  80 { $side-effects "variable" } ;
  81
  82 HELP: on
  83 { $values { "variable" "a variable, by convention a symbol" } }
  84 { $description "Assigns a value of " { $link t } " to the variable." }
  85 { $side-effects "variable" } ;
  86
  87 HELP: change
  88 { $values { "variable" "a variable, by convention a symbol" } { "quot" { $quotation "( old -- new )" } } }
  89 { $description "Applies the quotation to the old value of the variable, and assigns the resulting value to the variable." }
  90 { $side-effects "variable" } ;
  91
  92 HELP: change-global
  93 { $values { "variable" "a variable, by convention a symbol" } { "quot" { $quotation "( old -- new )" } } }
  94 { $description "Applies the quotation to the old value of the global variable, and assigns the resulting value to the global variable." }
  95 { $side-effects "variable" } ;
  96
  97 HELP: toggle
  98 { $values
  99     { "variable" "a variable, by convention a symbol" }
 100 }
 101 { $description "Changes the boolean value of a variable to its opposite." } ;
 102
 103 HELP: with-global
 104 { $values
 105     { "quot" quotation }
 106 }
 107 { $description "Runs the quotation in the global namespace." } ;
 108
 109 HELP: +@
 110 { $values { "n" "a number" } { "variable" "a variable, by convention a symbol" } }
 111 { $description "Adds " { $snippet "n" } " to the value of the variable. A variable value of " { $link f } " is interpreted as being zero." }
 112 { $side-effects "variable" }
 113 { $examples
 114     { $example "USING: namespaces prettyprint ;" "IN: scratchpad" "SYMBOL: foo\n1 foo +@\n10 foo +@\nfoo get ." "11" }
 115 } ;
 116
 117 HELP: inc
 118 { $values { "variable" "a variable, by convention a symbol" } }
 119 { $description "Increments the value of the variable by 1. A variable value of " { $link f } " is interpreted as being zero." }
 120 { $side-effects "variable" } ;
 121
 122 HELP: dec
 123 { $values { "variable" "a variable, by convention a symbol" } }
 124 { $description "Decrements the value of the variable by 1. A variable value of " { $link f } " is interpreted as being zero." }
 125 { $side-effects "variable" } ;
 126
 127 HELP: counter
 128 { $values { "variable" "a variable, by convention a symbol" } { "n" integer } }
 129 { $description "Increments the value of the variable by 1, and returns its new value." }
 130 { $notes "This word is useful for generating (somewhat) unique identifiers. For example, the " { $link gensym } " word uses it." }
 131 { $side-effects "variable" } ;
 132
 133 HELP: with-scope
 134 { $values { "quot" quotation } }
 135 { $description "Calls the quotation in a new namespace. Any variables set by the quotation are discarded when it returns." }
 136 { $examples
 137     { $example "USING: math namespaces prettyprint ;" "IN: scratchpad" "SYMBOL: x" "0 x set" "[ x [ 5 + ] change x get . ] with-scope x get ." "5\n0" }
 138 } ;
 139
 140 HELP: with-variable
 141 { $values { "value" object } { "key" "a variable, by convention a symbol" } { "quot" quotation } }
 142 { $description "Calls the quotation in a new namespace where " { $snippet "key" } " is set to " { $snippet "value" } "." }
 143 { $examples "The following two phrases are equivalent:"
 144     { $code "[ 3 x set foo ] with-scope" }
 145     { $code "3 x [ foo ] with-variable" }
 146 } ;
 147
 148 HELP: with-variables
 149 { $values { "ns" assoc } { "quot" quotation } }
 150 { $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" } "." } ;
 151
 152 HELP: namespace
 153 { $values { "namespace" assoc } }
 154 { $description "Outputs the current namespace. Calls to " { $link set } " modify this namespace." } ;
 155
 156 HELP: global
 157 { $values { "g" assoc } }
 158 { $description "Outputs the global namespace. The global namespace is always checked last when looking up variable values." } ;
 159
 160 HELP: get-global
 161 { $values { "variable" "a variable, by convention a symbol" } { "value" "the value" } }
 162 { $description "Outputs the value of a variable in the global namespace." } ;
 163
 164 HELP: set-global
 165 { $values { "value" "the new value" } { "variable" "a variable, by convention a symbol" } }
 166 { $description "Assigns a value to the variable in the global namespace." }
 167 { $side-effects "variable" } ;
 168
 169 HELP: namestack*
 170 { $values { "namestack" "a vector of assocs" } }
 171 { $description "Outputs the current name stack." } ;
 172
 173 HELP: namestack
 174 { $values { "namestack" "a vector of assocs" } }
 175 { $description "Outputs a copy of the current name stack." } ;
 176
 177 HELP: set-namestack
 178 { $values { "namestack" "a vector of assocs" } }
 179 { $description "Replaces the name stack with a copy of the given vector." } ;
 180
 181 HELP: >n
 182 { $values { "namespace" assoc } }
 183 { $description "Pushes a namespace on the name stack." } ;
 184
 185 HELP: ndrop
 186 { $description "Pops a namespace from the name stack." } ;
 187
 188 HELP: init-namespaces
 189 { $description "Resets the name stack to its initial state, holding a single copy of the global namespace." }
 190 $low-level-note ;
 191
 192 HELP: initialize
 193 { $values { "variable" symbol } { "quot" quotation } }
 194 { $description "If " { $snippet "variable" } " does not have a value in the global namespace, calls " { $snippet "quot" } " and assigns the result to " { $snippet "variable" } " in the global namespace." } ;