core/classes/classes-docs.factor

   1 USING: generic help.markup help.syntax kernel kernel.private
   2 namespaces sequences words arrays layouts help effects math
   3 layouts classes.private classes.union classes.mixin
   4 classes.predicate ;
   5 IN: classes
   6
   7 ARTICLE: "builtin-classes" "Built-in classes"
   8 "Every object is an instance of to exactly one canonical " { $emphasis "built-in class" } " which defines its layout in memory and basic behavior."
   9 $nl
  10 "Corresponding to every built-in class is a built-in type number. An object can be asked for its built-in type number:"
  11 { $subsection type }
  12 "Built-in type numbers can be converted to classes, and vice versa:"
  13 { $subsection type>class }
  14 { $subsection type-number }
  15 "The set of built-in classes is a class:"
  16 { $subsection builtin-class }
  17 { $subsection builtin-class? }
  18 "See " { $link "type-index" } " for a list of built-in classes." ;
  19
  20 ARTICLE: "class-operations" "Class operations"
  21 "Set-theoretic operations on classes:"
  22 { $subsection class< }
  23 { $subsection class-and }
  24 { $subsection class-or }
  25 { $subsection classes-intersect? }
  26 "Topological sort:"
  27 { $subsection sort-classes }
  28 { $subsection min-class }
  29 "Low-level implementation detail:"
  30 { $subsection types }
  31 { $subsection flatten-class }
  32 { $subsection flatten-builtin-class }
  33 { $subsection flatten-union-class } ;
  34
  35 ARTICLE: "class-predicates" "Class predicate words"
  36 "With a handful of exceptions, each class has a membership predicate word, named " { $snippet { $emphasis "class" } "?" } " . A quotation calling this predicate is stored in the " { $snippet "\"predicate\"" } " word property."
  37 $nl
  38 "When it comes to predicates, the exceptional classes are:"
  39 { $table
  40     { "Class" "Predicate" "Explanation" }
  41     { { $link f } { $snippet "[ not ]" } { "The conventional name for a word which outputs true when given false is " { $link not } "; " { $snippet "f?" } " would be confusing." } }
  42     { { $link object } { $snippet "[ drop t ]" } { "All objects are instances of " { $link object } } }
  43     { { $link null } { $snippet "[ drop f ]" } { "No object is an instance of " { $link null } } }
  44     { { $link general-t } { $snippet "[ ]" } { "All objects with a true value are instances of " { $link general-t } } }
  45 }
  46 "The set of class predicate words is a class:"
  47 { $subsection predicate }
  48 { $subsection predicate? }
  49 "A predicate word holds a reference to the class it is predicating over in the " { $snippet "\"predicating\"" } " word property." ;
  50
  51 ARTICLE: "classes" "Classes"
  52 "Conceptually, a " { $snippet "class" } " is a set of objects whose members can be identified with a predicate, and on which generic words can specialize methods. Classes are organized into a general partial order, and an object may be an instance of more than one class."
  53 $nl
  54 "At the implementation level, a class is a word with certain word properties set."
  55 $nl
  56 "Words for working with classes are found in the " { $vocab-link "classes" } " vocabulary."
  57 $nl
  58 "Classes themselves form a class:"
  59 { $subsection class? }
  60 "You can ask an object for its class:"
  61 { $subsection class }
  62 "There is a universal class which all objects are an instance of, and an empty class with no instances:"
  63 { $subsection object }
  64 { $subsection null }
  65 "Obtaining a list of all defined classes:"
  66 { $subsection classes }
  67 "Other sorts of classes:"
  68 { $subsection "builtin-classes" }
  69 { $subsection "unions" }
  70 { $subsection "mixins" }
  71 { $subsection "predicates" }
  72 "Classes can be inspected and operated upon:"
  73 { $subsection "class-operations" }
  74 { $see-also "class-index" } ;
  75
  76 ABOUT: "classes"
  77
  78 HELP: class
  79 { $values { "object" object } { "class" class } }
  80 { $description "Outputs an object's canonical class. While an object may be an instance of more than one class, the canonical class is either its built-in class, or if the object is a tuple, its tuple class." }
  81 { $class-description "The class of all class words. Subclasses include " { $link builtin-class } ", " { $link union-class } ", " { $link mixin-class } ", " { $link predicate-class } " and " { $link tuple-class } "." }
  82 { $examples { $example "USE: classes" "1.0 class ." "float" } { $example "USE: classes" "TUPLE: point x y z ;\nT{ point f 1 2 3 } class ." "point" } } ;
  83
  84 HELP: classes
  85 { $values { "seq" "a sequence of class words" } }
  86 { $description "Finds all class words in the dictionary." } ;
  87
  88 HELP: builtin-class
  89 { $class-description "The class of built-in classes." }
  90 { $examples
  91     "The class of arrays is a built-in class:"
  92     { $example "USE: classes" "array builtin-class? ." "t" }
  93     "However, a literal array is not a built-in class; it is not even a class:"
  94     { $example "USE: classes" "{ 1 2 3 } builtin-class? ." "f" }
  95 } ;
  96
  97 HELP: tuple-class
  98 { $class-description "The class of tuple class words." }
  99 { $examples { $example "USE: classes\nTUPLE: name title first last ;\nname tuple-class? ." "t" } } ;
 100
 101 HELP: typemap
 102 { $var-description "Hashtable mapping unions to class words, used to implement " { $link class-and } " and " { $link class-or } "." } ;
 103
 104 HELP: builtins
 105 { $var-description "Vector mapping type numbers to builtin class words." } ;
 106
 107 HELP: class<map
 108 { $var-description "Hashtable mapping each class to a set of classes which are contained in that class under the " { $link (class<) } " relation. The " { $link class< } " word uses this hashtable to avoid frequent expensive calls to " { $link (class<) } "." } ;
 109
 110 HELP: update-map
 111 { $var-description "Hashtable mapping each class to a set of classes defined in terms of this class. The " { $link define-class } " word uses this information to update generic words when classes are redefined." } ;
 112
 113 HELP: type>class
 114 { $values { "n" "a non-negative integer" } { "class" class } }
 115 { $description "Outputs a builtin class whose instances are precisely those having a given pointer tag." }
 116 { $notes "The parameter " { $snippet "n" } " must be between 0 and the return value of " { $link num-types } "." } ;
 117
 118 HELP: predicate-word
 119 { $values { "word" "a word" } { "predicate" "a predicate word" } }
 120 { $description "Suffixes the word's name with \"?\" and creates a word with that name in the same vocabulary as the word itself." } ;
 121
 122 HELP: define-predicate
 123 { $values { "class" class } { "predicate" "a predicate word" } { "quot" "a quotation" } }
 124 { $description
 125     "Defines a predicate word. This is identical to a word definition associating " { $snippet "quot" } " with " { $snippet "predicate" } " with the added perk that three word properties are set:"
 126     { $list
 127         { "the class word's " { $snippet "\"predicate\"" } " property is set to a quotation that calls the predicate" }
 128         { "the predicate word's " { $snippet "\"predicating\"" } " property is set to the class word" }
 129         { "the predicate word's " { $snippet "\"declared-effect\"" } " word property is set to a descriptive " { $link effect } }
 130     }
 131     "These properties are used by method dispatch and the help system."
 132 }
 133 $low-level-note ;
 134
 135 HELP: superclass
 136 { $values { "class" class } { "super" class } }
 137 { $description "Outputs the superclass of a class. All instances of this class are also instances of the superclass." }
 138 { $notes "If " { $link class< } " yields that one class is a subtype of another, it does not imply that a superclass relation is involved. The superclass relation is a technical implementation detail of predicate and tuple classes." } ;
 139
 140 HELP: members
 141 { $values { "class" class } { "seq" "a sequence of union members, or " { $link f } } }
 142 { $description "If " { $snippet "class" } " is a union class, outputs a sequence of its member classes, otherwise outputs " { $link f } "." } ;
 143
 144 HELP: flatten-union-class
 145 { $values { "class" class } { "assoc" "an assoc whose keys are classes" } }
 146 { $description "Outputs the set of classes whose union is equal to " { $snippet "class" } ". Unions are expanded recursively so the output assoc does not contain any union classes. However, it may contain predicate classes whose superclasses are unions." } ;
 147
 148 HELP: flatten-builtin-class
 149 { $values { "class" class } { "assoc" "an assoc whose keys are classes" } }
 150 { $description "Outputs a set of tuple classes whose union is the smallest cover of " { $snippet "class" } " intersected with " { $link tuple } "." } ;
 151
 152 HELP: flatten-class
 153 { $values { "class" class } { "assoc" "an assoc whose keys are classes" } }
 154 { $description "Outputs a set of builtin and tuple classes whose union is the smallest cover of " { $snippet "class" } "." } ;
 155
 156 HELP: types
 157 { $values { "class" class } { "seq" "an increasing sequence of integers" } }
 158 { $description "Outputs a sequence of builtin type numbers whose instances can possibly be instances of the given class." } ;
 159
 160 HELP: class-empty?
 161 { $values { "class" "a class" } { "?" "a boolean" } }
 162 { $description "Tests if a class is a union class with no members." }
 163 { $examples { $example "USE: classes" "null class-empty? ." "t" } } ;
 164
 165 HELP: (class<)
 166 { $values { "class1" "a class" } { "class2" "a class" } { "?" "a boolean" } }
 167 { $description "Performs the calculation for " { $link class< } ". There is never any reason to call this word from user code since " { $link class< } " outputs identical values and caches results for better performance." } ;
 168
 169 HELP: class<
 170 { $values { "class1" "a class" } { "class2" "a class" } { "?" "a boolean" } }
 171 { $description "Tests if all instances of " { $snippet "class1" } " are also instances of " { $snippet "class2" } "." }
 172 { $notes "Classes are partially ordered. This means that if " { $snippet "class1 <= class2" } " and " { $snippet "class2 <= class1" } ", then " { $snippet "class1 = class2" } ". Also, if " { $snippet "class1 <= class2" } " and " { $snippet "class2 <= class3" } ", then " { $snippet "class1 <= class3" } "." } ;
 173
 174 HELP: sort-classes
 175 { $values { "seq" "a sequence of class" } { "newseq" "a new seqence of classes" } }
 176 { $description "Outputs a topological sort of a sequence of classes. Larger classes come before their subclasses." } ;
 177
 178 { sort-classes methods order } related-words
 179
 180 HELP: lookup-union
 181 { $values { "classes" "a hashtable mapping class words to themselves" } { "class" class } }
 182 { $description "Given a set of classes represented as a hashtable with equal keys and values, looks up a previously-defined union class having those members. If no union is defined, outputs " { $link object } "." } ;
 183
 184 { class-and class-or lookup-union } related-words
 185
 186 HELP: class-or
 187 { $values { "class1" class } { "class2" class } { "class" class } }
 188 { $description "Outputs the smallest known class containing both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
 189
 190 HELP: class-and
 191 { $values { "class1" class } { "class2" class } { "class" class } }
 192 { $description "Outputs the largest known class contained in both " { $snippet "class1" } " and " { $snippet "class2" } ". If the intersection is non-empty but no union class with those exact members is defined, outputs " { $link object } ". If the intersection is empty, outputs " { $link null } "." } ;
 193
 194 HELP: classes-intersect?
 195 { $values { "class1" class } { "class2" class } { "?" "a boolean" } }
 196 { $description "Tests if two classes have a non-empty intersection. If the intersection is empty, no object can be an instance of both classes at once." } ;
 197
 198 HELP: min-class
 199 { $values { "class" class } { "seq" "a sequence of class words" } { "class/f" "a class word or " { $link f } } }
 200 { $description "If all classes in " { $snippet "seq" } " that intersect " { $snippet "class" } " are subtypes of " { $snippet "class" } ", outputs the last such element of " { $snippet "seq" } ". If any conditions fail to hold, outputs " { $link f } "." } ;
 201
 202 HELP: define-class
 203 { $values { "word" word } { "members" "a sequence of class words" } { "superclass" class } { "metaclass" class } }
 204 { $description "Sets a property indicating this word is a class word, thus making it an instance of " { $link class } ", and registers it with " { $link typemap } " and " { $link class<map } "." }
 205 $low-level-note ;