-USING: classes classes.private help.markup help.syntax kernel
-math sequences ;
+USING: classes classes.algebra.private classes.private help.markup
+help.syntax kernel math sequences ;
IN: classes.algebra
ARTICLE: "class-operations" "Class operations"
{ $description "Tests if all instances of " { $snippet "class1" } " are also instances of " { $snippet "class2" } "." }
{ $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" } "." } ;
-HELP: sort-classes
-{ $values { "seq" "a sequence of class" } { "newseq" "a new sequence of classes" } }
-{ $description "Outputs a linear sort of a sequence of classes. Larger classes come before their subclasses." } ;
+HELP: class-and
+{ $values { "first" class } { "second" class } { "class" class } }
+{ $description "Outputs the largest anonymous class contained in both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
+
+HELP: class-not
+{ $values { "class" class } { "complement" class } }
+{ $description "Outputs the complement class of 'class'." } ;
HELP: class-or
{ $values { "first" class } { "second" class } { "class" class } }
{ $description "Outputs the smallest anonymous class containing both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
-HELP: class-and
-{ $values { "first" class } { "second" class } { "class" class } }
-{ $description "Outputs the largest anonymous class contained in both " { $snippet "class1" } " and " { $snippet "class2" } "." } ;
-
HELP: classes-intersect?
{ $values { "first" class } { "second" class } { "?" boolean } }
{ $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." } ;
+HELP: normalize-class
+{ $values { "class" class } { "class'" class } }
+{ $description "Normalizes a class in such a way that it becomes easier to perform algebra on it." } ;
+
HELP: smallest-class
{ $values { "classes" "a sequence of class words" } { "class/f" { $maybe class } } }
{ $description "Outputs a minimum class from the given sequence." } ;
+
+HELP: sort-classes
+{ $values { "seq" "a sequence of class" } { "newseq" "a new sequence of classes" } }
+{ $description "Outputs a linear sort of a sequence of classes. Larger classes come before their subclasses." } ;
{ $description "Defines a predicate word for a class." }
$low-level-note ;
+HELP: metaclass-changed
+{ $values { "use" class } { "class" class } }
+{ $description "Notifies the class 'class' that its metaclass 'use' has changed." } ;
+
HELP: predicate-def
{ $values { "obj" "a type object" } { "quot" quotation } }
{ $description "Outputs a quotation that can be used to check if objects are an instance of the given type." }
IN: classes.intersection
ARTICLE: "intersections" "Intersection classes"
-"An object is an instance of a intersection class if it is an instance of all of its participants."
+"An object is an instance of an intersection class if it is an instance of all of its participants."
{ $subsections POSTPONE: INTERSECTION: }
{ $subsections define-intersection-class }
"Intersection classes can be introspected:"
-USING: compiler.units.private definitions help.markup help.syntax kernel
-kernel.private parser quotations sequences source-files stack-checker.errors
-words ;
+USING: classes.tuple.private compiler.units.private definitions
+help.markup help.syntax kernel kernel.private parser quotations
+sequences source-files stack-checker.errors words ;
IN: compiler.units
ARTICLE: "compilation-units-internals" "Compilation units internals"
"A hook to be called at the end of the compilation unit. If the optimizing compiler is loaded, this compiles new words with the " { $link "compiler" } ":"
{ $subsections recompile }
"Low-level compiler interface exported by the Factor VM:"
-{ $subsections modify-code-heap } ;
+{ $subsections modify-code-heap }
+"Variables maintaining state within a compilation unit."
+{ $subsections
+ changed-definitions
+ maybe-changed
+ outdated-generics
+ outdated-tuples
+} ;
ARTICLE: "compilation-units" "Compilation units"
"A " { $emphasis "compilation unit" } " scopes a group of related definitions. They are compiled and entered into the system in one atomic operation."
{ $values { "?" boolean } }
{ $description "Whether the " { $link REDEFINITION-COUNTER } " should be increased." } ;
+HELP: new-definitions
+{ $var-description "Stores a pair of sets where the members form the set of definitions which were defined so far by the current parsing of " { $link current-source-file } "." } ;
+
+HELP: forgotten-definitions
+{ $var-description "All definitions (words and vocabs) that have been forgotten in the current compilation unit." } ;
+
HELP: old-definitions
{ $var-description "Stores a pair of sets where the members form the set of definitions which were defined by " { $link current-source-file } " the most recent time it was loaded." } ;
{ $values { "definition" "a definition specifier" } { "loc" "a " { $snippet "{ path line# }" } " pair" } }
{ $description "Saves the location of a definition and associates this definition with the current source file." } ;
-HELP: new-definitions
-{ $var-description "Stores a pair of sets where the members form the set of definitions which were defined so far by the current parsing of " { $link current-source-file } "." } ;
-
HELP: with-compilation-unit
{ $values { "quot" quotation } }
{ $description "Calls a quotation in a new compilation unit. The quotation can define new words and classes, as well as forget words. When the quotation returns, any changed words are recompiled, and changes are applied atomically." }
HELP: to-recompile
{ $values { "words" sequence } }
-{ $description "Sequence of words that will be recompiled by the compilation unit." } ;
+{ $description "Sequence of words that will be recompiled by the compilation unit. The non-optimizing compiler only recompiles words whose definitions has changed. But the optimizing compiler, which can perform optimizations such as inlining, recompiles words that depends on the changed words." } ;
HELP: no-compilation-unit
{ $values { "word" word } }
ABOUT: "definitions"
+HELP: changed-definition
+{ $values { "defspec" "definition" } }
+{ $description "Adds the definitio to the unit's " { $link changed-definitions } "." } ;
+
+HELP: changed-definitions
+{ $var-description "A set that contains all words and vocabs whose definitions have changed or are new. " }
+{ $see-also changed-definition } ;
+
HELP: changed-effects
{ $var-description "A set that contains all words whose stack effects have changed in the compilation unit." } ;
-HELP: set-where
-{ $values { "loc" "a " { $snippet "{ path line# }" } " pair" } { "defspec" "a definition specifier" } }
-{ $description "Sets the definition's location." }
-{ $notes "This word is used by the parser." } ;
-
HELP: forget
{ $values { "defspec" "a definition specifier" } }
{ $description "Forgets about a definition. For example, if it is a word, it will be removed from its vocabulary." }
{ $description "Forgets every definition in a sequence." }
{ $notes "This word must be called from inside " { $link with-compilation-unit } "." } ;
+HELP: maybe-changed
+{ $var-description "The set of definitions that has maybe changed in the compilation unit. For example, if a union class is redefined it will be added to this set because it is possible but not certain that it has become different." } ;
+
HELP: outdated-generics
{ $var-description "A " { $link hash-set } " where newly defined generic words are kept until they are being remade." }
{ $see-also remake-generic remake-generics } ;
+HELP: set-where
+{ $values { "loc" "a " { $snippet "{ path line# }" } " pair" } { "defspec" "a definition specifier" } }
+{ $description "Sets the definition's location." }
+{ $notes "This word is used by the parser." } ;
+
HELP: where
{ $values { "defspec" "a definition specifier" } { "loc" "a " { $snippet "{ path line# }" } " pair" } }
{ $description "Outputs the location of a definition. If the location is not known, will output " { $link f } "." } ;
ABOUT: "slots"
+HELP: bad-initial-value
+{ $error-description "Thrown by " { $link POSTPONE: TUPLE: } " if a slot has an impossible initial value. "
+ { $examples
+ { $unchecked-example
+ "TUPLE: a { b integer initial: \"invalid\" } ;"
+ "1: TUPLE: a { b integer initial: \"invalid\" } ;"
+ " ^"
+ "Incompatible initial value"
+ "name \"b\""
+ "initial-value \"invalid\""
+ "class integer"
+ ""
+ "Type :help for debugging help."
+ }
+ }
+} ;
+
HELP: slot-spec
{ $class-description "A slot specification. The " { $snippet "\"slots\"" } " word property of " { $link builtin-class } " and " { $link tuple-class } " instances holds sequences of slot specifications."
$nl
-USING: arrays assocs classes.tuple combinators command-line
-effects generic generic.math generic.single help.markup
-help.syntax io.pathnames kernel math parser sequences
-vocabs.loader vocabs.parser words words.alias words.constant
-words.symbol ;
+USING: arrays assocs classes.algebra.private classes.tuple combinators
+command-line effects generic generic.math generic.single help.markup
+help.syntax io.pathnames kernel math parser sequences vocabs.loader
+vocabs.parser words words.alias words.constant words.symbol ;
IN: syntax
ARTICLE: "parser-algorithm" "Parser algorithm"
{ $description "Marks the beginning of a literal byte array. Literal byte arrays are terminated by " { $link POSTPONE: } } "." }
{ $examples { $code "B{ 1 2 3 }" } } ;
+HELP: intersection{
+{ $syntax "intersection{ elements... }" }
+{ $values { "elements" "a list of classoids" } }
+{ $description "Marks the beginning of a literal " { $link anonymous-intersection } " class." } ;
+
HELP: H{
{ $syntax "H{ { key value }... }" }
{ $values { "key" object } { "value" object } }
HELP: add-vocab-root
{ $values { "root" "a pathname string" } }
{ $description "Adds a directory pathname to the list of vocabulary roots." }
-{ $see-also ".factor-roots" } ;
+{ $see-also ".factor-roots" add-vocab-root-hook } ;
+
+HELP: add-vocab-root-hook
+{ $var-description "A quotation that is run when a vocab root is added." }
+{ $see-also add-vocab-root } ;
HELP: find-vocab-root
{ $values { "vocab" "a vocabulary specifier" } { "path/f" "a pathname string" } }
{ { { $snippet "\"superclass\"" } ", " { $snippet "\"predicate-definition\"" } } { $link "predicates" } }
{ { $snippet "\"members\"" } { $link "unions" } { $link "maybes" } }
-
+ {
+ { $snippet "\"instances\"" }
+ { "Lists the instances of the mixin class and where they are defined - " { $link "mixins" } }
+ }
+ {
+ { $snippet "\"predicate\"" }
+ { "A quotation that tests if the top of the stack is an instance of this class - " { $link "class-predicates" } }
+ }
{ { $snippet "\"slots\"" } { $link "slots" } }
-
- { { $snippet "\"predicate\"" } { "A quotation that tests if the top of the stack is an instance of this class - " { $link "class-predicates" } } }
+ {
+ {
+ { $snippet "\"superclass\"" } ", "
+ { $snippet "\"predicate-definition\"" }
+ }
+ { $link "predicates" }
+ }
+ { { $snippet "\"type\"" } { $link "builtin-classes" } }
} ;
ARTICLE: "word.private" "Word implementation details"
HELP: changed-effect
{ $values { "word" word } }
-{ $description "Signals to the compilation unit that the word has changed. It causes all words that depend on it to be recompiled in response." } ;
+{ $description "Signals to the compilation unit that the effect of the word has changed. It causes all words that depend on it to be recompiled in response." }
+{ $see-also changed-effects } ;
HELP: deferred
{ $class-description "The class of deferred words created by " { $link POSTPONE: DEFER: } "." } ;