core/classes/algebra/algebra-docs.factor

   1 USING: help.markup help.syntax kernel classes words\r
   2 checksums checksums.crc32 sequences math ;\r
   3 IN: classes.algebra\r
   4 \r
   5 ARTICLE: "class-operations" "Class operations"\r
   6 "Set-theoretic operations on classes:"\r
   7 { $subsections\r
   8     class=\r
   9     class<\r
  10     class<=\r
  11     class-and\r
  12     class-or\r
  13     classes-intersect?\r
  14 }\r
  15 "Low-level implementation detail:"\r
  16 { $subsections\r
  17     flatten-class\r
  18     flatten-builtin-class\r
  19     class-types\r
  20     class-tags\r
  21 } ;\r
  22 \r
  23 ARTICLE: "class-linearization" "Class linearization"\r
  24 "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:"\r
  25 { $list\r
  26     "If a generic word defines a method on a mixin class A and another 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."\r
  27     { "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." }\r
  28 }\r
  29 "The first ambiguity is resolved with a tie-breaker that compares metaclasses. The intrinsic meta-class order, from most-specific to least-specific:"\r
  30 { $list\r
  31     "Built-in classes and tuple classes"\r
  32     "Predicate classes"\r
  33     "Union classes"\r
  34     "Mixin classes"\r
  35 }\r
  36 "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."\r
  37 $nl\r
  38 "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."\r
  39 $nl\r
  40 "Operations:"\r
  41 { $subsections\r
  42     class<\r
  43     sort-classes\r
  44     smallest-class\r
  45 }\r
  46 "Metaclass order:"\r
  47 { $subsections rank-class } ;\r
  48 \r
  49 HELP: flatten-builtin-class\r
  50 { $values { "class" class } { "assoc" "an assoc whose keys are classes" } }\r
  51 { $description "Outputs a set of tuple classes whose union is the smallest cover of " { $snippet "class" } " intersected with " { $link tuple } "." } ;\r
  52 \r
  53 HELP: flatten-class\r
  54 { $values { "class" class } { "assoc" "an assoc whose keys are classes" } }\r
  55 { $description "Outputs a set of builtin and tuple classes whose union is the smallest cover of " { $snippet "class" } "." } ;\r
  56 \r
  57 HELP: class-types\r
  58 { $values { "class" class } { "seq" "an increasing sequence of integers" } }\r
  59 { $description "Outputs a sequence of builtin type numbers whose instances can possibly be instances of the given class." } ;\r
  60 \r
  61 HELP: class<=\r
  62 { $values { "first" "a class" } { "second" "a class" } { "?" "a boolean" } }\r
  63 { $description "Tests if all instances of " { $snippet "class1" } " are also instances of " { $snippet "class2" } "." }\r
  64 { $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" } "." } ;\r
  65 \r
  66 HELP: sort-classes\r
  67 { $values { "seq" "a sequence of class" } { "newseq" "a new seqence of classes" } }\r
  68 { $description "Outputs a linear sort of a sequence of classes. Larger classes come before their subclasses." } ;\r
  69 \r
  70 HELP: class-or\r
  71 { $values { "first" class } { "second" class } { "class" class } }\r
  72 { $description "Outputs the smallest anonymous class containing both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;\r
  73 \r
  74 HELP: class-and\r
  75 { $values { "first" class } { "second" class } { "class" class } }\r
  76 { $description "Outputs the largest anonymous class contained in both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;\r
  77 \r
  78 HELP: classes-intersect?\r
  79 { $values { "first" class } { "second" class } { "?" "a boolean" } }\r
  80 { $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." } ;\r
  81 \r
  82 HELP: smallest-class\r
  83 { $values { "classes" "a sequence of class words" } { "class/f" { $maybe class } } }\r
  84 { $description "Outputs a minimum class from the given sequence." } ;\r