/core/namespaces/namespaces-docs.factor

http://github.com/abeaumont/factor · Factor · 199 lines · 166 code · 33 blank · 0 comment · 0 complexity · ebea4956b699bb5ce58b9a7170733cd8 MD5 · raw file

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