Vocabulary loader
Factor handbook » The language


The USE: and USING: words load vocabularies using the vocabulary loader. The vocabulary loader is implemented in the vocabs.loader vocabulary.

The vocabulary loader searches for vocabularies in a set of directories known as vocabulary roots.
Vocabulary roots

Vocabulary names map directly to source files inside these roots. A vocabulary named foo.bar is defined in foo/bar/bar.factor; that is, a source file named bar.factor within a bar directory nested inside a foo directory of a vocabulary root. Any level of nesting, separated by dots, is permitted.

The vocabulary directory - bar in our example - contains a source file:
foo/bar/bar.factor - the source file must define words in the foo.bar vocabulary with an IN: foo.bar form

Two other Factor source files, storing documentation and tests, respectively, may optionally be placed alongside the source file:
foo/bar/bar-docs.factor - documentation, see Writing documentation
foo/bar/bar-tests.factor - unit tests, see Unit testing

Optional text files may contain metadata.
Vocabulary metadata
Vocabulary icons

Vocabularies can also be loaded at run time, without altering the vocabulary search path. This is done by calling a word which loads a vocabulary if it is not in the image, doing nothing if it is:
require ( object -- )

The above word will only ever load a vocabulary once in a given session. Sometimes, two vocabularies require special code to interact. The following word is used to load one vocabulary when another is present:
require-when ( if then -- )

There is another word which unconditionally loads vocabulary from disk, regardless of whether or not is has already been loaded:
reload ( name -- )

For interactive development in the listener, calling reload directly is usually not necessary, since a better facility exists for Runtime code reloading.

Application vocabularies can define a main entry point, giving the user a convenient way to run the application:

run ( vocab -- )


See also
Vocabularies, The parser, Source files