Conventions - Factor Documentation (original) (raw)

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

Glossary of terms
Common terminology and abbreviations used throughout Factor and its documentation:

Term	Definition
alist	an association list; see Association lists
assoc	an associative mapping; see Associative mapping operations
associative mapping	an object whose class implements the Associative mapping protocol
boolean	t or f
class	a set of objects identified by a class word together with a discriminating predicate. See Classes
combinator	a word taking a quotation or another word as input; a higher-order function. See Combinators
definition specifier	an instance of definition which implements the Definition protocol
generalized boolean	an object interpreted as a boolean; a value of f denotes false and anything else denotes true
generic word	a word whose behavior depends on the class of one of its inputs. See Generic words and methods
method	a specialized behavior of a generic word on a class. See Generic words and methods
object	any datum which can be identified
ordering specifier	see Ordering specifiers
pathname string	an OS-specific pathname which identifies a file
quotation	an 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
sequence	a sequence; see Sequence protocol
slot	a component of an object which can store a value
stack effect	a pictorial representation of a word's inputs and outputs, for example + ( x y -- z ). See Stack effect declarations
true value	any object not equal to f
vocabulary or vocab	a named set of words. See Vocabularies
vocabulary specifier	a vocab, vocab-link or a string naming a vocabulary
word	the 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 form	Description	Examples
foo?	outputs a boolean	empty?
foo!	a variant of foo which mutates one of its arguments	append!
?foo	conditionally performs foo	?nth
<foo>	creates a new foo
>foo<	destroys an object of class foo, usually unpacking its data	>slice<
>foo	converts the top of the stack into a foo	>array
foo>bar	converts a foo into a bar	number>string
new-foo	creates a new foo, taking some kind of parameter from the stack which determines the type of the object to be created	new-sequence, new-lexer, new
foo*	alternative form of foo, or a generic word called by foo	at, pprint
(foo)	implementation detail word used by foo	(clone)
set-foo	sets foo to a new value	set-length
foo>>	gets the foo slot of the tuple at the top of the stack; see Slot accessors	name>>
>>foo	sets the foo slot of the tuple at the top of the stack; see Slot accessors	>>name
with-foo	performs some kind of initialization and cleanup related to foo, usually in a new dynamic scope	with-scope, with-input-stream, with-output-stream
foo∣helpmarkup∣[foo	help markup	[foo∣helpmarkup∣heading, $emphasis

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