core/classes/algebra/algebra-docs.factor

   1 USING: classes classes.algebra.private classes.private help.markup
   2 help.syntax kernel math sequences ;
   3 IN: classes.algebra
   4
   5 ARTICLE: "class-operations" "Class operations"
   6 "Set-theoretic operations on classes:"
   7 { $subsections
   8     class=
   9     class<
  10     class<=
  11     class-and
  12     class-or
  13     classes-intersect?
  14     flatten-class
  15 } ;
  16
  17 ARTICLE: "class-linearization" "Class linearization"
  18 "Classes have an intrinsic partial order; given two classes A and B, we either have that A is a subset of B, B is a subset of A, A and B are equal as sets, or they are incomparable. The last two situations present difficulties for method dispatch:"
  19 { $list
  20     "If a generic word defines a method on a mixin class A and another on class B, and B is the only instance of A, there is an ambiguity because A and B are equal as sets; any object that is an instance of one is an instance of both."
  21     { "If a generic word defines methods on two union classes which are incomparable but not disjoint, for example " { $link sequence } " and " { $link number } ", there is an ambiguity because the generic word may be called on an object that is an instance of both unions." }
  22 }
  23 "The first ambiguity is resolved with a tie-breaker that compares metaclasses. The intrinsic meta-class order, from most-specific to least-specific:"
  24 { $list
  25     "Built-in classes and tuple classes"
  26     "Predicate classes"
  27     "Union classes"
  28     "Mixin classes"
  29 }
  30 "This means that in the above example, the generic word with methods on a mixin and its sole instance will always call the method for the sole instance, since it is more specific than a mixin class."
  31 $nl
  32 "The second problem is resolved with another tie-breaker. When performing the topological sort of classes, if there are multiple candidates at any given step of the sort, lexicographical order on the class name is used."
  33 $nl
  34 "Operations:"
  35 { $subsections
  36     class<
  37     sort-classes
  38     smallest-class
  39 }
  40 "Metaclass order:"
  41 { $subsections rank-class } ;
  42
  43 HELP: flatten-class
  44 { $values { "class" class } { "assoc" "an assoc whose keys are classes" } }
  45 { $description "Outputs a set of builtin and tuple classes whose union is the smallest cover of " { $snippet "class" } "." } ;
  46
  47 HELP: class<=
  48 { $values { "first" "a class" } { "second" "a class" } { "?" boolean } }
  49 { $description "Tests if all instances of " { $snippet "class1" } " are also instances of " { $snippet "class2" } "." }
  50 { $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" } "." } ;
  51
  52 HELP: class-and
  53 { $values { "first" class } { "second" class } { "class" class } }
  54 { $description "Outputs the largest anonymous class contained in both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
  55
  56 HELP: class-not
  57 { $values { "class" class } { "complement" class } }
  58 { $description "Outputs the complement class of 'class'." } ;
  59
  60 HELP: class-or
  61 { $values { "first" class } { "second" class } { "class" class } }
  62 { $description "Outputs the smallest anonymous class containing both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
  63
  64 HELP: classes-intersect?
  65 { $values { "first" class } { "second" class } { "?" boolean } }
  66 { $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." } ;
  67
  68 HELP: normalize-class
  69 { $values { "class" class } { "class'" class } }
  70 { $description "Normalizes a class in such a way that it becomes easier to perform algebra on it." } ;
  71
  72 HELP: smallest-class
  73 { $values { "classes" "a sequence of class words" } { "class/f" { $maybe class } } }
  74 { $description "Outputs a minimum class from the given sequence." } ;
  75
  76 HELP: sort-classes
  77 { $values { "seq" "a sequence of class" } { "newseq" "a new sequence of classes" } }
  78 { $description "Outputs a linear sort of a sequence of classes. Larger classes come before their subclasses." } ;