core/classes/classes-docs.factor

   1 USING: classes.private help.markup help.syntax kernel sequences words ;
   2 IN: classes
   3
   4 ARTICLE: "class-predicates" "Class predicate words"
   5 "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."
   6 $nl
   7 "When it comes to predicates, the exceptional classes are:"
   8 { $table
   9     { "Class" "Predicate" "Explanation" }
  10     { { $link f } { $snippet "[ not ]" } { "The conventional name for a word which outputs true when given false is " { $link not } "; " { $snippet "f?" } " would be confusing." } }
  11     { { $link object } { $snippet "[ drop t ]" } { "All objects are instances of " { $link object } } }
  12     { { $link null } { $snippet "[ drop f ]" } { "No object is an instance of " { $link null } } }
  13 }
  14 "The set of class predicate words is a class:"
  15 { $subsections
  16     predicate
  17     predicate?
  18 }
  19 "A predicate word holds a reference to the class it is predicating over in the " { $snippet "\"predicating\"" } " word property." $nl
  20 "Implementation of class reloading:"
  21 { $subsections reset-class forget-class forget-methods } ;
  22
  23 ARTICLE: "classes" "Classes"
  24 "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."
  25 $nl
  26 "At the implementation level, a class is a word with certain word properties set."
  27 $nl
  28 "Words for working with classes are found in the " { $vocab-link "classes" } " vocabulary."
  29 $nl
  30 "Classes themselves form a class:"
  31 { $subsections class? }
  32 "You can ask an object for its class:"
  33 { $subsections class-of }
  34 "Testing if an object is an instance of a class:"
  35 { $subsections instance? }
  36 "You can ask a class for its superclass:"
  37 { $subsections
  38     superclass-of
  39     superclasses-of
  40     subclass-of?
  41 }
  42 "Class predicates can be used to test instances directly:"
  43 { $subsections "class-predicates" }
  44 "There is a universal class which all objects are an instance of, and an empty class with no instances:"
  45 { $subsections
  46     object
  47     null
  48 }
  49 "Obtaining a list of all defined classes:"
  50 { $subsections classes }
  51 "There are several sorts of classes:"
  52 { $subsections
  53     "builtin-classes"
  54     "unions"
  55     "intersections"
  56     "maybes"
  57     "mixins"
  58     "predicates"
  59     "singletons"
  60 }
  61 { $link "tuples" } " are documented in their own section."
  62 $nl
  63 "Classes can be inspected and operated upon:"
  64 { $subsections
  65     "class-operations"
  66     "class-linearization"
  67 }
  68 { $see-also "class-index" } ;
  69
  70 ABOUT: "classes"
  71
  72 HELP: class
  73 { $class-description "The class of all class words." } ;
  74
  75 HELP: class-members
  76 { $values { "class" class } { "seq" "a sequence of union members, or " { $link f } } }
  77 { $description "If " { $snippet "class" } " is a union class, outputs a sequence of its member classes, otherwise outputs " { $link f } "." } ;
  78
  79 HELP: class-of
  80 { $values { "object" object } { "class" class } }
  81 { $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." }
  82 { $examples { $example "USING: classes prettyprint ;" "1.0 class-of ." "float" } { $example "USING: classes prettyprint ;" "IN: scratchpad" "TUPLE: point x y z ;\nT{ point f 1 2 3 } class-of ." "point" } } ;
  83
  84 HELP: class-usage
  85 { $values { "class" class } { "seq" sequence } }
  86 { $description "Lists all classes that uses or depends on this class." } ;
  87
  88 HELP: classes
  89 { $values { "seq" { $sequence class } } }
  90 { $description "Finds all class words in the dictionary." } ;
  91
  92 HELP: contained-classes
  93 { $values { "obj" class } { "members" sequence } }
  94 { $description "Lists all classes contained in the class." }
  95 { $see-also all-contained-classes } ;
  96
  97 HELP: define-predicate
  98 { $values { "class" class } { "quot" { $quotation ( obj -- ? ) } } }
  99 { $description "Defines a predicate word for a class." }
 100 $low-level-note ;
 101
 102 HELP: metaclass-changed
 103 { $values { "use" class } { "class" class } }
 104 { $description "Notifies the class 'class' that its metaclass 'use' has changed." } ;
 105
 106 HELP: predicate-def
 107 { $values { "obj" "a type object" } { "quot" { $quotation ( obj -- ? ) } } }
 108 { $description "Outputs a quotation that can be used to check if objects are an instance of the given type." }
 109 { $examples
 110   { $example
 111     "USING: classes math prettyprint ;"
 112     "fixnum predicate-def ."
 113     "[ fixnum? ]"
 114   }
 115 } ;
 116
 117 HELP: predicate-word
 118 { $values { "word" word } { "predicate" "a predicate word" } }
 119 { $description "Suffixes the word's name with \"?\" and creates a word with that name in the same vocabulary as the word itself." } ;
 120
 121 HELP: superclass-of
 122 { $values { "class" class } { "super" class } }
 123 { $description "Outputs the superclass of a class. All instances of this class are also instances of the superclass." }
 124 { $examples
 125     { $example "USING: classes prettyprint ;"
 126                "t superclass-of ."
 127                "word"
 128     }
 129 } ;
 130
 131 HELP: superclasses-of
 132 { $values
 133      { "class" class }
 134      { "supers" sequence } }
 135 { $description "Outputs a sequence of superclasses of a class along with the class itself." }
 136 { $examples
 137     { $example "USING: classes prettyprint ;"
 138                "t superclasses-of ."
 139                "{ word t }"
 140     }
 141 } ;
 142
 143 HELP: subclass-of?
 144 { $values
 145     { "class" class }
 146     { "superclass" class }
 147     { "?" boolean }
 148 }
 149 { $description "Outputs a boolean value indicating whether " { $snippet "class" } " is at any level a subclass of " { $snippet "superclass" } "." }
 150 { $examples
 151     { $example "USING: classes classes.tuple prettyprint words ;"
 152                "tuple-class \\ class subclass-of? ."
 153                "t"
 154     }
 155 } ;
 156
 157 HELP: update-map
 158 { $var-description "Assoc 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." }
 159 { $see-also class-usage } ;
 160
 161 { superclass-of superclasses-of subclass-of? } related-words
 162
 163 HELP: class-participants
 164 { $values { "class" class } { "seq" "a sequence of intersection participants, or " { $link f } } }
 165 { $description "If " { $snippet "class" } " is an intersection class, outputs a sequence of its participant classes, otherwise outputs " { $link f } "." } ;
 166
 167 HELP: define-class
 168 { $values { "word" word } { "superclass" class } { "members" { $sequence class } } { "participants" { $sequence class } } { "metaclass" class } }
 169 { $description "Sets a property indicating this word is a class word, thus making it an instance of " { $link class } ", and registers it with " { $link update-map } "." }
 170 $low-level-note ;
 171
 172 HELP: implementors
 173 { $values { "class/classes" { $or class { $sequence class } } } { "seq" "a sequence of generic words" } }
 174 { $description "Finds all generic words in the dictionary implementing methods for the given set of classes." } ;
 175
 176 HELP: instance?
 177 { $values
 178      { "object" object } { "class" class }
 179      { "?" boolean } }
 180 { $description "Tests whether the input object is a member of the class." } ;
 181
 182 HELP: reset-class
 183 { $values { "class" class } }
 184 { $description "Forgets all of words that the class defines, but not words that are defined on the class. For instance, on a tuple class, this word should reset all of the tuple accessors but not things like " { $link nth } " that may be defined on the class elsewhere." } ;
 185
 186 HELP: forget-class
 187 { $values { "class" class } }
 188 { $description "Removes a class by forgetting all of the methods defined on that class and all of the methods generated when that class was defined. Also resets any caches that may contain that class." } ;
 189
 190 HELP: forget-methods
 191 { $values { "class" class } }
 192 { $description "Forgets all methods defined on a class. In contrast to " { $link reset-class } ", this not only forgets accessors but also any methods at all on the class." } ;