basis/refs/refs-docs.factor

   1 ! Copyright (C) 2007 Slava Pestov
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax kernel ;
   4 IN: refs
   5
   6 ARTICLE: "refs" "References to assoc entries"
   7 "A " { $emphasis "reference" } " is an object encapsulating an assoc and a key; the reference then refers to either the key itself, or the value associated to the key. References can be read, written, and deleted. References are defined in the " { $vocab-link "refs" } " vocabulary."
   8 { $subsection get-ref }
   9 { $subsection set-ref }
  10 { $subsection delete-ref }
  11 "References to keys:"
  12 { $subsection key-ref }
  13 { $subsection <key-ref> }
  14 "References to values:"
  15 { $subsection value-ref }
  16 { $subsection <value-ref> }
  17 "References are used by the inspector." ;
  18
  19 ABOUT: "refs"
  20
  21 HELP: ref
  22 { $class-description "A class whose instances identify a key or value location in an associative structure. Instances of this clas are never used directly; only instances of " { $link key-ref } " and " { $link value-ref } " should be created." } ;
  23
  24 HELP: delete-ref
  25 { $values { "ref" ref } }
  26 { $description "Deletes the association entry pointed at by this reference." } ;
  27
  28 HELP: get-ref
  29 { $values { "ref" ref } { "obj" object } }
  30 { $description "Outputs the key or the value pointed at by this reference." } ;
  31
  32 HELP: set-ref
  33 { $values { "obj" object } { "ref" ref } }
  34 { $description "Stores a new key or value at by this reference." } ;
  35
  36 HELP: key-ref
  37 { $class-description "Instances of this class identify a key in an associative structure. New key references are created by calling " { $link <key-ref> } "." } ;
  38
  39 HELP: <key-ref>
  40 { $values { "key" object } { "assoc" "an assoc" } { "ref" key-ref } }
  41 { $description "Creates a reference to a key stored in an assoc." } ;
  42
  43 HELP: value-ref
  44 { $class-description "Instances of this class identify a value associated to a key in an associative structure. New value references are created by calling " { $link <value-ref> } "." } ;
  45
  46 HELP: <value-ref>
  47 { $values { "key" object } { "assoc" "an assoc" } { "ref" value-ref } }
  48 { $description "Creates a reference to the value associated with " { $snippet "key" } " in " { $snippet "assoc" } "." } ;
  49
  50 { get-ref set-ref delete-ref } related-words
  51
  52 { <key-ref> <value-ref> } related-words