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 are sufficient for holding data which is not literal. But occasionally, for global information that's calculated just once, it's useful to use the word mechanism instead, and set the 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