basis/values/values-docs.factor

   1 USING: help.markup help.syntax ;\r
   2 IN: values\r
   3 \r
   4 ARTICLE: "values" "Global values"\r
   5 "Usually, dynamically-scoped variables subsume global variables and are sufficient for holding global data. But occasionally, for global information that's calculated just once and must be accessed more rapidly than a dynamic variable lookup can provide, it's useful to use the word mechanism instead, and set a word to the appropriate value just once. The " { $vocab-link "values" } " vocabulary implements " { $emphasis "values" } ", which abstract over this concept. To create a new word as a value, use the following syntax:"\r
   6 { $subsection POSTPONE: VALUE: }\r
   7 "To get the value, just call the word. The following words manipulate values:"\r
   8 { $subsection get-value }\r
   9 { $subsection set-value }\r
  10 { $subsection POSTPONE: to: }\r
  11 { $subsection change-value } ;\r
  12 \r
  13 ABOUT: "values"\r
  14 \r
  15 HELP: VALUE:\r
  16 { $syntax "VALUE: word" }\r
  17 { $values { "word" "a word to be created" } }\r
  18 { $description "Creates a value on the given word, initializing it to hold " { $snippet "f" } ". To get the value, just run the word. To set it, use " { $link POSTPONE: to: } "." }\r
  19 { $examples\r
  20   { $example\r
  21     "USING: values math prettyprint ;"\r
  22     "IN: scratchpad"\r
  23     "VALUE: x"\r
  24     "2 2 + to: x"\r
  25     "x ."\r
  26     "4"\r
  27   }\r
  28 } ;\r
  29 \r
  30 HELP: get-value\r
  31 { $values { "word" "a value word" } { "value" "the contents" } }\r
  32 { $description "Gets a value. This should not normally be used, unless the word is not known until runtime." } ;\r
  33 \r
  34 HELP: set-value\r
  35 { $values { "value" "a new value" } { "word" "a value word" } }\r
  36 { $description "Sets a value word." } ;\r
  37 \r
  38 HELP: to:\r
  39 { $syntax "... to: value" }\r
  40 { $values { "word" "a value word" } }\r
  41 { $description "Sets a value word." }\r
  42 { $notes\r
  43     "Note that"\r
  44     { $code "foo to: value" }\r
  45     "is just sugar for"\r
  46     { $code "foo \\ value set-value" }\r
  47 } ;\r
  48 \r
  49 HELP: change-value\r
  50 { $values { "word" "a value word" } { "quot" { $quotation "( oldvalue -- newvalue )" } } }\r
  51 { $description "Changes the value using the given quotation." } ;\r