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 { $subsections
   9     "refs-protocol"
  10     "refs-impls"
  11     "refs-utils"
  12 }
  13 "References are used by the " { $link "ui-inspector" } "." ;
  14
  15 ABOUT: "refs"
  16
  17 ARTICLE: "refs-impls" "Reference implementations"
  18 "References to objects:"
  19 { $subsections
  20     obj-ref
  21     <obj-ref>
  22 }
  23 "References to assoc keys:"
  24 { $subsections
  25     key-ref
  26     <key-ref>
  27 }
  28 "References to assoc values:"
  29 { $subsections
  30     value-ref
  31     <value-ref>
  32 }
  33 "References to variables:"
  34 { $subsections
  35     var-ref
  36     <var-ref>
  37     global-var-ref
  38     <global-var-ref>
  39 }
  40 "References to tuple slots:"
  41 { $subsections
  42     slot-ref
  43     <slot-ref>
  44 }
  45 "Using boxes as references:"
  46 { $subsections "box-refs" } ;
  47
  48 ARTICLE: "refs-utils" "Reference utilities"
  49 { $subsections
  50     ref-on
  51     ref-off
  52     ref-inc
  53     ref-dec
  54     set-ref*
  55 } ;
  56
  57 ARTICLE: "refs-protocol" "Reference protocol"
  58 "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:"
  59 { $subsections
  60     get-ref
  61     set-ref
  62 }
  63 "References may also implement:"
  64 { $subsections delete-ref } ;
  65
  66 ARTICLE: "box-refs" "Boxes as references"
  67 { $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." ;
  68
  69 HELP: ref
  70 { $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 } "." } ;
  71
  72 HELP: delete-ref
  73 { $values { "ref" ref } }
  74 { $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." } ;
  75
  76 HELP: get-ref
  77 { $values { "ref" ref } { "obj" object } }
  78 { $description "Outputs the value pointed at by this reference." } ;
  79
  80 HELP: set-ref
  81 { $values { "obj" object } { "ref" ref } }
  82 { $description "Stores a new value at this reference." } ;
  83
  84 HELP: obj-ref
  85 { $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> } "." } ;
  86
  87 HELP: <obj-ref>
  88 { $values { "obj" object } { "obj-ref" obj-ref } }
  89 { $description "Creates a reference which contains the value it references." } ;
  90
  91 HELP: var-ref
  92 { $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> } "." } ;
  93
  94 HELP: <var-ref>
  95 { $values { "var" object } { "var-ref" var-ref } }
  96 { $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." } ;
  97
  98 HELP: global-var-ref
  99 { $class-description "Instances of this class reference a global variable. New global references are created by calling " { $link <global-var-ref> } "." } ;
 100
 101 HELP: <global-var-ref>
 102 { $values { "var" object } { "global-var-ref" global-var-ref } }
 103 { $description "Creates a reference to a global variable." } ;
 104
 105 HELP: slot-ref
 106 { $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> } "." } ;
 107
 108 HELP: <slot-ref>
 109 { $values { "tuple" tuple } { "slot" integer } { "slot-ref" slot-ref } }
 110 { $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." } ;
 111
 112 HELP: key-ref
 113 { $class-description "Instances of this class identify a key in an associative structure. New key references are created by calling " { $link <key-ref> } "." } ;
 114
 115 HELP: <key-ref>
 116 { $values { "assoc" assoc } { "key" object } { "key-ref" key-ref } }
 117 { $description "Creates a reference to a key stored in an assoc." } ;
 118
 119 HELP: value-ref
 120 { $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> } "." } ;
 121
 122 HELP: <value-ref>
 123 { $values { "assoc" assoc } { "key" object } { "value-ref" value-ref } }
 124 { $description "Creates a reference to the value associated with " { $snippet "key" } " in " { $snippet "assoc" } "." } ;
 125
 126 { get-ref set-ref delete-ref set-ref* } related-words
 127
 128 { <obj-ref> <var-ref> <global-var-ref> <slot-ref> <key-ref> <value-ref> } related-words
 129
 130 HELP: set-ref*
 131 { $values { "ref" ref } { "obj" object } }
 132 { $description "Just like " { $link set-ref } ", but leave the ref on the stack." } ;
 133
 134 HELP: ref-on
 135 { $values { "ref" ref } }
 136 { $description "Sets the value of the ref to t." } ;
 137
 138 HELP: ref-off
 139 { $values { "ref" ref } }
 140 { $description "Sets the value of the ref to f." } ;
 141
 142 HELP: ref-inc
 143 { $values { "ref" ref } }
 144 { $description "Increment the value of the ref by 1." } ;
 145
 146 HELP: ref-dec
 147 { $values { "ref" ref } }
 148 { $description "Decrement the value of the ref by 1." } ;
 149
 150 HELP: take
 151 { $values { "ref" ref } { "obj" object } }
 152 { $description "Retrieve the value of the ref and then delete it, returning the value." } ;
 153
 154 { ref-on ref-off ref-inc ref-dec take } related-words
 155 { take delete-ref } related-words
 156 { on ref-on } related-words
 157 { off ref-off } related-words
 158 { inc ref-inc } related-words
 159 { dec ref-dec } related-words