core/namespaces/namespaces-docs.factor

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