"The listener evaluates Factor expressions read from a stream. The listener is the primary interface to the Factor runtime. Typically, you write Factor code in a text editor, then load it using the listener and test it."
"The listener knows when to expect more input by looking at the height of the stack. Parsing words such as " { $link POSTPONE: { } " leave elements on the parser stack, and corresponding words such as " { $link POSTPONE: } } " pop them."
$terpri
"A very common operation is to inspect the contents of the data stack in the listener:"
{ $subsection .s }
"Note that calls to " { $link .s } " can also be included inside words as a debugging aid, however a more convenient way to achieve this is to use the annotation facility. See " { $link "annotations" } "."
$terpri
"You can start a nested listener or exit a listener using the following words:"
{ $subsection listener }
{ $subsection bye }
"The following variables can be rebound inside a nested scope to customize the behavior of a listener; this can be done to create a development tool with a custom interaction loop:"
{ $subsection listener-prompt }
{ $subsection listener-hook }
{ $subsection datastack-hook }
"Finally, the multi-line expression reading word can be used independently of the rest of the listener:"
"The simplest way to distribute a piece of Factor code is in the form of a source file. Source files can be loaded in the listener:"
{ $subsection run-file }
"Another way to load a source file is to provide a path relative to the Factor installation directory:"
{ $subsection run-resource }
"Words remember which source file defines them; this can be used to update word definitions during development:"
{ $subsection reload }
"Details on the Factor source parser itself can be found in " { $link "parser" } "."
$terpri
"User-contributed libraries in the " { $snippet "contrib/" } " directory of the Factor distribution should be loaded via the high-level module system instead of the above words (" { $link "modules" } ")." ;
ARTICLE: "modules" "Modules and contributed libraries"
"The Factor distribution includes a selection of contributed libraries in the " { $snippet "contrib/" } " directory, which are managed by a simple module system."
$terpri
"To load " { $snippet "contrib/aim/" } " for instance, you simply issue the following command in the listener:"
{ $code "\"aim\" require" }
"The " { $link require } " word will load all dependencies and source files of the " { $snippet "aim" } " module."
{ $subsection require }
{ $subsection (require) }
"To define a new module named " { $snippet "frob" } ", create one of the following two files:"
"The module definition file should first list all required modules:"
{ $subsection POSTPONE: REQUIRES: }
"These modules will be loaded first. Next, the source files and unit tests, if any, have to be registered:"
{ $subsection POSTPONE: PROVIDE: }
"It is important that the module path name matches the module name passed to " { $link POSTPONE: PROVIDE: } ", which should be " { $snippet "frob" } " in the above example."
$terpri
"Here is a simple module definition taken from " { $snippet "contrib/concurrency/load.factor" } ":"
"If an expression entered in the listener throws an error, the error is printed to the output stream. A number of words facilitate interactive debugging of the error:"
{ $subsection :s }
{ $subsection :r }
{ $subsection :c }
{ $subsection :get }
{ $subsection :error }
{ $subsection :cc }
"If the error is recoverable, a list of restarts is also printed, and a numbered restart can be invoked:"
{ $subsection :res }
"You can read more about error handling in " { $link "errors" } "." ;
"The prettyprinter (see " { $link "prettyprint" } ") can turn any object into a source representation. Sometimes this source representation is hard to read for a human, so the inspector provides an alternative tabular view of an object:"
{ $subsection inspect }
"Once running, the inspector spawns a new nested listener with an " { $snippet "inspector" } " prompt. The inspector supports a number of commands:"
{ $subsection inspecting }
{ $subsection go }
{ $subsection up }
{ $subsection bye }
"An one-time inspector-like display can be shown without starting the inspector:"
{ $subsection describe }
"Word for getting very brief descriptions of words and general objects:"
{ $subsection synopsis }
{ $subsection summary } ;
ARTICLE: "memory" "Object memory"
"You can print object heap status information:"
{ $subsection room. }
{ $subsection heap-stats. }
"There are a pair of combinators, analogous to " { $link each } " and " { $link subset } ", which operate on the entire collection of objects in the object heap:"
"A unit test is a piece of code which starts with known input values, then compares the output of a word with an expected output, where the expected output is defined by the word's contract."
$terpri
"For example, if you were developing a word for computing symbolic derivatives, your unit tests would apply the word to certain input functions, comparing the results against the correct values."
$terpri
"If you maintain a complete collection of unit tests and run them frequently, then a failing unit test can allow you to accurately pinpoint a fault in your program. However, just because unit tests pass is not an indication the code is correct. Writing good unit tests is an art form, and encourages a certain approach to programming which results in simpler, more reusable code."
$terpri
"The following two words perform unit testing; they are usually placed inside test harness files which you run using " { $link run-file } ":"
"The word annotation feature modifies word definitions to add debugging code. You can restore the old definition by calling " { $link reload } " on the word in question."
{ $subsection watch }
{ $subsection break }
{ $subsection break-on }
{ $subsection profile }
"All of the above words are implemented using a single combinator which applies a quotation to a word definition to yield a new definition:"
{ $subsection annotate } ;
ARTICLE: "images" "Working with images"
"Factor is an " { $emphasis "image-based" } " system, meaning it integrates a persistence mechanism where the object heap can be checkpointed to disk and loaded back in. Every time Factor runs, it starts by loading an image. The image contains all code and data needed to run Factor in a \"ready-to-go\" form."
$terpri
"Image files are loaded by launching the Factor runtime with the image file as the first command line argument. Images are saved using one of the following two words; the latter takes an image path as a parameter:"
{ $subsection save }
{ $subsection save-image }
"A new image can also be built from sources; this is known as " { $emphasis "bootstrap" } ". Bootstrap is a two-step process. The first stage is the creation of a bootstrap image inside a running Factor instance:"
{ $subsection make-image }
"The second stage is initiated by running the resulting bootstrap image. This stage loads any additional platform-specific code, compiles all words, and dumps a new, final image." ;
