diff --git a/TODO.FACTOR.txt b/TODO.FACTOR.txt
index d6ea091bc5..1f3aae6750 100644
--- a/TODO.FACTOR.txt
+++ b/TODO.FACTOR.txt
@@ -7,9 +7,8 @@ ERROR: I/O error: [ "primitive_read_line_fd_8" "Resource temporarily unavailable
 - decide if overflow is a fatal error
 - f >n: crashes
 - typecases: type error reporting bad
-- image output
 - floats
-- {...} vectors
+- {...} vectors in java factor
 - parsing should be parsing
 - describe-word
 - clone-sbuf
diff --git a/doc/compiler-impl.txt b/doc/compiler-impl.txt
new file mode 100644
index 0000000000..3edd9a5efe
--- /dev/null
+++ b/doc/compiler-impl.txt
@@ -0,0 +1,898 @@
+IMPLEMENTATION OF THE FACTOR COMPILER
+
+Compilation of Factor is a messy business, driven by heuristics and not
+formal theory. The compiler is inherently limited -- some expressions
+cannot be compiled by definition. The programmer must take care to
+ensure that performance-critical sections of code are written such that
+they can be compiled.
+
+=== Introduction
+
+==== The problem
+
+The Factor interpreter introduces a lot of overhead:
+
+- Execution of a quotation involves iteration down a linked list.
+
+- Stack access is not as fast as local variables, since Java
+  bound-checks all array accesses.
+
+- At the lowest level, everything is expressed as Java reflection calls
+  to the Factor and Java platform libraries. Java reflection is not as
+  fast as statically-compiled Java calls.
+
+- Since Factor is dynamically-typed, intermediate values on the stack
+  are all stored as java.lang.Object types, so type checks and
+  possibly coercions must be done at each step of the computation.
+
+==== The solution
+
+The following optimizations naturally suggest themselves, and lead to
+the implementation of the Factor compiler:
+
+- Compiling Factor code down to Java platform bytecode.
+
+- Using virtual machine local variables instead of an array stack to
+  store intermediate values.
+
+- Statically compiling in Java calls where the class, method and
+  variable names are known ahead of time.
+
+- Type inference and soft typing to eliminate unnecessary type checks.
+  (At the time of writing, this is in progress and is not documented in
+  this paper.)
+
+=== Preliminaries: interpreter internals
+
+A word object is essentially a property list. The one property we are
+concerned with here is "def", which holds a FactorWordDefinition object.
+
+The accessor word "worddef" pushes the "def" slot of a given word name
+or word object:
+
+    0] "+" worddef .
+#<factor.FactorCompoundDefinition: +>
+
+Generally, the word definition is an opaque object, however there are
+various ways to deconstruct it, which will not be convered here (see the
+worddef>list word if you are interested).
+
+When a word object is being executed, the eval() method of its
+definition is invoked. The eval() method takes one parameter, which is
+the FactorInterpreter instance. The interpreter instance provides access
+to the stacks, global namespace, vocabularies, and so on.
+
+(In this article, we will use the term "word" and "word definition"
+somewhat interchangably; this does not cause any confusion. If a "word"
+is mentioned where one would expect a definition, simply assume the
+"def" slot of the word is being accessed.)
+
+The class FactorWordDefinition is abstract; a number of subclasses
+exist:
+
+- FactorCompoundDefinition: a standard colon definition consisting of
+  a quotation; for example, : sq dup * ; is syntax for a compound
+  definition named "sq" with quotation [ dup * ].
+
+  Of course, its eval() method simply pushes the quotation on the
+  interpreter's callstack.
+
+- FactorShuffleDefinition: a stack rearrangement word, whose syntax is
+  described in detail in parser.txt. For example,
+  ~<< swap a b -- b a >>~ is syntax for a shuffle definition named
+  "swap" that exchanges the top two values on the data stack.
+
+- FactorPrimitiveDefinition: primitive word definitions are written in
+  Java. Various concrete subclasses of this class in the
+  factor.primitives package provide implementations of eval().
+
+When a word definition is compiled, the compiler dynamically generates a
+new class, creates a new instance, and replaces the "def" slot of the
+word in question with the instance of the compiled class.
+
+So the compiler's primary job is to generate appropriate Java bytecode
+for the eval() method.
+
+=== Preliminaries: the specimen
+
+Consider the following (naive) implementation of the Fibonacci sequence:
+
+: fib ( n -- nth fibonacci number )
+    dup 1 <= [
+        drop 1 
+    ] [
+        pred dup fib swap pred fib + 
+    ] ifte ;
+
+A quick overview of the words used here:
+
+- dup: a shuffle word that duplicates the top of the stack.
+
+- <=: compare the top two numbers on the stack.
+
+- drop: remove the top of the stack.
+
+- pred: decrement the top of the stack by one. Indeed, it is defined as
+  simply : pred 1 - ;.
+
+- swap: exchange the top two stack elements.
+
+- +: add the top two stack elements.
+
+- ifte: execute one of two given quotations, depending on the condition
+  on the stack.
+
+=== Java reflection
+
+The biggest performance improvement comes from the transformation of
+Java reflection calls into static bytecode.
+
+Indeed, when the compiler was first written, the only type of word it
+could compile were such simple expressions that interfaced with Java and
+nothing else.
+
+In the above definition of "fib", the three key words <= - and + (note
+that - is not referenced directly, but rather is a factor of the word
+pred). All three of these words are implemented as Java calls into the
+Factor math library:
+
+: <= ( a b -- boolean )
+    [
+        "java.lang.Number" "java.lang.Number" 
+    ] "factor.math.FactorMath" "lessEqual" jinvoke-static ;
+
+: - ( a b -- a-b )
+    [
+        "java.lang.Number" "java.lang.Number" 
+    ] "factor.math.FactorMath" "subtract" jinvoke-static ;
+
+: + ( a b -- a+b )
+    [
+        "java.lang.Number" "java.lang.Number" 
+    ] "factor.math.FactorMath" "add" jinvoke-static ;
+
+During interpretation, the execution of one of these words involves a
+lot of overhead. First, the argument list is transformed into a Java
+Class[] array; then the Class object corresponding to the containing
+class is looked up; then the appropriate Method object defined in this
+class is looked up; then the method is invoked, by passing it an
+Object[] array consisting of arguments from the stack.
+
+As one might guess, this is horribly inefficient. Indeed, look at the
+time taken to compute the 25th Fibonacci number using pure
+interpretation (of course depending on your hardware, results might
+vary):
+
+    0] [ 25 fib ] time
+24538
+
+One quickly notices that in fact, all the overhead from the reflection
+API is unnecessary; the containing class, method name and argument types
+are, after all, known ahead of time.
+
+For instance, the word "<=" might be compiled into the following
+pseudo-bytecode (the details are a bit more complex in reality; we'll
+get to it later):
+
+MOVE datastack[top - 2] to JVM stack // get operands in right order
+CHECKCAST java/lang/Number
+MOVE datastack[top - 1] to JVM stack
+CHECKCAST java/lang/Number
+DECREMENT datastack.top 2            // pop the operands
+INVOKESTATIC                         // invoke the method
+	"factor/FactorMath"
+	"lessEqual"
+	"(Ljava/lang/Number;Ljava/lang/Number;)Ljava/lang/Number;"
+MOVE JVM stack top to datastack      // push return value
+
+Notice that no dynamic class or method lookups are done, and no arrays
+are constructed; in fact, a modern Java virtual machine with a native
+code compiler should be able to transform an INVOKESTATIC into a simple
+subroutine call.
+
+So what how much overhead is eliminated in practice? It is easy to find
+out:
+
+    5] [ + - <= ] [ compile ] each
+    1] [ 25 fib ] time
+937
+
+This is still quite slow -- however, already we've gained a 26x speed
+improvement!
+
+Words consisting entirely of literal parameters to Java primitives such
+as jinvoke, jnew, jvar-get/set, or jvar-get/set-static are compiled in a
+similar manner; there is nothing new there.
+
+=== First attempt at compiling compound definitions
+
+Now consider the problem of compiling a word that does not directly call
+Java primitives, but instead calls other words, which are already been
+compiled.
+
+For instance, consider the following word (recall that (...) is a comment!):
+
+: mag2 ( x y -- sqrt[x*x+y*y] )
+    swap dup * swap dup * + sqrt ;
+
+Lets assume that 'swap', 'dup', '*' and '+' are defined as before, and
+that 'sqrt' is an already-compiled word that calls into the math
+library.
+
+Assume that the pseudo-bytecode INVOKEWORD <word> invokes the "eval"
+method of a FactorWordDefinition instance.
+
+(In reality, it is a bit more complex:
+
+GETFIELD ... some field that stores a FactorWordDefinition instance ...
+ALOAD 0 // push interpreter parameter to eval() on the stack
+INVOKEVIRTUAL
+	"factor/FactorWordDefinition"
+	"eval"
+	"(Lfactor/FactorInterpreter;)V"
+
+However the above takes up more space and adds no extra information over
+the INVOKE notation.)
+
+Now, we have the tools necessary to try compiling "mag2" as follows:
+
+INVOKEWORD swap
+INVOKEWORD dup
+INVOKEWORD *
+INVOKEWORD swap
+INVOKEWORD dup
+INVOKEWORD *
+INVOKEWORD +
+INVOKEWORD sqrt
+
+In other words, the words still shuffle values back and forth on the
+interpreter data stack as before; however, instead of the interpreter
+iterating down a word thread, compiled bytecode invokes words directly.
+
+This might seem like the obvious approach; however, it turns out it
+brings very little performance benefit over simply iterating down a
+linked list representing a quotation!
+
+What we would like to do is just eliminate use of the interpreter's
+stack for intermediate values altogether, and just loading the inputs at
+the beginning and storing them at the end.
+
+=== Avoiding the interpreter stack
+
+The JVM is a stack machine, however its semantics are so different that
+a direct mapping of interpreter stack use to stack bytecode would not
+be feasable:
+
+- No arbitrary stack access is allowed in Java; only a few, fixed stack
+  bytecodes like POP, DUP, SWAP are provided.
+
+- A Java function receives input parameters in local variables, not in
+  the JVM stack.
+
+In fact, the second point suggests that it is a better idea is to use
+JVM *local variables* for temporary storage in compiled definitions.
+
+Since no indirect addressing of locals is permitted, stack positions
+used in computations must be known ahead of time. This process is known
+as "stack effect deduction", and is the key concept of the Factor
+compiler.
+
+=== Fundamental idea: eval/core split
+
+Earlier, we showed pseudo-bytecode for the word <=, however it was noted
+that the reality is a bit more complicated.
+
+Recall that FactorWordDefinition.eval() takes an interpreter instance.
+It is the responsibility of this method to marshall and unmarshall
+values on the interpreter stack before and after the word performs any
+computation on the values.
+
+In actual fact, compiled word definitions have a second method named
+core(). Instead of accessing the interpreter data stack directly, this
+method takes inputs from formal parameters passed to the method, in the
+natural stack order.
+
+So, lets look at possible disassembly for the eval() and core() methods
+of the word <=:
+
+void eval(FactorInterpreter interp)
+
+ALOAD 0 // push interpreter instance on JVM stack
+MOVE datastack[top - 2] to JVM stack // get operands in right order
+CHECKCAST java/lang/Number
+MOVE datastack[top - 1] to JVM stack
+CHECKCAST java/lang/Number
+DECREMENT datastack.top 2            // pop the operands
+INVOKESTATIC                         // invoke the method
+	... compiled definition class name ...
+	"core"
+	"(Lfactor/FactorInterpreter;Ljava/lang/Object;Ljava/lang/Object;)
+	 Ljava/lang/Object;"
+MOVE JVM stack top to datastack      // push return value
+
+Object core(FactorInterpreter interp, Object x, Object y)
+
+ALOAD 0                              // push formal parameters
+ALOAD 1
+ALOAD 2
+INVOKESTATIC                         // invoke the actual method
+	"factor/FactorMath"
+	"lessEqual"
+	"(Ljava/lang/Number;Ljava/lang/Number;)Ljava/lang/Number;"
+ARETURN                              // pass return value up to eval()
+
+==== Using the JVM stack and locals for intermediates
+
+At first glance it seems nothing was achieved with the eval/core split,
+excepting an extra layer of overhead.
+
+However, the new revalation here is that compiled word definitions can
+call each other's core methods *directly*, passing in the parameters
+through JVM local variables, without the interpreter data stack being
+involved!
+
+Instead of pseudo-bytecode, from now on we will consider a very
+abstract, high level "register transfer language". The extra verbosity
+of bytecode will only distract from the key ideas.
+
+Tentatively, we would like to compile the word 'mag2' as follows:
+
+r0 * r0 -> r0
+r1 * r1 -> r1
+r0 + r1 -> r0
+sqrt r0 -> r0
+return r0
+
+However this looks very different from the original, RPN definition; in
+particular, we have named values, and the stack operations are gone!
+
+As it turns out, there is a automatic way to transform the stack program
+'mag2' into the register transfer program above (the reverse is also
+possible, but will not be discussed here).
+
+==== Stack effect deduction
+
+Consider the following quotation:
+
+[ swap dup * swap dup * + sqrt ]
+
+The transformation of the above stack code into register code consists
+of two passes.
+
+(A one-pass approach is also possible; however because of the design of
+the assembler used by the compiler, an extra pass will be required
+elsewhere if this transformation described here is single-pass).
+
+The first pass is simply to determine the total number of input and
+output parameters of the quotation (its "stack effect"). We proceed as
+follows.
+
+1. Create a 'simulated' datastack. It does not contain actual values,
+   but rather markers.
+
+   Set the input parameter count to zero.
+
+2. Iterate through each element of the quotation, and act as follows:
+
+   - If the element is a literal, allocate a simulated stack entry.
+
+   - If the element is a word, ensure that the stack has at least as
+     many items as the word's input parameter count.
+     
+     If the stack does not have enough items, increment the input
+     parameter count by the difference between the stack item count and
+     the word's expected input parameter count, and fill the stack with
+     the difference.
+
+     Decrement the stack pointer by the word's input parameter count.
+
+     Increment the stack pointer by the word's output parameter count,
+     filling the new entries with markers.
+
+3. When the end of the quotation is reached, the output parameter count
+   is the number of items on the simulated stack. The input parameter
+   count is the value of the intermediate parameter created in step 1.
+
+Note that this algorithm is recursive -- to determine the stack effect
+of a word, the stack effects of all its factors must be known. For now,
+assume the stack effects of words that use the Java primitives are
+"trivially" known.
+
+A brief walkthrough of the above algorithm for the quotation
+[ swap dup * swap dup * + sqrt ]:
+
+swap - the simulated stack is empty but swap expects two parameters,
+       so the input parameter count becomes 2.
+
+       two empty markers are pushed on the simulated stack:
+       # #
+
+dup  - requires one parameter, which is already present.
+       another empty marker is pushed on the simulated stack:
+       
+       # # #
+
+*    - requires two parameters, and returns one parameter, so the
+       simulated stack is now:
+       
+       # #
+
+swap - requires and returns two parameters.
+
+       # #
+
+dup  - requires one, returns two parameters.
+
+       # # #
+
+*    - requires two, and returns one parameter.
+
+       # #
+
++    - requires two, and returns one parameter.
+
+       #
+
+sqrt - requires one, and returns one parameter.
+
+       #
+
+So the input parameter count is two, and the output parameter count is
+one (since at the end of the quotation the simulated datastack contains
+one item marker).
+
+==== The dataflow algorithm
+
+The second pass of the compiler algorithm relies on the stack effect
+already being known. It consists of these steps:
+
+1. Create a new simulated stack. For each input parameter, a new entry
+   is allocated. This time, entries are not blank markers, but rather
+   register numbers.
+
+2. Iterate through each element of the quotation, and act as follows:
+
+   - If the element is a literal, allocate a simulated stack entry.
+     This time, allocation finds an unused register number by checking
+     each stack entry.
+
+   - If the element is a shuffle word, apply the shuffle to the
+     simulated stack *and do not emit any code!*
+
+   - If the element is another word, pop the appropriate number of
+     register numbers from the simulated stack, and emit assembly code
+     for invoking the word with parameters stored in these registers.
+
+     Decrement the simulated stack pointer by the word's input parameter
+     count.
+
+     Increment the simulated stack pointer by the word's output
+     parameter count, filling the new entries with newly-allocated
+     register numbers.
+
+     Emit assembly code for moving the return values of the word into
+     the newly allocated registers.
+
+Voila! The 'simulated stack' is a compile time only notion, and the
+resulting emitted code does not explicitly reference any stacks at all;
+in fact, applying this algorithm to the following quotation:
+
+[ swap dup * swap dup * + sqrt ]
+
+Yields the following output:
+
+r0 * r0 -> r0
+r1 * r1 -> r1
+r0 + r1 -> r0
+sqrt r0 -> r0
+return r0
+
+==== Multiple return values
+
+A minor implementation detail is multiple return values. Java does not
+support them directly, but a Factor word can return any number of
+values. This is implemented by temporarily using the interpreter data
+stack to return multiple values. This is the only time the interpreter
+data stack is used.
+
+==== The call stack
+
+Sometimes Factor code uses the call stack as an 'extra hand' for
+temporary storage:
+
+dup >r + r> *
+
+The dataflow algorithm can be trivially generalized with two simulated
+stacks; there is nothing more to be said about this.
+
+=== Questioning assumptions
+
+The dataflow compilation algorithm gives us another nice performance
+improvement. However, the algorithm assumes that the stack effect of
+each word is known a priori, or can be deduced using the algorithm.
+
+The algorithm falls down when faced with the following more complicated 
+expressions:
+
+- Combinators calling the 'call' and 'ifte' primitives
+
+- Recursive words
+
+So ironically, this algorithm is unsuitable for code where it would help
+the most -- complex code with a lot of branching, and tight loops and
+recursions.
+
+=== Eliminating explicit 'call':
+
+As described above, the dataflow algorithm would break when it
+encountered the 'call' primitive:
+
+[ 2 + ] 5 swap call
+
+The 'call' primitive executes the quotation at the top of the stack. So
+its stack effect depends on its input parameter!
+
+The first problem we faced was compilation of Java reflection
+primitives. A critical observation was that all the information to
+compile them efficiently was 'already there' in the source.
+
+Our intuitition tells us that in the above code, the occurrence of
+'call' *always* receives the parameter of [ 2 + ]; so somehow, the
+quotation can be transformed into the following, which we can already
+compile:
+
+[ 2 + ] 5 swap drop 2 +
+               ^^^^^^^^
+	       "immediate instantiation" of 'call'
+
+Or indeed, once the unused literal [ 2 + ] is factored out, simply:
+
+5 2 +
+
+==== Generalizing the 'simulated stack'
+
+It might seem surprising that such expressions can be easily compiled,
+once the 'simulated stack' is generalized such that it can hold literal
+values!
+
+The only change that needs to be made, is that in both passes, when a
+literal is encountered, it is pushed directly on the simulated stack.
+
+Also, when the primitive 'call' is encountered, its stack effect is
+assumed to be the stack effect of the literal quotation at the top of
+the simulated stack.
+
+(What if the top of the simulated stack is a register number? The word
+cannot be compiled, since the stack effect can potentially be
+arbitrary!)
+
+Being able to compile 'call' whose parameters are literals from the
+same word definition doesn't really add nothing new.
+
+A real breakthrough would be compiling "combinators"; words that take
+parameters that are themselves quotations.
+
+As it turns out, combinators themselves are not compiled -- however,
+specific *instances* of combinators in other word definitions are.
+
+For example, we can rewrite our word 'mag2' as follows:
+
+: mag2 ( x y -- sqrt[x*x+y*y] )
+    [ sq ] 2apply + sqrt ;
+
+Where 2apply is defined as follows:
+
+: 2apply ( x y [ code ] -- )
+    2dup 2>r nip call 2r> call ;
+
+How can we compile this new, equivalent, form of 'mag2'?
+
+==== Inline words
+
+Normally, when the dataflow algorithm encounters a word as an element
+of a quotation, a call to that word's core() method is emitted. However,
+if the word is compiled 'immediately', its definition is substituted in.
+
+Assume for a second that in the new form of 'mag2', the word '2apply' is
+compiled inline (ignoring the specifics of how this decision is made).
+In other words, it is as if 'mag2' was defined as follows:
+
+: mag2 ( x y -- sqrt[x*x+y*y] )
+    [ sq ] 2dup 2>r nip call 2r> call + sqrt ;
+
+However, we already have a way of compiling the above code; in fact it
+is compiled into the equivalent of:
+
+: mag2 ( x y -- sqrt[x*x+y*y] )
+    [ sq ] 2dup 2>r nip drop sq 2r> drop sq + sqrt ;
+                        ^^^^^^^     ^^^^^^^
+			immediate instantiation of 'call'
+
+As an aside, recall that the stack words 2dup, 2>r, nip, drop, and 2r>
+do not emit any code, and the 'drop' of the literal [ sq ] ensures that
+it never makes it to the compiled definition. The end-result is that the
+register-transfer code is identical to the earlier definition of 'mag2'
+which did not involve 2apply:
+
+r0 * r0 -> r0
+r1 * r1 -> r1
+r0 + r1 -> r0
+sqrt r0 -> r0
+return r0
+
+So, how is the decision made to compile a word inline, or not? It is
+quite simple. If the word has a deducable stack effect on the simulated
+stack of the current compilation, but it does *not* have a deducable
+stack effect on an empty simulated stack, it is compiled immediate.
+
+For example, the following word has a deducable stack effect, regardless
+of the values of any literals on the simulated stack:
+
+: sq ( x -- x^2 )
+    dup * ;
+
+So the word 'sq' is always compiled normally.
+
+However, the '2apply' word we saw earlier does not have a deducable
+stack effect unless there is a literal quotation at the top of the
+simulated stack:
+
+: 2apply ( x y [ code ] -- )
+    2dup 2>r nip call 2r> call ;
+
+So it is compiled inline.
+
+Sometimes it is desirable to have short non-combinator words inlined.
+While this is not necessary (whereas non-inlined combinators do not
+compile), it can increase performance, especially if the word returns
+multiple values (and without inlining, the interpreter datastack will
+need to be used).
+
+To mark a word for inline compilation, use the word 'inline' like so:
+
+: sq ( x -- x^2 )
+    dup * ; inline
+
+The word 'inline' sets the inline slot of the most recently defined word
+object.
+
+(Indeed, to push a reference to the most recently defined word object,
+use the word 'word').
+
+=== Branching
+
+The only branching primitive supported by factor is 'ifte'. The syntax
+is as follows:
+
+2 2 + 4 = ( condition that leaves boolean on the stack )
+[
+    ( code to execute if condition is true )
+] [
+    ( code to execute if condition is false )
+] ifte
+
+Note that the different components might be spread between words, and
+affected by stack operations in transit. Due to the dataflow algorithm
+and inlining, all useful cases can be handled correctly.
+
+==== Not all branching forms have a deducable stack effect
+
+The first observation we gain is that if the two branches leave the
+stack in inconsistent states, then stack positions used by subsequent
+code will depend on the outcome of the branch.
+
+This practice is discouraged anyway -- it leads to hard-to-understand
+code -- so it is not supported by the compiler. If you must do it, the
+words will always run in the interpreter.
+
+Attempting to compile or balance an expression with such a branch raises
+an error:
+
+    9] : bad-ifte 3 = [ 1 2 3 ] [ 2 2 + ] ifte ;
+    10] word effect .
+break called.
+
+:r prints the callstack.
+:j prints the Java stack.
+:x returns to top level.
+:s returns to top level, retaining the data stack.
+:g continues execution (but expect another error).
+
+ERROR: Stack effect of [ 1 2 3 ] ( java.lang.Object -- java.lang.Object
+java.lang.Object java.lang.Object ) is inconsistent with [ 2 2 + ] (
+java.lang.Object -- java.lang.Object )
+Head is ( java.lang.Object -- )
+Recursive state:
+[ #<ifte,base=null,effect=( java.lang.Object -- boolean java.lang.Object
+java.lang.Object ); null.null()> #<bad-ifte,base=null,effect=( -- );
+null.null()> ]
+
+==== Merging
+
+Lets return to our register transfer language, and add a branching
+notation:
+
+- two-instruction sequence to branch to <label> if <register> is null
+  ALOAD <register>
+  IFNULL <label>
+
+- unconditional goto to <label>
+  GOTO <label>
+
+So a simple conditional
+
+rot [
+    (true)
+] [
+    (false)
+] ifte
+
+Will be compiled as follows, where the inputs are in registers 1, 2, 3
+
+1	ALOAD 1
+2	IFNULL 5
+3	(true)
+4	GOTO 6
+5	(false)
+6	RETURN
+
+However the question arises, what becomes of the simulated stack after
+the branches are done.
+
+For example, consider this snippet:
+
+random-int random-int random-boolean [
+    swap
+] [
+    
+] ifte
+
+The first three words followed by the branch itself are compiled like
+so:
+
+1	1 <- random-int
+2	2 <- random-int
+3	3 <- random-boolean
+4	ALOAD 3
+5	IFNULL 8
+
+However, a problem arises because if the true branch is taken, the
+simulated stack contains register 1 at the top, and register 2 below;
+but if the false branch is taken, it is the opposite!
+
+The solution is to "merge" the stacks at the end of each branch. So
+the remainder of our code might be compiled as follows:
+
+6	1 <-> 2 // new notation: exchange registers 1 and 2
+7	GOTO 8
+8	RETURN
+
+=== Recursion
+
+Consider our old friend 'fib':
+
+: fib ( n -- nth fibonacci number )
+    dup 1 <= [
+        drop 1 
+    ] [
+        pred dup fib swap pred fib + 
+    ] ifte ;
+
+Using the tools we have, we cannot deduce its stack effect yet, since
+the false branch of the 'ifte' refers to the word 'fib' itself.
+
+A critical observation is if the word is to complete, eventually, the
+test will fail and 'drop 1' will be executed.
+
+Note that this implies that when given a parameter of 0 or 1, the
+stack effect of 'fib' is ( X -- X ).
+
+==== What is the stack effect?
+
+To see how to deduce the stack effect of the recursive case, it is
+necessary to make a mental leap. Consider the case where the parameter
+to fib is 2. The word recurses twice, and in each case, the parameter
+to the recursive call is <= 1, so 'drop 1' is executed.
+
+So when the parameter is 2, the stack effect is also ( X -- X )!
+
+In fact it is not hard to usee that if the stack effect of 'fib' with
+parameter n-1 and n-2 is ( X -- X ), then the stack effect of 'fib' with
+parameter n is also ( X -- X ).
+
+Therefore by induction, for any input, 'fib' has stack effect
+( X -- X ).
+
+Once the stack effect is known, it is easy enough to compile; just treat
+the two recursive calls like calls to any other word with stack effect
+( X -- X ).
+
+==== Not all recursive forms have a deducable stack effect
+
+Consider the following word:
+
+: push ( list -- ... )
+    dup [
+        uncons push
+    ] unless ;
+
+If the top of the stack is null, the word returns. So the base case is (
+X -- X ).
+
+However if the top of the stack is a list of one element, the word has
+stack effect ( X -- X X ), since 'uncons' has stack effect ( X -- X X )
+and the base case is ( X -- X ).
+
+If we proceed, we find that if the top of the stack is a list of two
+elements, the stack effect of the word is ( X -- X X X ).
+
+The stack positions used for intermediate values can no longer be
+determined ahead of time.
+
+A word whose stack effect depends on input is said to 'diverge'. Since
+it is generally good practice to only write converging recursive words,
+it is not a big loss that the compiler does not support them. Of course,
+such words still work in the interpreter.
+
+==== Auxiliary methods
+
+So far, we can compile recursive words such as 'fib' and tail-recursive
+words such as 'list?'. Now, lets try applying our techniques to a word
+that calls a recursive combinator:
+
+: reverse ( list -- list )
+    [ ] swap [ swons ] each ;
+
+Recall that 'swons' creates a cons cell with stack effect
+( cdr car -- [ car , cdr ] ) -- the opposite order of 'cons', which has stack effect ( car cdr -- [ car , cdr ] ).
+
+The combinator 'each' is defined as follows:
+
+: each ( [ list ] [ quotation ] -- )
+    over [
+        >r uncons r> tuck 2>r call 2r> each
+    ] [
+        2drop
+    ] ifte ;
+
+If we apply our previous inling technique, however, the end result is
+absurd, since the recursive call to 'each' remains:
+
+: reverse ( list -- list )
+    f swap [ swons ] over [
+        >r uncons r> tuck 2>r call 2r> each
+    ] [
+        2drop
+    ] ifte ;
+
+However, if the recursive call is changed to 'reverse', then the result
+is also incorrect, since '[ ] swap' would be executed on each iteration.
+
+The solution is to place instances of recursive combinators in an
+'auxiliary method' in the same class as the definition being compiled.
+
+So in fact, 'reverse' is compiled as three methods, eval(), core(), and 
+aux_each_0().
+
+==== Wrapping up
+
+There are two implementation details not covered here; they are not
+really 'interesting' and best described by the source code anyway:
+
+- tail-recursive words are compiled with a GOTO not a method invocation
+  at the end of the recursive case.
+
+- some extra steps are needed to normalize the stack after recursive
+  calls, and when auxiliary methods are being generated.
+
+=== Conclusion
+
+Finally, lets see what kind of improvement we get over naive
+interpretation when our old friend the 'fib' word is compiled using all
+the techniques mentioned above:
+
+    3] "fib" compile
+    4] [ 25 fib ] time
+123
+
+That's right -- a 200x improvement over pure interpretation.
diff --git a/doc/devel-guide.lyx b/doc/devel-guide.lyx
new file mode 100644
index 0000000000..b6d9eed6d6
--- /dev/null
+++ b/doc/devel-guide.lyx
@@ -0,0 +1,3927 @@
+#LyX 1.3 created this file. For more info see http://www.lyx.org/
+\lyxformat 221
+\textclass article
+\language english
+\inputencoding auto
+\fontscheme default
+\graphics default
+\paperfontsize default
+\spacing single 
+\papersize Default
+\paperpackage a4
+\use_geometry 0
+\use_amsmath 0
+\use_natbib 0
+\use_numerical_citations 0
+\paperorientation portrait
+\secnumdepth 3
+\tocdepth 2
+\paragraph_separation skip
+\defskip medskip
+\quotes_language english
+\quotes_times 2
+\papercolumns 1
+\papersides 1
+\paperpagestyle headings
+
+\layout Title
+
+Factor Developer's Guide
+\layout Author
+
+Slava Pestov
+\layout Standard
+
+
+\begin_inset LatexCommand \tableofcontents{}
+
+\end_inset 
+
+
+\layout Section*
+\pagebreak_top 
+Introduction
+\layout Standard
+
+Factor is an imperitive programming language with functional and object-oriented
+ influences.
+ Its primary goal is to be used for web-based server-side applications.
+ Factor is interpreted by a virtual machine that provides garbage collection
+ and prohibits pointer arithmetic.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+Two releases of Factor are available -- a virtual machine written in C,
+ and an interpreter written in Java that runs on the Java virtual machine.
+ This guide targets the C version of Factor.
+\end_inset 
+
+
+\layout Standard
+
+Factor borrows heavily from Forth, Joy and Lisp.
+ From Forth it inherits a flexible syntax defined in terms of 
+\begin_inset Quotes eld
+\end_inset 
+
+parsing words
+\begin_inset Quotes erd
+\end_inset 
+
+ and an execution model based on a data stack and call stack.
+ From Joy and Lisp it inherits a virtual machine prohibiting direct pointer
+ arithmetic, and the use of 
+\begin_inset Quotes eld
+\end_inset 
+
+cons cells
+\begin_inset Quotes erd
+\end_inset 
+
+ to represent code and data struture.
+\layout Section
+
+Fundamentals
+\layout Standard
+
+A "word" is the main unit of program organization in Factor -- it corresponds
+ to a "function", "procedure" or "method" in other languages.
+\layout Standard
+
+When code examples are given, the input is in a roman font, and any output
+ from the interpreter is in italics:
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+Hello, world!
+\begin_inset Quotes erd
+\end_inset 
+
+ print
+\layout LyX-Code
+
+
+\emph on 
+Hello, world!
+\layout Subsection
+
+The stack
+\layout Standard
+
+The stack is used to exchange data between words.
+ When a number is executed, it is pushed on the stack.
+ When a word is executed, it receives input parameters by removing successive
+ elements from the top of the stack.
+ Results are then pushed back to the top of the stack.
+ 
+\layout Standard
+
+The word 
+\family typewriter 
+.s
+\family default 
+ prints the contents of the stack, leaving the contents of the stack unaffected.
+ The top of the stack is the rightmost element in the printout:
+\layout LyX-Code
+
+2 3 .s
+\layout LyX-Code
+
+
+\emph on 
+{ 2 3 }
+\layout Standard
+
+The word 
+\family typewriter 
+.
+
+\family default 
+ removes the object at the top of the stack, and prints it:
+\layout LyX-Code
+
+1 2 3 .
+ .
+ .
+\layout LyX-Code
+
+
+\emph on 
+3
+\layout LyX-Code
+
+
+\emph on 
+2
+\layout LyX-Code
+
+
+\emph on 
+1
+\layout Standard
+
+The usual arithmetic operators 
+\family typewriter 
++ - * /
+\family default 
+ all take two parameters from the stack, and push one result back.
+ Where the order of operands matters (
+\family typewriter 
+-
+\family default 
+ and 
+\family typewriter 
+/
+\family default 
+), the operands are taken from the stack in the natural order.
+ For example:
+\layout LyX-Code
+
+10 17 + .
+\layout LyX-Code
+
+
+\emph on 
+27
+\layout LyX-Code
+
+111 234 - .
+\layout LyX-Code
+
+
+\emph on 
+-123
+\layout LyX-Code
+
+333 3 / .
+\layout LyX-Code
+
+
+\emph on 
+111
+\layout Standard
+
+This type of arithmetic is called 
+\emph on 
+postfix
+\emph default 
+, because the operator follows the operands.
+ Contrast this with 
+\emph on 
+infix
+\emph default 
+ notation used in many other languages, so-called because the operator is
+ in-between the two operands.
+\layout Standard
+
+More complicated infix expressions can be translated into postfix by translating
+ the inner-most parts first.
+ Grouping parantheses are never necessary:
+\layout LyX-Code
+
+! Postfix equivalent of (2 + 3) * 6
+\layout LyX-Code
+
+2 3 + 6 *
+\layout LyX-Code
+
+
+\emph on 
+36
+\layout LyX-Code
+
+! Postfix equivalent of 2 + (3 * 6)
+\layout LyX-Code
+
+2 3 6 * +
+\layout LyX-Code
+
+
+\emph on 
+20
+\layout Subsection
+
+Factoring
+\layout Standard
+
+New words can be defined in terms of existing words using the 
+\emph on 
+colon definition
+\emph default 
+ syntax:
+\layout LyX-Code
+
+: 
+\emph on 
+name
+\emph default 
+ (
+\emph on 
+ inputs 
+\emph default 
+--
+\emph on 
+ outputs
+\emph default 
+ )
+\layout LyX-Code
+
+    #! 
+\emph on 
+Description
+\layout LyX-Code
+
+    
+\emph on 
+factors ...
+ 
+\emph default 
+;
+\layout Standard
+
+When the new word is executed, each one of its factors gets executed, in
+ turn.
+ The comment delimited by 
+\family typewriter 
+(
+\family default 
+ and 
+\family typewriter 
+)
+\family default 
+ is called a stack effect comment and is described later.
+ The stack effect comment, as well as the documentation comment starting
+ with 
+\family typewriter 
+#!
+\family default 
+ are both optional, and can be placed anywhere in the source code, not just
+ in colon definitions.
+\layout Standard
+
+Note that in a source file, a word definition can span multiple lines.
+ However, the interactive interpreter expects each line of input to be 
+\begin_inset Quotes eld
+\end_inset 
+
+complete
+\begin_inset Quotes erd
+\end_inset 
+
+, so interactively, colon definitions must be entered all on one line.
+\layout Standard
+
+For example, lets assume we are designing some software for an aircraft
+ navigation system.
+ Lets assume that internally, all lengths are stored in meters, and all
+ times are stored in seconds.
+ We can define words for converting from kilometers to meters, and hours
+ and minutes to seconds:
+\layout LyX-Code
+
+: kilometers 1000 * ;
+\layout LyX-Code
+
+: minutes 60 * ;
+\layout LyX-Code
+
+: hours 60 * 60 * ;
+\layout LyX-Code
+
+2 km .
+\layout LyX-Code
+
+
+\emph on 
+2000
+\layout LyX-Code
+
+10 minutes .
+\layout LyX-Code
+
+
+\emph on 
+600
+\layout LyX-Code
+
+2 hours .
+\layout LyX-Code
+
+
+\emph on 
+7200
+\layout Standard
+
+Now, suppose we need a word that takes the flight time, the aircraft velocity,
+ and the tailwind velocity, and returns the distance travelled.
+ If the parameters are given on the stack in that order, all we do is add
+ the top two elements (aircraft velocity, tailwind velocity) and multiply
+ it by the element underneath (flight time).
+ So the definition looks like this, this time with a stack effect comment
+ since its slightly less obvious what the operands are:
+\layout LyX-Code
+
+: distance ( time aircraft tailwind -- distance ) + * ;
+\layout LyX-Code
+
+2 900 36 distance .
+\layout LyX-Code
+
+
+\emph on 
+1872
+\layout Standard
+
+Note that we are not using any units here.
+ We could, if we defined some words for velocity units first.
+ The only non-trivial thing here is the implementation of 
+\family typewriter 
+km/hour
+\family default 
+ -- we have to divide the 
+\family typewriter 
+km/sec
+\family default 
+ velocity by the number of seconds in one hour to get the desired result:
+\layout LyX-Code
+
+: km/hour kilometers 1 hours / ;
+\layout LyX-Code
+
+2 hours 900 km/hour 36 km/hour distance .
+\layout LyX-Code
+
+
+\emph on 
+1872000
+\layout Subsection
+
+Stack effects
+\layout Standard
+
+A stack effect comment contains a description of inputs to the left of 
+\family typewriter 
+--
+\family default 
+, and a description of outputs to the right.
+ As always, the top of the stack is on the right side.
+ Lets try writing a word to compute the cube of a number.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+I'd use the somewhat simpler example of a word that squares a number, but
+ such a word already exists in the standard library.
+ Its in the 
+\family typewriter 
+arithmetic
+\family default 
+ vocabulary, named 
+\family typewriter 
+sq
+\family default 
+.
+\end_inset 
+
+ 
+\layout Standard
+
+Three numbers on the stack can be multiplied together using 
+\family typewriter 
+* *
+\family default 
+:
+\layout LyX-Code
+
+2 4 8 * * .
+\layout LyX-Code
+
+
+\emph on 
+64
+\layout Standard
+
+However, the stack effect of 
+\family typewriter 
+* *
+\family default 
+ is 
+\family typewriter 
+( a b c -- a*b*c )
+\family default 
+.
+ We would like to write word that takes 
+\emph on 
+one
+\emph default 
+ input only.
+ To achive this, we need to be able to duplicate the top stack element twice.
+ As it happends, there is a word 
+\family typewriter 
+dup ( x -- x x )
+\family default 
+ for precisely this purpose.
+ Now, we are able to define the 
+\family typewriter 
+cube
+\family default 
+ word:
+\layout LyX-Code
+
+: cube dup dup * * ;
+\layout LyX-Code
+
+10 cube .
+\layout LyX-Code
+
+
+\emph on 
+1000
+\layout LyX-Code
+
+-2 cube .
+\layout LyX-Code
+
+
+\emph on 
+-8
+\layout Standard
+
+It is quite often the case that we want to compose two factors in a colon
+ definition, but their stack effects don't 
+\begin_inset Quotes eld
+\end_inset 
+
+match up
+\begin_inset Quotes erd
+\end_inset 
+
+.
+\layout Standard
+
+There is a set of 
+\emph on 
+shuffle words
+\emph default 
+ for solving precisely this problem.
+ These words are so-called because they simply rearrange stack elements
+ in some fashion, without modifying them in any way.
+ Lets take a look at the most frequently-used shuffle words:
+\layout Standard
+
+
+\family typewriter 
+drop ( x -- )
+\family default 
+ Discard the top stack element.
+ Used when a return value is not needed.
+\layout Standard
+
+
+\family typewriter 
+dup ( x -- x x )
+\family default 
+ Duplicate the top stack element.
+ Used when a value is needed more than once.
+\layout Standard
+
+
+\family typewriter 
+swap ( x y -- y x )
+\family default 
+ Swap top two stack elements.
+ Used when a word expects parameters in a different order.
+\layout Standard
+
+
+\family typewriter 
+rot ( x y z -- y z x )
+\family default 
+ Rotate top three stack elements to the left.
+\layout Standard
+
+
+\family typewriter 
+-rot ( x y z -- z x y )
+\family default 
+ Rotate top three stack elements to the right.
+\layout Standard
+
+
+\family typewriter 
+over ( x y -- x y x )
+\family default 
+ Bring the second stack element 
+\begin_inset Quotes eld
+\end_inset 
+
+over
+\begin_inset Quotes erd
+\end_inset 
+
+ the top element.
+\layout Standard
+
+
+\family typewriter 
+nip ( x y -- y )
+\family default 
+ Remove the second stack element.
+\layout Standard
+
+
+\family typewriter 
+tuck ( x y -- y x y )
+\family default 
+ Tuck the top stack element under the second stack element.
+\layout Standard
+
+You can try all these words out -- push some numbers on the stack, execute
+ a word, and look at how the stack contents was changed using 
+\family typewriter 
+.s
+\family default 
+.
+ Compare the stack contents with the stack effects above.
+\layout Standard
+
+Note the order of the shuffle word descriptions above.
+ The ones at the top are used most often because they are easy to understand.
+ The more complex ones such as rot should be avoided as possible, because
+ they make the flow of data in a word definition harder to understand.
+\layout Standard
+
+If you find yourself using too many shuffle words, or you're writing a stack
+ effect comment in the middle of a colon definition, it is a good sign that
+ the word should probably be factored into two or more words.
+ Effective factoring is like riding a bicycle -- it is hard at first, but
+ then you 
+\begin_inset Quotes eld
+\end_inset 
+
+get it
+\begin_inset Quotes erd
+\end_inset 
+
+, and writing small, clear and reusable word definitions becomes second-nature.
+\layout Subsection
+
+Combinators
+\layout Standard
+
+A quotation a list of objects that can be executed.
+ Words that operate on quotations are called 
+\emph on 
+combinators
+\emph default 
+.
+ Quotations are input using the following syntax:
+\layout LyX-Code
+
+[ 2 3 + .
+ ]
+\layout Standard
+
+When input, a quotation is not executed immediately -- rather, it becomes
+ one object on the stack.
+ Try evaluating the following:
+\layout LyX-Code
+
+[ 1 2 3 + * ] .s
+\layout LyX-Code
+
+
+\emph on 
+{ [ 1 2 3 + * ] }
+\layout LyX-Code
+
+call .s
+\layout LyX-Code
+
+
+\emph on 
+{ 5 }
+\layout Standard
+
+
+\family typewriter 
+call
+\family default 
+ 
+\family typewriter 
+( quot -- )
+\family default 
+ executes the quotation at the top of the stack.
+ Using 
+\family typewriter 
+call
+\family default 
+ with a literal quotation is useless; writing out the elements of the quotation
+ has the same effect.
+ However, the 
+\family typewriter 
+call
+\family default 
+ combinator is a building block of more powerful combinators, since quotations
+ can be passed around arbitrarily and even modified before being called.
+\layout Standard
+
+
+\family typewriter 
+ifte
+\family default 
+ 
+\family typewriter 
+( cond true false -- )
+\family default 
+ executes either the 
+\family typewriter 
+true
+\family default 
+ or 
+\family typewriter 
+false
+\family default 
+ quotations, depending on the boolean value of 
+\family typewriter 
+cond
+\family default 
+.
+ In Factor, there is no real boolean data type -- instead, a special object
+ 
+\family typewriter 
+f
+\family default 
+ is the only object with a 
+\begin_inset Quotes eld
+\end_inset 
+
+false
+\begin_inset Quotes erd
+\end_inset 
+
+ boolean value.
+ Every other object is a boolean 
+\begin_inset Quotes eld
+\end_inset 
+
+true
+\begin_inset Quotes erd
+\end_inset 
+
+.
+ The special object 
+\family typewriter 
+t
+\family default 
+ is the 
+\begin_inset Quotes eld
+\end_inset 
+
+canonical
+\begin_inset Quotes erd
+\end_inset 
+
+ truth value.
+\layout Standard
+
+Here is an example of 
+\family typewriter 
+ifte
+\family default 
+ usage:
+\layout LyX-Code
+
+1 2 < [ 
+\begin_inset Quotes eld
+\end_inset 
+
+1 is less than 2.
+\begin_inset Quotes erd
+\end_inset 
+
+ print ] [ 
+\begin_inset Quotes eld
+\end_inset 
+
+bug!
+\begin_inset Quotes erd
+\end_inset 
+
+ print ] ifte
+\layout Standard
+
+Compare the order of operands here, and the order of arguments in the stack
+ effect of 
+\family typewriter 
+ifte
+\family default 
+.
+\layout Standard
+
+That the stack effects of the two 
+\family typewriter 
+ifte
+\family default 
+ branches should be the same.
+ If they differ, the word becomes harder to document and debug.
+\layout Standard
+
+
+\family typewriter 
+times ( num quot -- )
+\family default 
+ executes a quotation a number of times.
+ It is good style to have the quotation always consume as many values from
+ the stack as it produces.
+ This ensures the stack effect of the entire 
+\family typewriter 
+times
+\family default 
+ expression stays constant regardless of the number of iterations.
+\layout Standard
+
+More combinators will be introduced later.
+\layout Subsection
+
+Vocabularies
+\layout Standard
+
+The dictionary of words is not a flat list -- rather, it is separated into
+ a number of 
+\emph on 
+vocabularies
+\emph default 
+.
+ Each vocabulary is a named list of words that have something in common
+ -- for example, the 
+\begin_inset Quotes eld
+\end_inset 
+
+lists
+\begin_inset Quotes erd
+\end_inset 
+
+ vocabulary contains words for working with linked lists.
+\layout Standard
+
+When a word is read by the parser, the 
+\emph on 
+vocabulary search path
+\emph default 
+ determines which vocabularies to search.
+ In the interactive interpreter, the default search path contains a large
+ number of vocabularies.
+ Contrast this to the situation when a file is being parsed -- the search
+ path has a minimal set of vocabularies containing basic parsing words.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+The rationale here is that the interactive interpreter should have a large
+ number of words available by default, for convinience, whereas source files
+ should specify their external dependencies explicitly.
+\end_inset 
+
+
+\layout Standard
+
+New vocabularies are added to the search path using the 
+\family typewriter 
+USE:
+\family default 
+ parsing word.
+ For example:
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+/home/slava/.factor-rc
+\begin_inset Quotes erd
+\end_inset 
+
+ exists? .
+\layout LyX-Code
+
+
+\emph on 
+ERROR: <interactive>:1: Undefined: exists?
+\layout LyX-Code
+
+USE: streams
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+/home/slava/.factor-rc
+\begin_inset Quotes erd
+\end_inset 
+
+ exists? .
+\layout LyX-Code
+
+
+\emph on 
+t
+\layout Standard
+
+How do you know which vocabulary contains a word? Vocabularies can either
+ be listed, or an 
+\begin_inset Quotes eld
+\end_inset 
+
+apropos
+\begin_inset Quotes erd
+\end_inset 
+
+ search can be performed:
+\layout LyX-Code
+
+"init" words.
+\layout LyX-Code
+
+
+\emph on 
+[ ?run-file boot cli-arg cli-param init-environment
+\layout LyX-Code
+
+
+\emph on 
+init-gc init-interpreter init-scratchpad init-search-path
+\layout LyX-Code
+
+
+\emph on 
+init-stdio init-toplevel parse-command-line parse-switches
+\layout LyX-Code
+
+
+\emph on 
+run-files run-user-init stdin stdout ] 
+\layout LyX-Code
+
+\layout LyX-Code
+
+"map" apropos.
+\layout LyX-Code
+
+
+\emph on 
+IN: lists
+\layout LyX-Code
+
+
+\emph on 
+map
+\layout LyX-Code
+
+
+\emph on 
+IN: strings
+\layout LyX-Code
+
+
+\emph on 
+str-map
+\layout LyX-Code
+
+
+\emph on 
+IN: vectors
+\layout LyX-Code
+
+
+\emph on 
+(vector-map)
+\layout LyX-Code
+
+
+\emph on 
+(vector-map-step)
+\layout LyX-Code
+
+
+\emph on 
+vector-map 
+\layout Standard
+
+New words are defined in the 
+\emph on 
+input vocabulary
+\emph default 
+.
+ The input vocabulary can be changed at the interactive prompt, or in a
+ source file, using the 
+\family typewriter 
+IN:
+\family default 
+ parsing word.
+ For example:
+\layout LyX-Code
+
+IN: music-database
+\layout LyX-Code
+
+: random-playlist ...
+ ;
+\layout Standard
+
+It is a convention (although it is not enforced by the parser) that the
+ 
+\family typewriter 
+IN:
+\family default 
+ directive is the first statement in a source file, and all 
+\family typewriter 
+USE:
+\family default 
+ follow, before any other definitions.
+\layout Section
+
+PRACTICAL: Numbers game
+\layout Standard
+
+In this section, basic input/output and flow control is introduced.
+ We construct a program that repeatedly prompts the user to guess a number
+ -- they are informed if their guess is correct, too low, or too high.
+ The game ends on a correct guess.
+\layout LyX-Code
+
+numbers-game
+\layout LyX-Code
+
+
+\emph on 
+I'm thinking of a number between 0 and 100.
+\layout LyX-Code
+
+
+\emph on 
+Enter your guess:
+\emph default 
+ 25
+\layout LyX-Code
+
+
+\emph on 
+Too low
+\layout LyX-Code
+
+
+\emph on 
+Enter your guess:
+\emph default 
+ 38
+\layout LyX-Code
+
+
+\emph on 
+Too high
+\layout LyX-Code
+
+
+\emph on 
+Enter your guess:
+\emph default 
+ 31
+\layout LyX-Code
+
+
+\emph on 
+Correct - you win!
+\layout Subsection
+
+Development methodology
+\layout Standard
+
+A typical Factor development session involves a text editor
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+Try jEdit, which has Factor syntax highlighting out of the box.
+\end_inset 
+
+ and Factor interpreter running side by side.
+ Instead of the edit/compile/run cycle, the development process becomes
+ an 
+\begin_inset Quotes eld
+\end_inset 
+
+edit cycle
+\begin_inset Quotes erd
+\end_inset 
+
+ -- you make some changes to the source file and reload it in the interpreter
+ using a command like this:
+\layout LyX-Code
+
+  
+\begin_inset Quotes eld
+\end_inset 
+
+numbers-game.factor
+\begin_inset Quotes erd
+\end_inset 
+
+ run-file
+\layout Standard
+
+Then the changes can be tested, either by hand, or using a test harness.
+ There is no need to compile anything, or to lose interpreter state by restartin
+g.
+ Additionally, words with 
+\begin_inset Quotes eld
+\end_inset 
+
+throw-away
+\begin_inset Quotes erd
+\end_inset 
+
+ definitions that you do not intend to keep can also be entered directly
+ at this interpreter prompt.
+\layout Standard
+
+Each word should do one useful task.
+ New words can be defined in terms of existing, already-tested words.
+ You design a set of reusable words that model the problem domain.
+ Then, the problem is solved in terms of a 
+\emph on 
+domain-specific vocabulary
+\emph default 
+.
+ This is called
+\emph on 
+ bottom-up design.
+\layout Subsection
+
+Getting started
+\layout Standard
+
+Start a text editor and create a file named 
+\family typewriter 
+numbers-game.factor
+\family default 
+.
+\layout Standard
+
+At the top of the file, write a comment.
+ Comments are a feature that can be found in almost any programming language;
+ in Factor, they are implemented as parsing words.
+ An example of commenting follows:
+\layout LyX-Code
+
+! The word ! discards input until the end of the line
+\layout LyX-Code
+
+( The word ( discards input until the next )
+\layout Standard
+
+It is always a good idea to comment your code.
+ Try to write simple code that does not need detailed comments to describe;
+ similarly, avoid redundant comments.
+ These two principles are hard to quantify in a concrete way, and will become
+ more clear as your skills with Factor increase.
+\layout Standard
+
+We will be defining new words in the numbers-game vocabulary; add an 
+\family typewriter 
+IN:
+\family default 
+ statement at the top of the source file:
+\layout LyX-Code
+
+IN: numbers-game
+\layout Standard
+
+Also in order to be able to test the words, issue a 
+\family typewriter 
+USE:
+\family default 
+ statement in the interactive interpreter:
+\layout LyX-Code
+
+USE: numbers-game
+\layout Standard
+
+This section will develop the numbers game in an incremental fashion.
+ After each addition, issue a command like the following to load the source
+ file into the Factor interpreter:
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+numbers-game.factor
+\begin_inset Quotes erd
+\end_inset 
+
+ run-file
+\layout Subsection
+
+Reading a number from the keyboard
+\layout Standard
+
+A fundamental operation required for the numbers game is to be able to read
+ a number from the keyboard.
+ The 
+\family typewriter 
+read
+\family default 
+ word 
+\family typewriter 
+( -- str )
+\family default 
+ reads a line of input and pushes it on the stack as a string.
+ The 
+\family typewriter 
+parse-number
+\family default 
+ word 
+\family typewriter 
+( str -- n )
+\family default 
+ takes a string from the stack, and parses it, pushing an integer.
+ These two words can be combined into a single colon definition:
+\layout LyX-Code
+
+: read-number ( -- n ) read parse-number ;
+\layout Standard
+
+You should add this definition to the source file, and try loading the file
+ into the interpreter.
+ As you will soon see, this raises an error! The problem is that the two
+ words 
+\family typewriter 
+read
+\family default 
+ and 
+\family typewriter 
+parse-number
+\family default 
+ are not part of the default, minimal, vocabulary search path used when
+ reading files.
+ The solution is to use 
+\family typewriter 
+apropos.
+
+\family default 
+ to find out which vocabularies contain those words, and add the appropriate
+ USE: statements to the source file:
+\layout LyX-Code
+
+USE: parser
+\layout LyX-Code
+
+USE: stdio
+\layout Standard
+
+After adding the above two statements, the file should now parse, and testing
+ should confirm that the read-number word works correctly.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+There is the possibility of an invalid number being entered at the keyboard.
+ In this case, 
+\family typewriter 
+print-number
+\family default 
+ returns 
+\family typewriter 
+f
+\family default 
+, the boolean false value.
+ For the sake of simplicity, we ignore this case in the numbers game example.
+ However, proper error handling is an essential part of any large program
+ and is covered later.
+\end_inset 
+
+
+\layout Subsection
+
+Printing some messages
+\layout Standard
+
+Now we need to make some words for printing various messages.
+ They are given here without further ado:
+\layout LyX-Code
+
+: guess-banner
+\layout LyX-Code
+
+    
+\begin_inset Quotes eld
+\end_inset 
+
+I'm thinking of a number between 0 and 100.
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\layout LyX-Code
+
+: guess-prompt 
+\begin_inset Quotes eld
+\end_inset 
+
+Enter your guess: 
+\begin_inset Quotes erd
+\end_inset 
+
+ write ;
+\layout LyX-Code
+
+: too-high 
+\begin_inset Quotes eld
+\end_inset 
+
+Too high
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\layout LyX-Code
+
+: too-low 
+\begin_inset Quotes eld
+\end_inset 
+
+Too low
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\layout LyX-Code
+
+: correct 
+\begin_inset Quotes eld
+\end_inset 
+
+Correct - you win!
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\layout Standard
+
+Note that in the above, stack effect comments are omitted, since they are
+ obvious from context.
+ You should ensure the words work correctly after loading the source file
+ into the interpreter.
+\layout Subsection
+
+Taking action based on a guess
+\layout Standard
+
+The next logical step is to write a word 
+\family typewriter 
+judge-guess
+\family default 
+ that takes the user's guess along with the actual number to be guessed,
+ and prints one of the messages 
+\family typewriter 
+too-high
+\family default 
+, 
+\family typewriter 
+too-low
+\family default 
+, or 
+\family typewriter 
+correct
+\family default 
+.
+ This word will also push a boolean flag, indicating if the game should
+ continue or not -- in the case of a correct guess, the game does not continue.
+\layout Standard
+
+This description of judge-guess is a mouthful -- and it suggests that it
+ may be best to split it into two words.
+ So the first word we write handles the more specific case of an 
+\emph on 
+inexact
+\emph default 
+ guess -- so it prints either 
+\family typewriter 
+too-low
+\family default 
+ or 
+\family typewriter 
+too-high
+\family default 
+.
+\layout LyX-Code
+
+: inexact-guess ( guess actual -- )
+\layout LyX-Code
+
+     > [ too-high ] [ too-low ] ifte ;
+\layout Standard
+
+Note that the word gives incorrect output if the two parameters are equal.
+ However, it will never be called this way.
+\layout Standard
+
+With this out of the way, the implementation of judge-guess is an easy task
+ to tackle.
+ Using the words 
+\family typewriter 
+inexact-guess
+\family default 
+, 
+\family typewriter 
+=
+\family default 
+, and 
+\family typewriter 
+2dup
+\family default 
+, we can write:
+\layout LyX-Code
+
+: judge-guess ( actual guess -- ? )
+\layout LyX-Code
+
+    2dup = [
+\layout LyX-Code
+
+        correct f
+\layout LyX-Code
+
+    ] [
+\layout LyX-Code
+
+        inexact-guess t
+\layout LyX-Code
+
+    ] ifte ;
+\layout Standard
+
+Note the use of 
+\family typewriter 
+2dup ( x y -- x y x y )
+\family default 
+.
+ Since 
+\family typewriter 
+=
+\family default 
+ consumes both its parameters, we must make copies of them to pass to 
+\family typewriter 
+correct
+\family default 
+ and 
+\family typewriter 
+inexact-guess
+\family default 
+.
+ Try the following at the interpreter to see what's going on:
+\layout LyX-Code
+
+clear 1 2 2dup = .s
+\layout LyX-Code
+
+
+\emph on 
+{ 1 2 f }
+\layout LyX-Code
+
+clear 4 4 2dup = .s
+\layout LyX-Code
+
+
+\emph on 
+{ 4 4 t }
+\layout Standard
+
+Test 
+\family typewriter 
+judge-guess
+\family default 
+ with a few inputs:
+\layout LyX-Code
+
+1 10 judge-guess .
+\layout LyX-Code
+
+
+\emph on 
+Too low
+\layout LyX-Code
+
+
+\emph on 
+t
+\layout LyX-Code
+
+89 43 judge-guess .
+\layout LyX-Code
+
+
+\emph on 
+Too high
+\layout LyX-Code
+
+
+\emph on 
+t
+\layout LyX-Code
+
+64 64 judge-guess .
+\layout LyX-Code
+
+
+\emph on 
+Correct
+\layout LyX-Code
+
+
+\emph on 
+f
+\layout Subsection
+
+Generating random numbers
+\layout Standard
+
+The 
+\family typewriter 
+random-int 
+\family default 
+word 
+\family typewriter 
+( min max -- n )
+\family default 
+ pushes a random number in a specified range.
+ The range is inclusive, so both the minimum and maximum indices are candidate
+ random numbers.
+ Use 
+\family typewriter 
+apropos.
+
+\family default 
+ to determine that this word is in the 
+\family typewriter 
+random
+\family default 
+ vocabulary.
+ For the purposes of this game, random numbers will be in the range of 0
+ to 100, so we can define a word that generates a random number in the range
+ of 0 to 100:
+\layout LyX-Code
+
+: number-to-guess ( -- n ) 0 100 random-int ;
+\layout Standard
+
+Add the word definition to the source file, along with the appropriate 
+\family typewriter 
+USE:
+\family default 
+ statement.
+ Load the source file in the interpreter, and confirm that the word functions
+ correctly, and that its stack effect comment is accurate.
+\layout Subsection
+
+The game loop
+\layout Standard
+
+The game loop consists of repeated calls to 
+\family typewriter 
+guess-prompt
+\family default 
+, 
+\family typewriter 
+read-number
+\family default 
+ and 
+\family typewriter 
+judge-guess
+\family default 
+.
+ If 
+\family typewriter 
+judge-guess
+\family default 
+ pushes 
+\family typewriter 
+f
+\family default 
+, the loop stops, otherwise it continues.
+ This is realized with a recursive implementation:
+\layout LyX-Code
+
+: numbers-game-loop ( actual -- )
+\layout LyX-Code
+
+    dup guess-prompt read-number judge-guess [
+\layout LyX-Code
+
+        numbers-game-loop
+\layout LyX-Code
+
+    ] [
+\layout LyX-Code
+
+        drop
+\layout LyX-Code
+
+    ] ifte ;
+\layout Standard
+
+In Factor, tail-recursive words consume a bounded amount of call stack space.
+ This means you are free to pick recursion or iteration based on their own
+ merits when solving a problem.
+ In many other languages, the usefulness of recursion is severely limited
+ by the lack of tail-recursive call optimization.
+\layout Subsection
+
+Finishing off
+\layout Standard
+
+The last task is to combine everything into the main 
+\family typewriter 
+numbers-game
+\family default 
+ word.
+ This is easier than it seems:
+\layout LyX-Code
+
+: numbers-game number-to-guess numbers-game-loop ;
+\layout Standard
+
+Try it out! Simply invoke the numbers-game word in the interpreter.
+ It should work flawlessly, assuming you tested each component of this design
+ incrementally!
+\layout Subsection
+
+The complete program
+\layout LyX-Code
+
+! Numbers game example
+\newline 
+
+\layout LyX-Code
+
+IN: numbers-game
+\layout LyX-Code
+
+USE: parser
+\layout LyX-Code
+
+USE: stdio
+\newline 
+
+\newline 
+: read-number ( -- n ) read parse-number ;
+\newline 
+
+\newline 
+: guess-banner
+\layout LyX-Code
+
+    
+\begin_inset Quotes eld
+\end_inset 
+
+I'm thinking of a number between 0 and 100.
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\layout LyX-Code
+
+: guess-prompt 
+\begin_inset Quotes eld
+\end_inset 
+
+Enter your guess: 
+\begin_inset Quotes erd
+\end_inset 
+
+ write ;
+\layout LyX-Code
+
+: too-high 
+\begin_inset Quotes eld
+\end_inset 
+
+Too high
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\layout LyX-Code
+
+: too-low 
+\begin_inset Quotes eld
+\end_inset 
+
+Too low
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\layout LyX-Code
+
+: correct 
+\begin_inset Quotes eld
+\end_inset 
+
+Correct - you win!
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\newline 
+
+\newline 
+: inexact-guess ( guess actual -- )
+\layout LyX-Code
+
+     > [ too-high ] [ too-low ] ifte ;
+\newline 
+
+\newline 
+: judge-guess ( actual guess -- ? )
+\layout LyX-Code
+
+    2dup = [
+\layout LyX-Code
+
+        correct f
+\layout LyX-Code
+
+    ] [
+\layout LyX-Code
+
+        inexact-guess t
+\layout LyX-Code
+
+    ] ifte ;
+\newline 
+
+\newline 
+: number-to-guess ( -- n ) 0 100 random-int ;
+\newline 
+
+\newline 
+: numbers-game-loop ( actual -- )
+\layout LyX-Code
+
+    dup guess-prompt read-number judge-guess [
+\layout LyX-Code
+
+        numbers-game-loop
+\layout LyX-Code
+
+    ] [
+\layout LyX-Code
+
+        drop
+\layout LyX-Code
+
+    ] ifte ;
+\newline 
+
+\newline 
+: numbers-game number-to-guess numbers-game-loop ;
+\layout LyX-Code
+
+\layout Section
+
+Lists
+\layout Standard
+
+A list is composed of a set of pairs; each pair holds a list element, and
+ a reference to the next pair.
+ Lists have the following literal syntax:
+\layout LyX-Code
+
+[ 
+\begin_inset Quotes eld
+\end_inset 
+
+CEO
+\begin_inset Quotes erd
+\end_inset 
+
+ 5 
+\begin_inset Quotes eld
+\end_inset 
+
+CFO
+\begin_inset Quotes erd
+\end_inset 
+
+ -4 f ]
+\layout Standard
+
+Before we continue, it is important to understand the role of data types
+ in Factor.
+ Lets make a distinction between two categories of data types:
+\layout Itemize
+
+Representational type -- this refers to the form of the data in the interpreter.
+ Representational types include integers, strings, and vectors.
+ Representational types are checked at run time -- attempting to multiply
+ two strings, for example, will yield an error.
+\layout Itemize
+
+Intentional type -- this refers to the meaning of the data within the problem
+ domain.
+ This could be a length measured in inches, or a string naming a file, or
+ a list of objects in a room in a game.
+ It is up to the programmer to check intentional types -- Factor won't prevent
+ you from adding two integers representing a distance and a time, even though
+ the result is meaningless.
+\layout Subsection
+
+Cons cells
+\layout Standard
+
+It may surprise you that in Factor, 
+\emph on 
+lists are intentional types
+\emph default 
+.
+ This means that they are not an inherent feature of the interpreter; rather,
+ they are built from a simpler data type, the 
+\emph on 
+cons cell
+\emph default 
+.
+\layout Standard
+
+A cons cell is an object that holds a reference to two other objects.
+ The order of the two objects matters -- the first is called the 
+\emph on 
+car
+\emph default 
+, the second is called the 
+\emph on 
+cdr
+\emph default 
+.
+\layout Standard
+
+All words relating to cons cells and lists are found in the 
+\family typewriter 
+lists
+\family default 
+ vocabulary.
+ The words 
+\family typewriter 
+cons
+\family default 
+, 
+\family typewriter 
+car
+\family default 
+ and 
+\family typewriter 
+cdr
+\family default 
+
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+These infamous names originate from the Lisp language.
+ Originally, 
+\begin_inset Quotes eld
+\end_inset 
+
+Lisp
+\begin_inset Quotes erd
+\end_inset 
+
+ stood for 
+\begin_inset Quotes eld
+\end_inset 
+
+List Processing
+\begin_inset Quotes erd
+\end_inset 
+
+.
+\end_inset 
+
+ construct and deconstruct cons cells:
+\layout LyX-Code
+
+1 2 cons .
+\layout LyX-Code
+
+
+\emph on 
+[ 1 | 2 ]
+\layout LyX-Code
+
+3 4 car .
+\layout LyX-Code
+
+
+\emph on 
+3
+\layout LyX-Code
+
+5 6 cdr .
+\layout LyX-Code
+
+
+\emph on 
+6
+\layout Standard
+
+The output of the first expression suggests a literal syntax for cons cells:
+\layout LyX-Code
+
+[ 10 | 20 ] cdr .
+\layout LyX-Code
+
+
+\emph on 
+20
+\layout LyX-Code
+
+[ 
+\begin_inset Quotes eld
+\end_inset 
+
+first
+\begin_inset Quotes erd
+\end_inset 
+
+ | [ 
+\begin_inset Quotes eld
+\end_inset 
+
+second
+\begin_inset Quotes erd
+\end_inset 
+
+ | f ] ] car .
+\layout LyX-Code
+
+
+\emph on 
+
+\begin_inset Quotes eld
+\end_inset 
+
+first
+\begin_inset Quotes erd
+\end_inset 
+
+
+\layout LyX-Code
+
+[ 
+\begin_inset Quotes eld
+\end_inset 
+
+first
+\begin_inset Quotes erd
+\end_inset 
+
+ | [ 
+\begin_inset Quotes eld
+\end_inset 
+
+second
+\begin_inset Quotes erd
+\end_inset 
+
+ | f ] ] cdr car .
+\layout LyX-Code
+
+
+\emph on 
+
+\begin_inset Quotes eld
+\end_inset 
+
+second
+\begin_inset Quotes erd
+\end_inset 
+
+
+\layout Standard
+
+The last two examples make it clear how nested cons cells represent a list.
+ Since this 
+\begin_inset Quotes eld
+\end_inset 
+
+nested cons cell
+\begin_inset Quotes erd
+\end_inset 
+
+ syntax is extremely cumbersome, the parser provides an easier way:
+\layout LyX-Code
+
+[ 1 2 3 4 ] cdr cdr car .
+\layout LyX-Code
+
+
+\emph on 
+3
+\layout Standard
+
+A 
+\emph on 
+generalized list
+\emph default 
+ is a set of cons cells linked by their cdr.
+ A 
+\emph on 
+proper list
+\emph default 
+, or just list, is a generalized list with a cdr equal to f, the list is
+ a proper list.
+ Also, the object 
+\family typewriter 
+f
+\family default 
+ is a proper list, and in fact it is equivalent to the empty list 
+\family typewriter 
+[ ]
+\family default 
+.
+ An
+\emph on 
+ improper list
+\emph default 
+ is a generalized list that is not a proper list.
+\layout Standard
+
+The 
+\family typewriter 
+list?
+\family default 
+ word tests if the object at the top of the stack is a proper list:
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+hello
+\begin_inset Quotes erd
+\end_inset 
+
+ list? .
+\layout LyX-Code
+
+
+\emph on 
+f
+\layout LyX-Code
+
+[ 
+\begin_inset Quotes eld
+\end_inset 
+
+first
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+second
+\begin_inset Quotes erd
+\end_inset 
+
+ | 
+\begin_inset Quotes eld
+\end_inset 
+
+third
+\begin_inset Quotes erd
+\end_inset 
+
+ ] list? .
+\layout LyX-Code
+
+
+\emph on 
+f
+\layout LyX-Code
+
+[ 
+\begin_inset Quotes eld
+\end_inset 
+
+first
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+second
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+third
+\begin_inset Quotes erd
+\end_inset 
+
+ ] list? .
+\layout LyX-Code
+
+
+\emph on 
+t
+\layout Subsection
+
+Working with lists
+\layout Standard
+
+Unless otherwise documented, list manipulation words expect proper lists
+ as arguments.
+ Given an improper list, they will either raise an error, or disregard the
+ hanging cdr at the end of the list.
+\layout Standard
+
+Also unless otherwise documented, list manipulation words return newly-created
+ lists only.
+ The original parameters are not modified.
+ This may seem inefficient, however the absence of side effects makes code
+ much easier to test and debug.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+Side effect-free code is the fundamental idea underlying functional programming
+ languages.
+ While Factor allows side effects and is not a functional programming language,
+ for a lot of problems, coding in a functional style gives the most maintanable
+ and readable results.
+\end_inset 
+
+ Where performance is important, a set of 
+\begin_inset Quotes eld
+\end_inset 
+
+destructive
+\begin_inset Quotes erd
+\end_inset 
+
+ words is provided.
+ They are documented in the next section.
+\layout Standard
+
+
+\family typewriter 
+nth ( index list -- obj )
+\family default 
+ Look up an element specified by a zero-based index, by successively iterating
+ down the cdr of the list:
+\layout LyX-Code
+
+1 [ 
+\begin_inset Quotes eld
+\end_inset 
+
+Hamster
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+Bagpipe
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+Beam
+\begin_inset Quotes erd
+\end_inset 
+
+ ] nth .
+\layout LyX-Code
+
+
+\emph on 
+
+\begin_inset Quotes eld
+\end_inset 
+
+Bagpipe
+\begin_inset Quotes erd
+\end_inset 
+
+
+\layout Standard
+
+This word takes linear time proportional to the list index.
+ If you need constant time lookups, use a vector instead.
+\layout Standard
+
+
+\family typewriter 
+length ( list -- n )
+\family default 
+ Iterate down the cdr of the list until it reaches 
+\family typewriter 
+f
+\family default 
+, counting the number of elements in the list:
+\layout LyX-Code
+
+[ [ 1 2 ] [ 3 4 ] 5 ] length .
+\layout LyX-Code
+
+
+\emph on 
+3
+\layout LyX-Code
+
+[ [ [ 
+\begin_inset Quotes eld
+\end_inset 
+
+Hey
+\begin_inset Quotes erd
+\end_inset 
+
+ ] 5 ] length .
+\layout LyX-Code
+
+
+\emph on 
+2
+\layout Standard
+
+
+\family typewriter 
+unit ( obj -- list )
+\family default 
+ Make a list of one element:
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+Unit 18
+\begin_inset Quotes erd
+\end_inset 
+
+ unit .
+\layout LyX-Code
+
+
+\emph on 
+[ 
+\begin_inset Quotes eld
+\end_inset 
+
+Unit 18
+\begin_inset Quotes erd
+\end_inset 
+
+ ]
+\layout Standard
+
+
+\family typewriter 
+append ( list list -- list )
+\family default 
+ Append the two lists at the top of the stack:
+\layout LyX-Code
+
+[ 1 2 3 ] [ 4 5 6 ] append .
+\layout LyX-Code
+
+
+\emph on 
+[ 1 2 3 4 5 6 ]
+\layout LyX-Code
+
+[ 1 2 3 ] dup [ 4 5 6 ] append .s
+\layout LyX-Code
+
+
+\emph on 
+{ [ 1 2 3 ] [ 1 2 3 4 5 6 ] }
+\layout Standard
+
+The first list is copied, and the cdr of its last cons cell is set to the
+ second list.
+ The second example above shows that the original parameter was not modified.
+ Interestingly, if the second parameter is not a proper list, 
+\family typewriter 
+append
+\family default 
+ returns an improper list:
+\layout LyX-Code
+
+[ 1 2 3 ] 4 append .
+\layout LyX-Code
+
+
+\emph on 
+[ 1 2 3 | 4 ]
+\layout Standard
+
+
+\family typewriter 
+add ( list obj -- list )
+\family default 
+ Create a new list consisting of the original list, and a new element added
+ at the end:
+\layout LyX-Code
+
+[ 1 2 3 ] 4 add .
+\layout LyX-Code
+
+
+\emph on 
+[ 1 2 3 4 ]
+\layout LyX-Code
+
+1 [ 2 3 4 ] cons .
+\layout LyX-Code
+
+
+\emph on 
+[ 1 2 3 4 ]
+\layout Standard
+
+While 
+\family typewriter 
+cons
+\family default 
+ and 
+\family typewriter 
+add
+\family default 
+ appear to have similar effects, they are quite different -- 
+\family typewriter 
+cons
+\family default 
+ is a very cheap operation, while 
+\family typewriter 
+add
+\family default 
+ has to copy the entire list first! If you need adds to the end to take
+ a constant time, use a vector.
+\layout Standard
+
+
+\family typewriter 
+reverse ( list -- list )
+\family default 
+ Push a new list which has the same elements as the original one, but in
+ reverse order:
+\layout LyX-Code
+
+[ 4 3 2 1 ] reverse .
+\layout LyX-Code
+
+
+\emph on 
+[ 1 2 3 4 ]
+\layout Standard
+
+
+\family typewriter 
+contains ( obj list -- list )
+\family roman 
+ 
+\family default 
+Look
+\family roman 
+ for an occurrence of an object in a list.
+ The remainder of the list starting from the first occurrence
+\family default 
+ is returned.
+ If the object does not occur in the list, f is returned:
+\layout LyX-Code
+
+: lived-in? ( country -- ? )
+\layout LyX-Code
+
+    [ 
+\begin_inset Quotes eld
+\end_inset 
+
+Canada
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+New Zealand
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+Australia
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+Russia
+\begin_inset Quotes erd
+\end_inset 
+
+ ] contains ;
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+Australia
+\begin_inset Quotes erd
+\end_inset 
+
+ lived-in? .
+\layout LyX-Code
+
+
+\emph on 
+[ 
+\begin_inset Quotes eld
+\end_inset 
+
+Australia
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+Russia
+\begin_inset Quotes erd
+\end_inset 
+
+ ]
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+Pakistan
+\begin_inset Quotes erd
+\end_inset 
+
+ lived-in? .
+\layout LyX-Code
+
+
+\emph on 
+f
+\layout Standard
+
+For now, assume 
+\begin_inset Quotes eld
+\end_inset 
+
+occurs
+\begin_inset Quotes erd
+\end_inset 
+
+ means 
+\begin_inset Quotes eld
+\end_inset 
+
+contains an object that looks like
+\begin_inset Quotes erd
+\end_inset 
+
+.
+ The issue of object equality is covered in the next chapter.
+\layout Standard
+
+
+\family typewriter 
+remove ( obj list -- list )
+\family default 
+ Push a new list, with all occurrences of the object removed.
+ All other elements are in the same order:
+\layout LyX-Code
+
+: australia- 
+\begin_inset Quotes eld
+\end_inset 
+
+Australia
+\begin_inset Quotes erd
+\end_inset 
+
+ swap remove ;
+\layout LyX-Code
+
+[ "Canada" "New Zealand" "Australia" "Russia" ] australia- .
+\layout LyX-Code
+
+
+\emph on 
+[ "Canada" "New Zealand" "Russia" ]
+\layout Standard
+
+
+\family typewriter 
+remove-nth ( index list -- list )
+\family default 
+ Push a new list, with an index removed:
+\layout LyX-Code
+
+: australia- 
+\begin_inset Quotes eld
+\end_inset 
+
+Australia
+\begin_inset Quotes erd
+\end_inset 
+
+ swap remove ;
+\layout LyX-Code
+
+[ "Canada" "New Zealand" "Australia" "Russia" ] australia- .
+\layout LyX-Code
+
+
+\emph on 
+[ "Canada" "New Zealand" "Russia" ]
+\layout Standard
+
+XXX: unique, set-nth -- talk about lists as stacks
+\layout Subsection
+
+Association lists
+\layout Standard
+
+An 
+\emph on 
+association list
+\emph default 
+ is one where every element is a cons.
+ The car of each cons is a name, the cdr is a value.
+ The literal notation is suggestive:
+\layout LyX-Code
+
+[
+\layout LyX-Code
+
+    [ 
+\begin_inset Quotes eld
+\end_inset 
+
+Jill
+\begin_inset Quotes erd
+\end_inset 
+
+ | 
+\begin_inset Quotes eld
+\end_inset 
+
+CEO
+\begin_inset Quotes erd
+\end_inset 
+
+ ]
+\layout LyX-Code
+
+    [ 
+\begin_inset Quotes eld
+\end_inset 
+
+Jeff
+\begin_inset Quotes erd
+\end_inset 
+
+ | 
+\begin_inset Quotes eld
+\end_inset 
+
+manager
+\begin_inset Quotes erd
+\end_inset 
+
+ ]
+\layout LyX-Code
+
+    [ 
+\begin_inset Quotes eld
+\end_inset 
+
+James  | 
+\begin_inset Quotes eld
+\end_inset 
+
+lowly web designer
+\begin_inset Quotes erd
+\end_inset 
+
+ ]
+\layout LyX-Code
+
+]
+\layout Standard
+
+
+\family typewriter 
+assoc? ( obj -- ? )
+\family default 
+ returns 
+\family typewriter 
+t
+\family default 
+ if the object is a list whose every element is a cons; otherwise it returns
+ 
+\family typewriter 
+f
+\family default 
+.
+\layout Standard
+
+
+\family typewriter 
+assoc ( name alist -- value )
+\family default 
+ looks for a pair with this name in the list, and pushes the cdr of the
+ pair.
+ Pushes f if no name with this pair is present.
+ Note that assoc cannot differentiate between a name that is not present
+ at all, or a name with a value of 
+\family typewriter 
+f
+\family default 
+.
+\layout Standard
+
+
+\family typewriter 
+assoc* ( name alist -- [ name | value ] )
+\family default 
+ looks for a pair with this name, and pushes the pair itself.
+ Unlike 
+\family typewriter 
+assoc
+\family default 
+, 
+\family typewriter 
+assoc*
+\family default 
+ returns different values in the cases of a value set to 
+\family typewriter 
+f
+\family default 
+, or an undefined value.
+\layout Standard
+
+
+\family typewriter 
+set-assoc ( value name alist -- alist )
+\family default 
+ removes any existing occurrence of a name from the list, and adds a new
+ pair.
+ This creates a new list, the original is unaffected.
+\layout Standard
+
+
+\family typewriter 
+acons ( value name alist -- alist )
+\family default 
+ is slightly faster than 
+\family typewriter 
+set-assoc
+\family default 
+ since it simply conses a new pair onto the list.
+ However, if used repeatedly, the list will grow to contain a lot of 
+\begin_inset Quotes eld
+\end_inset 
+
+shadowed
+\begin_inset Quotes erd
+\end_inset 
+
+ pairs.
+\layout Standard
+
+Searching an association list incurs a linear time cost, so they should
+ only be used for small mappings -- a typical use is a mapping of half a
+ dozen entries or so, specified literally in source.
+ Hashtables can achieve better performance with larger mappings.
+\layout Subsection
+
+List combinators
+\layout Standard
+
+In a traditional language such as C, every iteration or collection must
+ be written out as a loop, with setting up and updating of idices, etc.
+ Factor on the other hand relies on combinators and quotations to avoid
+ duplicating these loop 
+\begin_inset Quotes eld
+\end_inset 
+
+design patterns
+\begin_inset Quotes erd
+\end_inset 
+
+ throughout the code.
+\layout Standard
+
+The simplest case is iterating through each element of a list, and printing
+ it or otherwise consuming it from the stack.
+\layout Standard
+
+
+\family typewriter 
+each ( list quot -- )
+\family default 
+ pushes each element of the list in turn, and executes the quotation.
+ The list and quotation are not on the stack when the quotation is executed.
+ This allows a powerful idiom where the quotation makes a copy of a value
+ on the stack, and consumes it along with the list element.
+ In fact, this idiom works with all well-designed combinators.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+Later, you will learn how to apply it when designing your own combinators.
+\end_inset 
+
+
+\layout Standard
+
+The previously-mentioned 
+\family typewriter 
+reverse
+\family default 
+ word is implemented using 
+\family typewriter 
+each
+\family default 
+:
+\layout LyX-Code
+
+: reverse [ ] swap [ swons ] each ;
+\layout Standard
+
+To understand how it works, consider that each element of the original list
+ is consed onto the beginning of a new list, in turn.
+ So the last element of the original list ends up at the beginning of the
+ new list.
+\layout Standard
+
+
+\family typewriter 
+inject ( list quot -- list )
+\family default 
+ is similar to 
+\family typewriter 
+each
+\family default 
+, except the return values of the quotation are collected into the new list.
+ The quotation must leave one more element on the stack than was present
+ before the quotation was called, otherwise the combinator will not function
+ properly; so the quotation must have stack effect 
+\family typewriter 
+( obj -- obj )
+\family default 
+.
+\layout Standard
+
+For example, suppose we have a list where each element stores the quantity
+ of a some nutrient in 100 grams of food; we would like to find out the
+ total nutrients contained in 300 grams:
+\layout LyX-Code
+
+: multiply-each ( n list -- list )
+\layout LyX-Code
+
+    [ dupd * ] inject nip ;
+\layout LyX-Code
+
+3 [ 50 450 101 ] multiply-each .
+\layout LyX-Code
+
+
+\emph on 
+[ 180 1350 303 ]
+\layout Standard
+
+Note the use of 
+\family typewriter 
+nip
+\family default 
+ to discard the original parameter 
+\family typewriter 
+n
+\family default 
+.
+\layout Standard
+
+In case there is no appropriate combinator, recursion can be used.
+ Factor performs tail call optimization, so a word where the recursive call
+ is the last thing done will not use an arbitrary amount of stack space.
+\layout Standard
+
+
+\family typewriter 
+subset ( list quot -- list )
+\family default 
+ produces a new list containing some of the elements of the original list.
+ Which elements to collect is determined by the quotation -- the quotation
+ is called with each list element on the stack in turn, and those elements
+ for which the quotation does not return 
+\family typewriter 
+f
+\family default 
+ are added to the new list.
+ The quotation must have stack effect 
+\family typewriter 
+( obj -- ? )
+\family default 
+.
+\layout Standard
+
+For example, lets construct a list of all numbers between 0 and 99 such
+ that the sum of their digits is less than 10:
+\layout LyX-Code
+
+: sum-of-digits ( n -- n ) 10 /mod + ;
+\layout LyX-Code
+
+100 count [ sum-of-digits 10 < ] subset .
+\layout LyX-Code
+
+
+\emph on 
+[ 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 20 21
+\layout LyX-Code
+
+
+\emph on 
+22 23 24 25 26 27 30 31 32 33 34 35 36 40 41 42 43 44
+\layout LyX-Code
+
+
+\emph on 
+45 50 51 52 53 54 60 61 62 63 70 71 72 80 81 90 ] 
+\layout Standard
+
+
+\family typewriter 
+all? ( list quot -- ? )
+\family default 
+ returns 
+\family typewriter 
+t
+\family default 
+ if the quotation returns 
+\family typewriter 
+t
+\family default 
+ for all elements of the list, otherwise it returns 
+\family typewriter 
+f
+\family default 
+.
+ In other words, if 
+\family typewriter 
+all?
+\family default 
+ returns 
+\family typewriter 
+t
+\family default 
+, then 
+\family typewriter 
+subset
+\family default 
+ applied to the same list and quotation would return the entire list.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+Barring any side effects which modify the execution of the quotation.
+ It is best to avoid side effects when using list combinators.
+\end_inset 
+
+
+\layout Standard
+
+For example, the implementation of 
+\family typewriter 
+assoc?
+\family default 
+ uses 
+\family typewriter 
+all?
+\family default 
+:
+\layout LyX-Code
+
+: assoc? ( list -- ? )
+\layout LyX-Code
+
+    dup list? [ [ cons? ] all? ] [ drop f ] ifte ;
+\layout Subsection
+
+List constructors
+\layout Standard
+
+The list construction words minimize stack noise with a clever trick.
+ They store a partial list in a variable, thus reducing the number of stack
+ elements that have to be juggled.
+\layout Standard
+
+The word 
+\family typewriter 
+[, ( -- )
+\family default 
+ begins list construction.
+\layout Standard
+
+The word 
+\family typewriter 
+, ( obj -- )
+\family default 
+ appends an object to the partial list.
+\layout Standard
+
+The word 
+\family typewriter 
+,] ( -- list )
+\family default 
+ pushes the complete list.
+\layout Standard
+
+While variables haven't been described yet, keep in mind that a new scope
+ is created between 
+\family typewriter 
+[,
+\family default 
+ and 
+\family typewriter 
+,]
+\family default 
+.
+ This means that list constructions can be nested, as long as in the end,
+ the number of 
+\family typewriter 
+[,
+\family default 
+ and 
+\family typewriter 
+,]
+\family default 
+ balances out.
+ There is no requirement that 
+\family typewriter 
+[,
+\family default 
+ and 
+\family typewriter 
+,]
+\family default 
+ appear in the same word, however, debugging becomes prohibitively difficult
+ when a list construction begins in one word and ends with another.
+\layout Standard
+
+Here is an example of list construction using this technique:
+\layout LyX-Code
+
+[, 1 10 [ 2 * dup , ] times drop ,] .
+\layout LyX-Code
+
+
+\emph on 
+[ 2 4 8 16 32 64 128 256 512 1024 ]
+\layout LyX-Code
+
+\layout Subsection
+
+Destructively modifying lists
+\layout Standard
+
+All previously discussed list modification functions always returned newly-alloc
+ated lists.
+ Destructive list manipulation functions on the other hand reuse the cons
+ cells of their input lists, and hence avoid memory allocation.
+\layout Standard
+
+Only ever destructively change lists you do not intend to reuse again.
+ You should not rely on the side effects -- they are unpredictable.
+ It is wrong to think that destructive words 
+\begin_inset Quotes eld
+\end_inset 
+
+modify
+\begin_inset Quotes erd
+\end_inset 
+
+ the original list -- rather, think of them as returning a new list, just
+ like the normal versions of the words, with the added caveat that the original
+ list must not be used again.
+\layout Standard
+
+
+\family typewriter 
+nreverse ( list -- list )
+\family default 
+ reverses a list without consing.
+ In the following example, the return value reuses the cons cells of the
+ original list, and the original list has been ruined by unpredictable side
+ effects:
+\layout LyX-Code
+
+[ 1 2 3 4 ] dup nreverse .s
+\layout LyX-Code
+
+
+\emph on 
+{ [ 4 ] [ 4 3 2 1 ] }
+\layout Standard
+
+Compare the second stack element (which is what remains of the original
+ list) and the top stack element (the list returned by 
+\family typewriter 
+nreverse
+\family default 
+).
+\layout Standard
+
+The 
+\family typewriter 
+nreverse
+\family default 
+ word is the most frequently used destructive list manipulator.
+ The usual idiom is a loop where values are consed onto the beginning of
+ a list in each iteration of a loop, then the list is reversed at the end.
+ Since the original list is never used again, 
+\family typewriter 
+nreverse
+\family default 
+ can safely be used here.
+ XXX - example
+\layout Standard
+
+
+\family typewriter 
+nappend ( list list -- list )
+\family default 
+ sets the cdr of the last cons cell in the first list to the second list,
+ unless the first list is 
+\family typewriter 
+f
+\family default 
+, in which case it simply returns the second list.
+ Again, the side effects on the first list are unpredictable -- if it is
+ 
+\family typewriter 
+f
+\family default 
+, it is unchanged, otherwise, it is equal to the return value:
+\layout LyX-Code
+
+[ 1 2 ] [ 3 4 ] nappend .
+\layout LyX-Code
+
+
+\emph on 
+[ 1 2 3 4 ]
+\layout Standard
+
+Note in the above examples, we use literal list parameters to nreverse and
+ nappend.
+ This is actually a very bad idea, since the same literal list may be used
+ more than once! For example, lets make a colon definition:
+\layout LyX-Code
+
+: very-bad-idea [ 1 2 3 4 ] nreverse ;
+\layout LyX-Code
+
+very-bad-idea .
+\layout LyX-Code
+
+
+\emph on 
+[ 4 3 2 1 ]
+\layout LyX-Code
+
+very-bad-idea .
+\layout LyX-Code
+
+
+\emph on 
+[ 4 ]
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+very-bad-idea
+\begin_inset Quotes erd
+\end_inset 
+
+ see
+\layout LyX-Code
+
+
+\emph on 
+: very-bad-idea
+\layout LyX-Code
+
+
+\emph on 
+    [ 4 ] nreverse ;
+\layout Standard
+
+As you can see, the word definition itself was ruined!
+\layout Standard
+
+Sometimes it is desirable make a copy of a list, so that the copy may be
+ safely side-effected later.
+\layout Standard
+
+
+\family typewriter 
+clone-list ( list -- list )
+\family default 
+ pushes a new list containing the exact same elements as the original.
+ The elements themselves are not copied.
+\layout Standard
+
+If you want to write your own destructive list manipulation words, you can
+ use 
+\family typewriter 
+set-car ( value cons -- )
+\family default 
+ and 
+\family typewriter 
+set-cdr ( value cons -- )
+\family default 
+ to modify individual cons cells.
+ Some words that are not destructive on their inputs nonetheless create
+ intermediate lists which are operated on using these words.
+ One example is 
+\family typewriter 
+clone-list
+\family default 
+ itself.
+\layout Section
+
+Vectors
+\layout Standard
+
+A vector is a contiguous chunk of cells which hold references to arbitrary
+ objects.
+ Vectors have the following literal syntax:
+\layout LyX-Code
+
+{ f f f t t f t t -6 
+\begin_inset Quotes eld
+\end_inset 
+
+Hey
+\begin_inset Quotes erd
+\end_inset 
+
+ }
+\layout Standard
+
+Use of vector literals in source code is discouraged, since vector manipulation
+ relies on side effects rather than return values, and it is very easy to
+ mess up a literal embedded in a word definition.
+\layout Subsection
+
+Vectors versus lists
+\layout Standard
+
+Vectors are applicable for a different class of problems than lists.
+ Compare the relative performance of common operations on vectors and lists:
+\layout Standard
+
+
+\begin_inset  Tabular
+<lyxtabular version="3" rows="4" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Lists
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Vectors
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Random access of an index
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+linear time
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+constant time
+\end_inset 
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Add new element at start
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+constant time
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+linear time
+\end_inset 
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Add new element at end
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+linear time
+\end_inset 
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+constant time
+\end_inset 
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset 
+
+
+\layout Standard
+
+When using vectors, you need to pass around a vector and an index -- when
+ working with lists, often only a list head is passed around.
+ For this reason, if you need a sequence for iteration only, a list is a
+ better choice because the list vocabulary contains a rich collection of
+ recursive words.
+\layout Standard
+
+On the other hand, when you need to maintain your own 
+\begin_inset Quotes eld
+\end_inset 
+
+stack
+\begin_inset Quotes erd
+\end_inset 
+
+-like collection, a vector is the obvious choice, since most pushes and
+ pops can then avoid allocating memory.
+\layout Standard
+
+Vectors and lists can be converted back and forth using the 
+\family typewriter 
+vector>list
+\family default 
+ word 
+\family typewriter 
+( vector -- list )
+\family default 
+ and the 
+\family typewriter 
+list>vector
+\family default 
+ word 
+\family typewriter 
+( list -- vector )
+\family default 
+.
+\layout Subsection
+
+Vector manipulation
+\layout Standard
+
+
+\family typewriter 
+<vector> ( capacity -- vector )
+\family default 
+ pushes a zero-length vector.
+ Storing more elements than the initial capacity grows the vector.
+\layout Standard
+
+
+\family typewriter 
+vector-nth ( index vector -- obj )
+\family default 
+ pushes the object stored at a zero-based index of a vector:
+\layout LyX-Code
+
+0 { 
+\begin_inset Quotes eld
+\end_inset 
+
+zero
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+one
+\begin_inset Quotes erd
+\end_inset 
+
+ } vector-nth .
+\layout LyX-Code
+
+
+\emph on 
+
+\begin_inset Quotes eld
+\end_inset 
+
+zero
+\begin_inset Quotes erd
+\end_inset 
+
+
+\layout LyX-Code
+
+2 { 1 2 } vector-nth .
+\layout LyX-Code
+
+
+\emph on 
+ERROR: Out of bounds
+\layout Standard
+
+
+\family typewriter 
+set-vector-nth ( obj index vector -- )
+\family default 
+ stores a value into a vector:
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+The words 
+\family typewriter 
+get
+\family default 
+ and 
+\family typewriter 
+set
+\family default 
+ used in this example will be formally introduced later.
+\end_inset 
+
+
+\layout LyX-Code
+
+{ 
+\begin_inset Quotes eld
+\end_inset 
+
+math
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+CS
+\begin_inset Quotes erd
+\end_inset 
+
+ } 
+\begin_inset Quotes eld
+\end_inset 
+
+v
+\begin_inset Quotes erd
+\end_inset 
+
+ set
+\layout LyX-Code
+
+1 
+\begin_inset Quotes eld
+\end_inset 
+
+philosophy
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+v
+\begin_inset Quotes erd
+\end_inset 
+
+ get set-vector-nth
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+v
+\begin_inset Quotes erd
+\end_inset 
+
+ get .
+\layout LyX-Code
+
+
+\emph on 
+{ 
+\begin_inset Quotes eld
+\end_inset 
+
+math
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+philosophy
+\begin_inset Quotes erd
+\end_inset 
+
+ }
+\layout LyX-Code
+
+4 
+\begin_inset Quotes eld
+\end_inset 
+
+CS
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+v
+\begin_inset Quotes erd
+\end_inset 
+
+ get set-vector-nth
+\layout LyX-Code
+
+
+\begin_inset Quotes eld
+\end_inset 
+
+v
+\begin_inset Quotes erd
+\end_inset 
+
+ get .
+\layout LyX-Code
+
+
+\emph on 
+{ 
+\begin_inset Quotes eld
+\end_inset 
+
+math
+\begin_inset Quotes erd
+\end_inset 
+
+ 
+\begin_inset Quotes eld
+\end_inset 
+
+philosophy
+\begin_inset Quotes erd
+\end_inset 
+
+ f f 
+\begin_inset Quotes eld
+\end_inset 
+
+CS
+\begin_inset Quotes erd
+\end_inset 
+
+ }
+\layout Standard
+
+
+\family typewriter 
+vector-length ( vector -- length )
+\family default 
+ pushes the number of elements in a vector.
+ As the previous two examples demonstrate, attempting to fetch beyond the
+ end of the vector will raise an error, while storing beyond the end will
+ grow the vector as necessary.
+\layout Standard
+
+
+\family typewriter 
+set-vector-length ( length vector -- )
+\family default 
+ resizes a vector.
+ If the new length is larger than the current length, the vector grows if
+ necessary, and the new cells are filled with 
+\family typewriter 
+f
+\family default 
+.
+\layout Standard
+
+
+\family typewriter 
+vector-push ( obj vector -- )
+\family default 
+ adds an object at the end of the vector.
+ This increments the vector's length by one.
+\layout Standard
+
+
+\family typewriter 
+vector-pop ( vector -- obj )
+\family default 
+ removes the object at the end of the vector and pushes it.
+ This decrements the vector's length by one.
+\layout Subsection
+
+Vector combinators
+\layout Standard
+
+vector-each, vector-map
+\layout Section
+
+Strings
+\layout Subsection
+
+Strings are character vectors
+\layout Standard
+
+str-nth, str-length, substring, ...
+\layout Subsection
+
+String buffers are mutable
+\layout Standard
+
+<sbuf>, sbuf-append, sbuf>str
+\layout Standard
+
+Otherwise like a vector:
+\layout Standard
+
+sbuf-nth, set-sbuf-nth, sbuf-length, set-sbuf-length
+\layout Subsection
+
+String constructors
+\layout Standard
+
+<% % %>
+\layout Subsection
+
+Printing and reading strings
+\layout Standard
+
+print, write, read, turning a string into a number
+\layout Section
+
+PRACTICAL: Contractor timesheet
+\layout Standard
+
+TODO operations:
+\layout Standard
+
+- print a time difference as hours:minutes
+\layout Standard
+
+- begin work
+\layout Standard
+
+- end work & annotate
+\layout Standard
+
+- print an invoice, takes hourly rate as a parameter.
+ do simple formatted output, using 'spaces' and 'pad-string'.
+\layout Standard
+
+use a vector to store [ annotation | time ] pairs, pass the vector in
+\layout Section
+
+Organization
+\layout Subsection
+
+Hashtables
+\layout Subsection
+
+Namespaces
+\layout Subsection
+
+The name stack
+\layout Subsection
+
+The inspector
+\layout Section
+
+PRACTICAL: Music player
+\layout Section
+
+Deeper in the beast
+\layout Standard
+
+Text -> objects - parser, objects -> text - unparser for atoms, prettyprinter
+ for collections.
+\layout Standard
+
+What really is a word -- primitive, parameter, property list.
+\layout Standard
+
+Call stack how it works and >r/r>
+\layout Subsection
+
+Parsing words
+\layout Standard
+
+Lets take a closer look at Factor syntax.
+ Consider a simple expression, and the result of evaluating it in the interactiv
+e interpreter:
+\layout LyX-Code
+
+2 3 + .
+\layout LyX-Code
+
+
+\emph on 
+5
+\layout Standard
+
+The interactive interpreter is basically an infinite loop.
+ It reads a line of input from the terminal, parses this line to produce
+ a 
+\emph on 
+quotation
+\emph default 
+, and executes the quotation.
+\layout Standard
+
+In the parse step, the input text is tokenized into a sequence of white
+ space-separated tokens.
+ First, the interpreter checks if there is an existing word named by the
+ token.
+ If there is no such word, the interpreter instead treats the token as a
+ number.
+\begin_inset Foot
+collapsed false
+
+\layout Standard
+
+Of course, Factor supports a full range of data types, including strings,
+ lists and vectors.
+ Their source representations are still built from numbers and words, however.
+\end_inset 
+
+
+\layout Standard
+
+Once the expression has been entirely parsed, the interactive interpreter
+ executes it.
+\layout Standard
+
+This parse time/run time distinction is important, because words fall into
+ two categories; 
+\begin_inset Quotes eld
+\end_inset 
+
+parsing words
+\begin_inset Quotes erd
+\end_inset 
+
+ and 
+\begin_inset Quotes eld
+\end_inset 
+
+running words
+\begin_inset Quotes erd
+\end_inset 
+
+.
+\layout Standard
+
+The parser constructs a parse tree from the input text.
+ When the parser encounters a token representing a number or an ordinary
+ word, the token is simply appended to the current parse tree node.
+ A parsing word on the other hand is executed
+\emph on 
+ 
+\emph default 
+immediately after being tokenized.
+ Since it executes in the context of the parser, it has access to the raw
+ input text, the entire parse tree, and other parser structures.
+\layout Standard
+
+Parsing words are also defined using colon definitions, except we add 
+\family typewriter 
+parsing
+\family default 
+ after the terminating 
+\family typewriter 
+;
+\family default 
+.
+ Here are two examples of definitions for words 
+\family typewriter 
+foo
+\family default 
+ and 
+\family typewriter 
+bar
+\family default 
+, both are identical except in the second example, 
+\family typewriter 
+foo
+\family default 
+ is defined as a parsing word:
+\layout LyX-Code
+
+! Lets define 'foo' as a running word.
+\layout LyX-Code
+
+: foo 
+\begin_inset Quotes eld
+\end_inset 
+
+1) foo executed.
+\begin_inset Quotes erd
+\end_inset 
+
+ print ;
+\layout LyX-Code
+
+: bar foo 
+\begin_inset Quotes eld
+\end_inset 
+
+2) bar executed.
+\begin_inset Quotes erd
+\end_inset 
+
+ ;
+\layout LyX-Code
+
+bar
+\layout LyX-Code
+
+
+\emph on 
+1) foo executed
+\layout LyX-Code
+
+
+\emph on 
+2) bar executed
+\layout LyX-Code
+
+bar
+\layout LyX-Code
+
+
+\emph on 
+1) foo executed
+\layout LyX-Code
+
+
+\emph on 
+2) bar executed
+\layout LyX-Code
+
+\layout LyX-Code
+
+! Now lets define 'foo' as a parsing word.
+\layout LyX-Code
+
+: foo 
+\begin_inset Quotes eld
+\end_inset 
+
+1) foo executed.
+\begin_inset Quotes erd
+\end_inset 
+
+ print ; parsing
+\layout LyX-Code
+
+: bar foo 
+\begin_inset Quotes eld
+\end_inset 
+
+2) bar executed.
+\begin_inset Quotes erd
+\end_inset 
+
+ ;
+\layout LyX-Code
+
+
+\emph on 
+1) foo executed
+\layout LyX-Code
+
+bar
+\layout LyX-Code
+
+
+\emph on 
+2) bar executed
+\layout LyX-Code
+
+bar
+\layout LyX-Code
+
+
+\emph on 
+2) bar executed
+\layout Standard
+
+In fact, the word 
+\family typewriter 
+
+\begin_inset Quotes eld
+\end_inset 
+
+ 
+\family default 
+that denotes a string literal is a parsing word -- it reads characters from
+ the input text until the next occurrence of 
+\family typewriter 
+
+\begin_inset Quotes eld
+\end_inset 
+
+
+\family default 
+, and appends this string to the current node of the parse tree.
+ Note that strings and words are different types of objects.
+ Strings are covered in great detail later.
+\layout Section
+
+PRACTICAL: Infix syntax
+\layout Section
+
+Continuations
+\layout Standard
+
+Generators, co-routines, multitasking, exception handling
+\layout Section
+
+HTTP Server
+\layout Section
+
+PRACTICAL: Some web app
+\the_end
diff --git a/doc/math.txt b/doc/math.txt
new file mode 100644
index 0000000000..09f31099b7
--- /dev/null
+++ b/doc/math.txt
@@ -0,0 +1,307 @@
+FACTOR MATH WORDS
+
+=== Basics
+
+The following expressions demonstrate basic arithmetic in Factor.
+
+    0] 2 2 + .
+4
+    1] 10 4.5 - .
+5.5
+    2] 12.5 3 * .
+37.5
+    3] 6 20 / .
+3/10
+    4] 6 20 /f .
+0.3
+    5] 0.354 neg .
+-0.354
+    6] 5 recip .
+0.2
+
+Arithmetic operators appear after their oprands, and intermediate values
+are stored on a stack -- this is called postfix syntax.
+
+The word . prints the value at the top of the stack.
+
+There are no operator precedence levels, and expressions can always be
+reprepsented unambiguously without parantheses, unlike traditional
+algebraic syntax.
+
+For example, (3 + 2) * (1 - 6) is written as:
+
+3 2 + 1 6 - *
+
+However, 3 + (2 * 1) - 6 is written as:
+
+3 2 1 * + 6 -
+
+=== The number tower
+
+Factor supports operations with many types of numbers, transparently
+converting results from one type to another. The following informal
+diagram can be helpful in understanding the various types of numbers.
+
++--------+ +--------+
+|=fixnum=| |=bignum=|
++--------+ +--------+
++-------------------+ +-------+
+|      integer      | |=ratio=|
++-------------------+ +-------+
++-----------------------------+ +-------+
+|           rational          | |=float=|
++-----------------------------+ +-------+
++---------------------------------------+ +---------+
+|                  real                 | |=complex=|
++---------------------------------------+ +---------+
++---------------------------------------------------+
+|                      number                       |
++---------------------------------------------------+
+
+Types on the same row are disjoint.
+
+Each type is a subtype of all types directly below.
+
+Types whose boxes are marked with '=' are disjoint concrete types.
+
+Type upgrades are performed through the concrete types, from the top
+left down to the bottom right.
+
+Ratios and complex numbers are compound types; ratios consist of a pair
+of integers, complex numbers consist of a pair of real numbers.
+
+=== Types of numbers
+
+All number entry is in base 10.
+
+The predicate word number? tests if the top of the stack is a number.
+
+Numbers are partitioned into two disjoint subsets; real numbers and
+complex numbers. (In math, the reals are a subset of the complex
+numbers. In Factor, a number whose imaginary part is zero is *not* a
+complex number).
+
+Real numbers are partitioned into three disjoint subsets: integers,
+ratios and floats.
+
+==== Integers: 12 -100 340282366920938463463374607431768211456
+
+The predicate word integer? tests if the top of the stack is an integer.
+
+The integers are partitioned into two disjoint types:
+
+- signed 32-bit fixnums (predicate: fixnum?)
+- signed arbitrary precision bignums (predicate: bignum?)
+
+Fixnums are automatically upgraded as necessary to bignums.
+
+For example:
+
+    8] 1073741824 fixnum? .
+t
+    9] 128 fixnum? .
+t
+    10] 1073741824 128 * .    
+137438953472
+    11] 1073741824 128 * bignum? .
+t
+
+In the above example, the result of multiply those two fixnums exceeds
+2^31-1, and the result is upgraded to a bignum.
+
+When given integer operands, + - and * always return integers.
+
+==== Ratios: 1/10 -37/78 10/3
+
+A ratio is the result of a division of two integers where the
+denimonator is not a multiple of the numerator.
+
+The predicate word ratio? tests if the top of the stack is a ratio.
+
+Ratios are always reduced to lowest terms, and the denominator is always
+positive. The numerator never equals zero since dividing zero by a
+non-zero integer always results in the integer zero.
+
+The accessor words numerator and denominator deconstruct a ratio. Given
+an integer, numerator is a no-op and denominator always returns 1.
+
+    14] 100 -30 / numerator .
+-10
+    15] 100 -30 / denominator .
+3
+    16] 12 numerator .
+12
+
+The numerator and denominator are integers, and hence either fixnums or
+bignums (there is no requirement for them to be of the same type).
+
+The result of dividing two integers as a floating point number can be
+obtained using the word /f. For example:
+
+    17] 1 3 /f .
+0.3333333333333333
+
+When arithmetic operators are given a ratio and an integer as
+parameters, the result is also a ratio or an integer.
+
+==== Floats: -1.3 1.5e-6 0.003
+
+Floats are entered as double-precision. Single-precision floats can be
+constructed via coercion. They are converted to double-precision by
+arithmetic operands.
+
+The predicate word float? tests if the top of the stack is a single or
+double precision float.
+
+When at least one of the parameters to an arithmetic operator is a
+float, the result is always a (double precision) float.
+
+==== Complex numbers: #{ 2 2.5 } #{ 1/2 1/3 }
+
+A complex number has a real and imaginary part. The syntax is to write
+#{ followed by the real part, followed by the imaginary part, and
+finally terminated with }. Each token must be separted with whitespace.
+
+The predicate word complex? tests if the top of the stack is a single or
+double precision float.
+
+For example, what is commonly written as 2-3.5i in textbooks is
+expressed as #{ 2 2.5 } in Factor.
+
+The real and imaginary parts can be either integers, ratios or floats.
+There is no requirement for them to be of the same type.
+
+The accessor words real and imaginary deconstruct a complex number. The
+real part followed by the imaginary part can both be pushed at once
+using the word >rect, and a new complex number can be constructed from a
+real and imaginary part using the word rect>.
+
+    4] -i sqrt >rect .s
+-0.7071067811865475
+0.7071067811865476
+    5] 1 2 rect> .
+#{ 1 2 }
+
+A complex number with an imaginary component of zero is automatically
+downgraded to an integer, a ratio or a float (depending on the type of
+its real component.)
+
+    6] 10 0 rect> .
+10
+    7] #{ 5 -10 } #{ 2 10 } + .
+7
+
+Complex numbers never arise as results of arithmetic operators with real
+operands. However, various irrational functions return complex values
+for some real inputs.
+
+=== Mathematical functions
+
+==== Square root, squaring, arbitrary powers
+
+These are pretty much self-explanatory.
+
+    10] 36 sq sqrt .
+36.0
+    11] -2 sqrt sq .
+-2.0000000000000004
+    12] 10 15 ^ .
+1.0E15
+    13] e pi i * ^ .
+#{ -1.0 1.2246467991473532E-16 }
+
+==== Exponential, logarithm
+
+The function e^x and its inverse.
+
+    15] e .
+2.718281828459045
+    16] 2 exp .
+7.38905609893065
+    17] 5 log 2 log - exp .
+2.5
+
+Note that the complex logarithm is infinitely-valued. The principle
+value is chosen such that the complex part is in the interval (-pi,pi].
+
+    18] -10 log .
+#{ 2.302585092994046 3.141592653589793 }
+
+==== Trigonometric and hyperbolic functions
+
+The full complement of trigonometric and hyperbolic functions and their
+inverses is provided:
+
+sin    cos    tan
+asin   acos   atan
+cosec  sec    cot
+acosec asec   acot
+
+sinh    cosh    tanh
+asinh   acosh   atanh
+cosech  sech    coth
+acosech asech   acoth
+
+Complex arguments are supported. The specific branch cuts used by the
+inverse functions are undocumented by can be deduced from the
+definitions of those functions, and the branch cuts taken by 'log' and
+'sqrt'.
+
+==== Polar co-ordinates
+
+Complex numbers can be converted to/from polar co-ordinate
+representations using the words >polar and polar>.
+
+    41] #{ 1 1 } >polar .s
+0.7853981633974483
+1.4142135623730951
+    42] -5 pi 3 / polar> .
+#{ -2.5000000000000004 -4.330127018922193 }
+
+==== Miscellaneous integer functions
+
+Factorial, fibonacci sequence, harmonic numbers.
+
+    33] 128 2^ .
+340282366920938463463374607431768211456
+    34] 30 fib .
+1346269
+    35] 100 harmonic >float 100 log - .
+0.5822073316515288
+    36] 1000 fac .
+402387260077093773543702433923003985719374864210714632543799910429938512
+398629020592044208486969404800479988610197196058631666872994808558901323
+829669944590997424504087073759918823627727188732519779505950995276120874
+975462497043601418278094646496291056393887437886487337119181045825783647
+849977012476632889835955735432513185323958463075557409114262417474349347
+553428646576611667797396668820291207379143853719588249808126867838374559
+731746136085379534524221586593201928090878297308431392844403281231558611
+036976801357304216168747609675871348312025478589320767169132448426236131
+412508780208000261683151027341827977704784635868170164365024153691398281
+264810213092761244896359928705114964975419909342221566832572080821333186
+116811553615836546984046708975602900950537616475847728421889679646244945
+160765353408198901385442487984959953319101723355556602139450399736280750
+137837615307127761926849034352625200015888535147331611702103968175921510
+907788019393178114194545257223865541461062892187960223838971476088506276
+862967146674697562911234082439208160153780889893964518263243671616762179
+168909779911903754031274622289988005195444414282012187361745992642956581
+746628302955570299024324153181617210465832036786906117260158783520751516
+284225540265170483304226143974286933061690897968482590125458327168226458
+066526769958652682272807075781391858178889652208164348344825993266043367
+660176999612831860788386150279465955131156552036093988180612138558600301
+435694527224206344631797460594682573103790084024432438465657245014402821
+885252470935190620929023136493273497565513958720559654228749774011413346
+962715422845862377387538230483865688976461927383814900140767310446640259
+899490222221765904339901886018566526485061799702356193897017860040811889
+729918311021171229845901641921068884387121855646124960798722908519296819
+372388642614839657382291123125024186649353143970137428531926649875337218
+940694281434118520158014123344828015051399694290153483077644569099073152
+433278288269864602789864321139083506217095002597389863554277196742822248
+757586765752344220207573630569498825087968928162753848863396909959826280
+956121450994871701244516461260379029309120889086942028510640182154399457
+156805941872748998094254742173582401063677404595741785160829230135358081
+840096996372524230560855903700624271243416909004153690105933983835777939
+410970027753472000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000
diff --git a/doc/naming.txt b/doc/naming.txt
new file mode 100644
index 0000000000..9fc82ef1cd
--- /dev/null
+++ b/doc/naming.txt
@@ -0,0 +1,66 @@
+FACTOR CODING CONVENTIONS.
+
+=== Naming words
+
+foo.     - perform "foo", but instead of pushing the result on the
+           stack, print it in a human-readable form suitable for
+	   interactive use.
+
+	   Eg: words. vocabs.
+
+.X       - three words to print the contents of the stacks:
+           .s - data stack
+	   .r - call stack
+	   .n - name stack
+
+foo*     - a variation of "foo" that takes more parameters.
+
+           Eg: index-of* parse* random-element*
+
+         - a lower-level word used in the implementation of "foo".
+
+	   Eg: compile* prettyprint*
+
+         - a word that is a variation on "foo", but is more specialized
+	   and less frequently used.
+
+	   Eg: last* get*
+
+>into    - convert object to type "into".
+
+           Eg: >str >lower >upper >fixnum >realnum
+
+one>two  - convert object of type "one" to "two".
+
+           Eg: stream>str stack>list worddef>list
+
+         - transfer values between stacks.
+	 
+	   Eg: >r r> 2>r 2r> >n
+
+<type>   - create an object of "type".
+
+           Eg: <namespace> <sbuf> <stream>
+
+foo@     - get the value of a variable at the top of the stack;
+           operate on the value with "foo"; store the value back in the
+	   variable.
+
+	   Eg: +@ *@ -@ /@ cons@ append@
+
+foo-iter - a tail-recursive word used in the implementatin of "foo".
+
+           Eg: nreverse-iter partition-iter
+
+nfoo     - on lists, a destructive version of "foo".
+
+           Eg: nappend nreverse
+
+2foo     - like foo but with two operands taken from stack.
+
+           Eg: 2drop 2dup 2each
+
+[foo]    - apply "foo" to each element of a list; sometimes with a bit
+           more logic than just [ foo ] each.
+
+	   Eg: [+] [.]
diff --git a/factor/FactorInterpreter.java b/factor/FactorInterpreter.java
index 331b76cc8a..12ae36e1e7 100644
--- a/factor/FactorInterpreter.java
+++ b/factor/FactorInterpreter.java
@@ -35,7 +35,7 @@ import java.io.*;
 
 public class FactorInterpreter implements FactorObject, Runnable
 {
-	public static final String VERSION = "0.60.8";
+	public static final String VERSION = "0.60.9";
 
 	// command line arguments are stored here.
 	public Cons args;