core/classes/classes-docs.factor

   1 USING: help.markup help.syntax kernel kernel.private
   2 namespaces sequences words arrays effects math
   3 classes.private classes.union classes.mixin
   4 classes.predicate quotations ;
   5 IN: classes
   6
   7 ARTICLE: "class-predicates" "Class predicate words"
   8 "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."
   9 $nl
  10 "When it comes to predicates, the exceptional classes are:"
  11 { $table
  12     { "Class" "Predicate" "Explanation" }
  13     { { $link f } { $snippet "[ not ]" } { "The conventional name for a word which outputs true when given false is " { $link not } "; " { $snippet "f?" } " would be confusing." } }
  14     { { $link object } { $snippet "[ drop t ]" } { "All objects are instances of " { $link object } } }
  15     { { $link null } { $snippet "[ drop f ]" } { "No object is an instance of " { $link null } } }
  16 }
  17 "The set of class predicate words is a class:"
  18 { $subsection predicate }
  19 { $subsection predicate? }
  20 "A predicate word holds a reference to the class it is predicating over in the " { $snippet "\"predicating\"" } " word property." ;
  21
  22 ARTICLE: "classes" "Classes"
  23 "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."
  24 $nl
  25 "At the implementation level, a class is a word with certain word properties set."
  26 $nl
  27 "Words for working with classes are found in the " { $vocab-link "classes" } " vocabulary."
  28 $nl
  29 "Classes themselves form a class:"
  30 { $subsection class? }
  31 "You can ask an object for its class:"
  32 { $subsection class }
  33 "Testing if an object is an instance of a class:"
  34 { $subsection instance? }
  35 "You can ask a class for its superclass:"
  36 { $subsection superclass }
  37 { $subsection superclasses }
  38 { $subsection subclass-of? }
  39 "Class predicates can be used to test instances directly:"
  40 { $subsection "class-predicates" }
  41 "There is a universal class which all objects are an instance of, and an empty class with no instances:"
  42 { $subsection object }
  43 { $subsection null }
  44 "Obtaining a list of all defined classes:"
  45 { $subsection classes }
  46 "There are several sorts of classes:"
  47 { $subsection "builtin-classes" }
  48 { $subsection "unions" }
  49 { $subsection "intersections" }
  50 { $subsection "mixins" }
  51 { $subsection "predicates" }
  52 { $subsection "singletons" }
  53 { $link "tuples" } " are documented in their own section."
  54 $nl
  55 "Classes can be inspected and operated upon:"
  56 { $subsection "class-operations" }
  57 { $subsection "class-linearization" }
  58 { $see-also "class-index" } ;
  59
  60 ABOUT: "classes"
  61
  62 HELP: class
  63 { $values { "object" object } { "class" class } }
  64 { $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." }
  65 { $class-description "The class of all class words." }
  66 { $examples { $example "USING: classes prettyprint ;" "1.0 class ." "float" } { $example "USING: classes prettyprint ;" "IN: scratchpad" "TUPLE: point x y z ;\nT{ point f 1 2 3 } class ." "point" } } ;
  67
  68 HELP: classes
  69 { $values { "seq" "a sequence of class words" } }
  70 { $description "Finds all class words in the dictionary." } ;
  71
  72 HELP: update-map
  73 { $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." } ;
  74
  75 HELP: predicate-word
  76 { $values { "word" "a word" } { "predicate" "a predicate word" } }
  77 { $description "Suffixes the word's name with \"?\" and creates a word with that name in the same vocabulary as the word itself." } ;
  78
  79 HELP: define-predicate
  80 { $values { "class" class } { "quot" quotation } }
  81 { $description "Defines a predicate word for a class." }
  82 $low-level-note ;
  83
  84 HELP: superclass
  85 { $values { "class" class } { "super" class } }
  86 { $description "Outputs the superclass of a class. All instances of this class are also instances of the superclass." }
  87 { $examples
  88     { $example "USING: classes prettyprint ;"
  89                "t superclass ."
  90                "word"
  91     }
  92 } ;
  93
  94 HELP: superclasses
  95 { $values
  96      { "class" class }
  97      { "supers" sequence } }
  98 { $description "Outputs a sequence of superclasses of a class along with the class itself." }
  99 { $examples
 100     { $example "USING: classes prettyprint ;"
 101                "t superclasses ."
 102                "{ word t }"
 103     }
 104 } ;
 105
 106 HELP: subclass-of?
 107 { $values
 108     { "class" class }
 109     { "superclass" class }
 110     { "?" boolean }
 111 }
 112 { $description "Outputs a boolean value indicating whether " { $snippet "class" } " is at any level a subclass of " { $snippet "superclass" } "." }
 113 { $examples
 114     { $example "USING: classes classes.tuple prettyprint words ;"
 115                "tuple-class \\ class subclass-of? ."
 116                "t"
 117     }
 118 } ;
 119
 120 { superclass superclasses subclass-of? } related-words
 121
 122 HELP: members
 123 { $values { "class" class } { "seq" "a sequence of union members, or " { $link f } } }
 124 { $description "If " { $snippet "class" } " is a union class, outputs a sequence of its member classes, otherwise outputs " { $link f } "." } ;
 125
 126 HELP: participants
 127 { $values { "class" class } { "seq" "a sequence of intersection participants, or " { $link f } } }
 128 { $description "If " { $snippet "class" } " is an intersection class, outputs a sequence of its participant classes, otherwise outputs " { $link f } "." } ;
 129
 130 HELP: define-class
 131 { $values { "word" word } { "superclass" class } { "members" "a sequence of class words" } { "participants" "a sequence of class words" } { "metaclass" class } }
 132 { $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 } "." }
 133 $low-level-note ;
 134
 135 HELP: implementors
 136 { $values { "class/classes" "a class or a sequence of classes" } { "seq" "a sequence of generic words" } }
 137 { $description "Finds all generic words in the dictionary implementing methods for the given set of classes." } ;
 138
 139 HELP: instance?
 140 { $values
 141      { "object" object } { "class" class }
 142      { "?" "a boolean" } }
 143 { $description "Tests whether the input object is a member of the class." } ;