/core/namespaces/namespaces-docs.factor

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