factor/library/words.facts

IN: words
USING: definitions help inspector kernel kernel-internals parser ;

HELP: execute "( word -- )"
{ $values { "word" "a word" } }
{ $description "Executes a word." }
{ $examples
    { $example ": twice dup execute execute ;\n: hello \"Hello\" print ;\n\\ hello twice" "Hello\nHello" }
} ;

HELP: word-props "( word -- props )"
{ $values { "word" "a word" } { "props" "a hashtable" } }
{ $description "Outputs a word's property hashtable." } ;

HELP: set-word-props "( props word -- )"
{ $values { "props" "a hashtable" } { "word" "a word" } }
{ $description "Sets a word's property hashtable." }
{ $notes "The given hashtable must not be a literal, since it will get mutated by future calls to " { $link set-word-prop } "." } ;

HELP: word-primitive "( word -- n )"
{ $values { "word" "a word" } { "n" "a non-negative integer" } }
{ $description "Outputs a word's primitive number." } ;

HELP: set-word-primitive "( n word -- )"
{ $values { "n" "a non-negative integer" } { "word" "a word" } }
{ $description "Sets a word's primitive number." }
{ $notes "Changing the primitive number does not update the execution token, and the word will still call its old definition until a subsequent call to " { $link update-xt } "." } ;

HELP: word-def "( word -- obj )"
{ $values { "word" "a word" } { "obj" "an object" } }
{ $description "Outputs a word's primitive parameter. This parameter is only used if the primitive number is 1 (compound definitions) or 2 (symbols)." } ;

HELP: set-word-def "( obj word -- )"
{ $values { "obj" "an object" } { "word" "a word" } }
{ $description "Sets a word's primitive parameter." }
$low-level-note ;

HELP: undefined f
{ $description "The class of undefined words." }
{ $see-also POSTPONE: DEFER: } ;

HELP: compound f
{ $description "The class of compound words." }
{ $see-also POSTPONE: : define-compound } ;

HELP: primitive f
{ $description "The class of primitive words." } ;

HELP: symbol f
{ $description "The class of symbols." }
{ $see-also POSTPONE: SYMBOL: define-symbol intern-symbol } ;

HELP: init-word "( word -- )"
{ $values { "word" "a word" } }
{ $description "Initializes a word output from the " { $link <word> } " primitive." } ;

HELP: word-prop "( word name -- value )"
{ $values { "word" "a word" } { "name" "a property name" } { "value" "a property value" } }
{ $description "Retrieves a word property. Word property names are conventionally strings." } ;

HELP: set-word-prop "( word value name -- )"
{ $values { "word" "a word" } { "value" "a property value" } { "name" "a property name" } }
{ $description "Stores a word property. Word property names are conventionally strings." } ;

HELP: remove-word-prop "( word name -- )"
{ $values { "word" "a word" } { "name" "a property name" } }
{ $description "Removes a word property, so future lookups will output " { $link f } " until it is set again. Word property names are conventionally strings." } ;

HELP: word-xt "( word -- xt )"
{ $values { "word" "a word" } { "xt" "an execution token integer" } }
{ $description "Outputs the machine code address of the word's definition." } ;

HELP: set-word-xt "( xt word -- )"
{ $values { "xt" "an execution token integer" } { "word" "a word" } }
{ $description "Sets the machine code address of the word's definition." }
{ $warning "This word is unsafe. Specifying an invalid address can corrupt memory and crash the runtime." }
{ $notes "This word is used by the compiler." } ;

HELP: uses "( word -- seq )"
{ $values { "word" "a word" } { "seq" "a sequence of words" } }
{ $description "Outputs a sequence of words directory called by the given word." }
{ $notes "The sequence will include the word itself if it is recursive." }
{ $see-also uses } ;

HELP: crossref f
{ $description "Variable. A graph whose vertices are words and edges are usages. See " { $link "graphs" } "." }
{ $see-also usage xref-words } ;

HELP: xref-word "( word -- )"
{ $values { "word" "a word" } }
{ $description "Adds a vertex representing this word, along with edges representing dependencies to the " { $link crossref } " graph." }
$low-level-note ;

HELP: usage "( word -- seq )"
{ $values { "word" "a word" } { "seq" "a sequence of words" } }
{ $description "Outputs a sequence of words that directly call the given word." }
{ $notes "The sequence will include the word itself if it is recursive." }
{ $see-also usage } ;

HELP: unxref-word* "( word -- )"
{ $values { "word" "a word" } }
{ $contract "Updates the word to cope with a callee being redefined." }
$low-level-note ;

HELP: unxref-word "( word -- )"
{ $values { "word" "a word" } }
{ $description "Remove the vertex representing the word from the " { $link crossref } " graph." }
$low-level-note ;

HELP: define "( word def primitive -- )"
{ $values { "word" "a word" } { "def" "an object" } { "primitive" "a non-negative integer" } }
{ $description "Defines a word and updates cross-referencing." }
$low-level-note
{ $see-also define-symbol define-compound } ;

HELP: define-symbol "( word -- )"
{ $values { "word" "a word" } }
{ $description "Defines the word to push itself on the stack when executed." } ;

HELP: intern-symbol "( word -- )"
{ $values { "word" "a word" } }
{ $description "If the word is undefined, makes it into a symbol which pushes itself on the stack when executed. If the word already has a definition, does nothing." } ;

HELP: define-compound "( word def -- )"
{ $values { "word" "a word" } { "def" "a quotation" } }
{ $description "Defines the word to call a quotation when executed." } ;

HELP: reset-word "( word -- )"
{ $values { "word" "a word" } }
{ $description "Reset word declarations." }
$low-level-note ;

HELP: reset-generic "( word -- )"
{ $values { "word" "a word" } }
{ $description "Reset word declarations and generic word properties." }
$low-level-note ;

HELP: (word) "( name vocab -- word )"
{ $values { "name" "a string" } { "vocab" "a string" } { "word" "a word" } }
{ $description "Allocates an uninterned word with the specified name and vocabulary. User code should call " { $link gensym } " to create uninterned words and " { $link create } " to create interned words." }
{ $see-also <word> } ;

HELP: <word> "( name vocab -- word )"
{ $values { "name" "a string" } { "vocab" "a string" } { "word" "a word" } }
{ $description "Allocates an uninterned word with the specified name and vocabulary, and a blank word properties hashtable. User code should call " { $link gensym } " to create uninterned words and " { $link create } " to create interned words." } ;

HELP: gensym "( -- word )"
{ $values { "word" "a word" } }
{ $description "Creates an uninterned word that is not equal to any other word in the system. Gensyms have an automatically-generated name based on a prefix and an incrementing counter." }
{ $examples { $example "gensym ." "G:260561" } }
{ $notes "Gensyms are often used as placeholder values that have no meaning of their own but must be unique. For example, the compiler uses gensyms to label sections of assembly code." } ;

HELP: define-temp "( quot -- word )"
{ $values { "quot" "a quotation" } { "word" "a word" } }
{ $description "Creates an uninterned word that will call " { $snippet "quot" } " when executed." }
{ $notes
    "The following phrases are equivalent:"
    { $code "[ 2 2 + . ] call" }
    { $code "[ 2 2 + . ] define-temp execute" }
} ;

HELP: definer "( word -- definer )"
{ $values { "word" "a word" } { "definer" "a word" } }
{ $description "Outputs the parsing word that defines the given word." }
{ $examples
    { $example ": foo ; \\ foo definer ." "POSTPONE: :" }
    { $example "SYMBOL: foo \\ foo definer ." "POSTPONE: SYMBOL:" }
} ;

HELP: bootstrapping? f
{ $description "Variable. Set by the library while bootstrap is in progress. Some parsing words need to behave differently during bootstrap." } ;

HELP: vocabularies f
{ $description "Variable. Holds a hashtable mapping vocabulary names to vocabularies." } ;

HELP: word "( -- word )"
{ $values { "word" "a word" } }
{ $description "Outputs the most recently defined word." }
{ $see-also save-location } ;

HELP: set-word "( -- word )"
{ $values { "word" "a word" } }
{ $description "Sets the recently defined word. Usually you would call " { $link save-location } " on a newly-defined word instead, which will in turn call this word." }
{ $see-also word } ;

HELP: vocabs "( -- seq )"
{ $values { "word" "a sequence of strings" } }
{ $description "Outputs a sequence of all defined vocabulary names." } ;

HELP: vocab "( name -- vocab )"
{ $values { "name" "a string" } { "vocab" "a hashtable" } }
{ $description "Outputs a named vocabulary, or " { $link f } " if no vocabulary with this name exists." } ;

HELP: ensure-vocab "( name -- )"
{ $values { "name" "a string" } }
{ $description "Creates a vocabulary if it does not already exist." } ;

HELP: words "( vocab -- seq )"
{ $values { "vocab" "a string" } { "seq" "a sequence of words" } }
{ $description "Outputs a sequence of words defined in the vocabulary, or " { $link f } " if no vocabulary with this name exists." } ;

HELP: all-words "( -- seq )"
{ $values { "seq" "a sequence of words" } }
{ $description "Outputs a sequence of all words in the dictionary." } ;

HELP: word-subset "( quot -- seq )"
{ $values { "quot" "a quotation with stack effect " { $snippet "( word -- ? )" } } { "seq" "a sequence of words" } }
{ $description "Outputs a sequence of words satisfying the predicate." } ;

HELP: xref-words "( -- )"
{ $description "Update the " { $link crossref } " graph of word dependencies. Usually this is done automatically." } ;

HELP: lookup "( name vocab -- word )"
{ $values { "name" "a string" } { "vocab" "a string" } { "word" "a word or " { $link f } } }
{ $description "Looks up a word in the dictionary. If the vocabulary or the word is not defined, outputs " { $link f } "." } ;

HELP: reveal "( word -- )"
{ $values { "word" "a word" } }
{ $description "Adds a newly-created word to the dictionary. Usually this word does not need to be called directly." }
{ $see-also create } ;

HELP: check-create "( name vocab -- name vocab )"
{ $values { "name" "a string" } { "vocab" "a string" } }
{ $description "Throws a " { $link check-create } " error if " { $snippet "name" } " or " { $snippet "vocab" } " is not a string." }
{ $error-description "Thrown if " { $link create } " is called with invalid parameters." } ;

HELP: create "( name vocab -- word )"
{ $values { "name" "a string" } { "vocab" "a string" } { "word" "a word" } }
{ $description "Creates a new word. Creates the vocabulary first if it does not already exist. If the vocabulary exists and already contains a word with the requested name, outputs the existing word." } ;

HELP: constructor-word "( name vocab -- word )"
{ $values { "name" "a string" } { "vocab" "a string" } { "word" "a word" } }
{ $description "Creates a new word, surrounding " { $snippet "name" } " in angle brackets." }
{ $examples { $example "\"salmon\" \"scratchpad\" constructor-word ." "<salmon>" } } ;

HELP: forget-word "( word -- )"
{ $values { "word" "a word" } }
{ $description "Removes a word from its vocabulary. The word becomes uninterned." }
{ $see-also POSTPONE: FORGET: forget-vocab forget } ;

HELP: forget-vocab "( vocab -- )"
{ $values { "vocab" "a string" } }
{ $description "Removes a vocabulary. All words in the vocabulary become uninterned." }
{ $see-also forget } ;

HELP: target-word "( word -- target )"
{ $values { "word" "a word" } { "target" "a word" } }
{ $description "Looks up a word with the same name and vocabulary as the given word. Used during bootstrap to transfer host words to the target dictionary." } ;

HELP: interned? "( word -- ? )"
{ $values { "word" "a word" } { "?" "a boolean" } }
{ $description "Test if the word is an interned word." } ;

HELP: bootstrap-word "( word -- target )"
{ $values { "word" "a word" } { "target" "a word" } }
{ $description "Looks up a word with the same name and vocabulary as the given word, performing a transformation to handle parsing words in the target dictionary. Used during bootstrap to transfer host words to the target dictionary." } ;

HELP: update-xt "( word -- )"
{ $values { "word" "a word" } }
{ $description "Updates a word's execution token based on the value of the " { $link word-primitive } " slot. If the word was compiled, this will lose the compiled definition and make it run in the interpreter." } ;

HELP: stack-effect "( word -- str )"
{ $values { "word" "a word" } { "str" "a string" } }
{ $description "Outputs the stack effect of a word, as a stack picture string. The stack effect is taken from either online help, or a cached inferred effect." } ;