Conventions
Factor handbook ยป The language

Next:Syntax


Various conventions are used throughout the Factor documentation and source code.

Glossary of terms
Common terminology and abbreviations used throughout Factor and its documentation:
TermDefinition
alistan association list; see Association lists
assocan associative mapping; see Associative mapping operations
associative mappingan object whose class implements the Associative mapping protocol
booleant or f
classa set of objects identified by a class word together with a discriminating predicate. See Classes
combinatora word taking a quotation or another word as input; a higher-order function. See Combinators
definition specifieran instance of definition which implements the Definition protocol
generalized booleanan object interpreted as a boolean; a value of f denotes false and anything else denotes true
generic worda word whose behavior depends on the class of one of its inputs. See Generic words and methods
methoda specialized behavior of a generic word on a class. See Generic words and methods
objectany datum which can be identified
ordering specifiersee Ordering specifiers
pathname stringan OS-specific pathname which identifies a file
quotationan anonymous function; an instance of the quotation class. More generally, instances of the callable class can be used in many places documented to expect quotations
sequencea sequence; see Sequence protocol
slota component of an object which can store a value
stack effecta pictorial representation of a word's inputs and outputs, for example + ( x y -- z ). See Stack effect declarations
true valueany object not equal to f
vocabulary or vocaba named set of words. See Vocabularies
vocabulary specifiera vocab, vocab-link or a string naming a vocabulary
wordthe basic unit of code, analogous to a function or procedure in other programming languages. See Words


Documentation conventions
Factor documentation consists of two distinct bodies of text. There is a hierarchy of articles, much like this one, and there is word documentation. Help articles reference word documentation, and vice versa, but not every documented word is referenced from some help article.

The browser, completion popups and other tools use a common set of Definition icons.

Every article has links to parent articles at the top. Explore these if the article you are reading is too specific.

Some generic words have Description headings, and others have Contract headings. A distinction is made between words which are not intended to be extended with user-defined methods, and those that are.

Vocabulary naming conventions
A vocabulary name ending in .private contains words which are either implementation details, unsafe, or both. For example, the sequences.private vocabulary contains words which access sequence elements without bounds checking (Unsafe sequence operations). You should avoid using private words from the Factor library unless absolutely necessary. Similarly, your own code can place words in private vocabularies using <PRIVATE if you do not want other people using them without good reason.

Word naming conventions
These conventions are not hard and fast, but are usually a good first step in understanding a word's behavior:
General formDescriptionExamples
foo?outputs a booleanempty?
foo!a variant of foo which mutates one of its argumentsappend!
?fooconditionally performs foo?nth
<foo>creates a new foo<array>
>foo<destroys an object of class foo, usually unpacking its data>slice<
>fooconverts the top of the stack into a foo>array
foo>barconverts a foo into a barnumber>string
new-foocreates a new foo, taking some kind of parameter from the stack which determines the type of the object to be creatednew-sequence, new-lexer, new
foo*alternative form of foo, or a generic word called by fooat*, pprint*
(foo)implementation detail word used by foo(clone)
set-foosets foo to a new valueset-length
foo>>gets the foo slot of the tuple at the top of the stack; see Slot accessorsname>>
>>foosets the foo slot of the tuple at the top of the stack; see Slot accessors>>name
with-fooperforms some kind of initialization and cleanup related to foo, usually in a new dynamic scopewith-scope, with-input-stream, with-output-stream
$foohelp markup$heading, $emphasis


Stack effect conventions
Stack effect conventions are documented in Stack effect declarations.