basis/refs/refs-docs.factor

   1 ! Copyright (C) 2007 Slava Pestov, 2009 Alex Chapman
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: boxes help.markup help.syntax kernel math namespaces assocs ;
   4 IN: refs
   5
   6 ARTICLE: "refs" "References"
   7 "References provide a uniform way of accessing and changing values. Some examples of referenced values are variables, tuple slots, and keys or values of assocs. References can be read, written, and deleted. References are defined in the " { $vocab-link "refs" } " vocabulary, and new reference types can be made by implementing a protocol."
   8 { $subsection "refs-protocol" }
   9 { $subsection "refs-impls" }
  10 { $subsection "refs-utils" }
  11 "References are used by the " { $link "ui-inspector" } "." ;
  12
  13 ABOUT: "refs"
  14
  15 ARTICLE: "refs-impls" "Reference implementations"
  16 "References to objects:"
  17 { $subsection obj-ref }
  18 { $subsection <obj-ref> }
  19 "References to assoc keys:"
  20 { $subsection key-ref }
  21 { $subsection <key-ref> }
  22 "References to assoc values:"
  23 { $subsection value-ref }
  24 { $subsection <value-ref> }
  25 "References to variables:"
  26 { $subsection var-ref }
  27 { $subsection <var-ref> }
  28 { $subsection global-var-ref }
  29 { $subsection <global-var-ref> }
  30 "References to tuple slots:"
  31 { $subsection slot-ref }
  32 { $subsection <slot-ref> }
  33 "Using boxes as references:"
  34 { $subsection "box-refs" } ;
  35
  36 ARTICLE: "refs-utils" "Reference utilities"
  37 { $subsection ref-on }
  38 { $subsection ref-off }
  39 { $subsection ref-inc }
  40 { $subsection ref-dec }
  41 { $subsection set-ref* } ;
  42
  43 ARTICLE: "refs-protocol" "Reference protocol"
  44 "To use a class of objects as references you must implement the reference protocol for that class, and mark your class as an instance of the " { $link ref } " mixin class. All references must implement these two words:"
  45 { $subsection get-ref }
  46 { $subsection set-ref }
  47 "References may also implement:"
  48 { $subsection delete-ref } ;
  49
  50 ARTICLE: "box-refs" "Boxes as references"
  51 { $link "boxes" } " are elements of the " { $link ref } " mixin class, so any box may be used as a reference. Bear in mind that boxes will still throw an error if you call " { $link get-ref } " on an empty box." ;
  52
  53 HELP: ref
  54 { $class-description "A mixin class whose instances encapsulate a value which can be read, written, and deleted. Instantiable members of this class include:" { $link obj-ref } ", " { $link var-ref } ", " { $link global-var-ref } ", " { $link slot-ref } ", " { $link box } ", " { $link key-ref } ", and " { $link value-ref } "." } ;
  55
  56 HELP: delete-ref
  57 { $values { "ref" ref } }
  58 { $description "Deletes the value pointed to by this reference. In most references this simply sets the value to f, but in some cases it is more destructive, such as in " { $link value-ref } " and " { $link key-ref } ", where it actually deletes the entry from the underlying assoc." } ;
  59
  60 HELP: get-ref
  61 { $values { "ref" ref } { "obj" object } }
  62 { $description "Outputs the value pointed at by this reference." } ;
  63
  64 HELP: set-ref
  65 { $values { "obj" object } { "ref" ref } }
  66 { $description "Stores a new value at this reference." } ;
  67
  68 HELP: obj-ref
  69 { $class-description "Instances of this class contain a value which can be changed using the " { $link "refs-protocol" } ". New object references are created by calling " { $link <obj-ref> } "." } ;
  70
  71 HELP: <obj-ref>
  72 { $values { "obj" object } { "obj-ref" obj-ref } }
  73 { $description "Creates a reference which contains the value it references." } ;
  74
  75 HELP: var-ref
  76 { $class-description "Instances of this class reference a variable as defined by the " { $vocab-link "namespaces" } " vocabulary. New variable references are created by calling " { $link <var-ref> } "." } ;
  77
  78 HELP: <var-ref>
  79 { $values { "var" object } { "var-ref" var-ref } }
  80 { $description "Creates a reference to the given variable. Note that this reference behaves just like any variable when it comes to dynamic scope. For example, if you use " { $link set-ref } " in an inner scope and then leave that scope, then calling " { $link get-ref } " may not return the expected value. If this is not what you want, try using an " { $link obj-ref } " instead." } ;
  81
  82 HELP: global-var-ref
  83 { $class-description "Instances of this class reference a global variable. New global references are created by calling " { $link <global-var-ref> } "." } ;
  84
  85 HELP: <global-var-ref>
  86 { $values { "var" object } { "global-var-ref" global-var-ref } }
  87 { $description "Creates a reference to a global variable." } ;
  88
  89 HELP: slot-ref
  90 { $class-description "Instances of this class identify a particular slot of a particular instance of a tuple. New slot references are created by calling " { $link <slot-ref> } "." } ;
  91
  92 HELP: <slot-ref>
  93 { $values { "tuple" tuple } { "slot" integer } { "slot-ref" slot-ref } }
  94 { $description "Creates a reference to the value in a particular slot of the given tuple. The slot must be given as an integer, where the first user-defined slot is number 2. This is mostly just a proof of concept until we have a way of generating this slot number from a slot name." } ;
  95
  96 HELP: key-ref
  97 { $class-description "Instances of this class identify a key in an associative structure. New key references are created by calling " { $link <key-ref> } "." } ;
  98
  99 HELP: <key-ref>
 100 { $values { "assoc" assoc } { "key" object } { "key-ref" key-ref } }
 101 { $description "Creates a reference to a key stored in an assoc." } ;
 102
 103 HELP: value-ref
 104 { $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> } "." } ;
 105
 106 HELP: <value-ref>
 107 { $values { "assoc" assoc } { "key" object } { "value-ref" value-ref } }
 108 { $description "Creates a reference to the value associated with " { $snippet "key" } " in " { $snippet "assoc" } "." } ;
 109
 110 { get-ref set-ref delete-ref set-ref* } related-words
 111
 112 { <obj-ref> <var-ref> <global-var-ref> <slot-ref> <key-ref> <value-ref> } related-words
 113
 114 HELP: set-ref*
 115 { $values { "ref" ref } { "obj" object } }
 116 { $description "Just like " { $link set-ref } ", but leave the ref on the stack." } ;
 117
 118 HELP: ref-on
 119 { $values { "ref" ref } }
 120 { $description "Sets the value of the ref to t." } ;
 121
 122 HELP: ref-off
 123 { $values { "ref" ref } }
 124 { $description "Sets the value of the ref to f." } ;
 125
 126 HELP: ref-inc
 127 { $values { "ref" ref } }
 128 { $description "Increment the value of the ref by 1." } ;
 129
 130 HELP: ref-dec
 131 { $values { "ref" ref } }
 132 { $description "Decrement the value of the ref by 1." } ;
 133
 134 HELP: take
 135 { $values { "ref" ref } { "obj" object } }
 136 { $description "Retrieve the value of the ref and then delete it, returning the value." } ;
 137
 138 { ref-on ref-off ref-inc ref-dec take } related-words
 139 { take delete-ref } related-words
 140 { on ref-on } related-words
 141 { off ref-off } related-words
 142 { inc ref-inc } related-words
 143 { dec ref-dec } related-words