-# FORTH
+# forth.jl
+
+A hobby implementation of a forth system atop the Julia scientific computing
+language. It will almost certainly never be useful for any purpose besides
+that which it has already fulfilled: forcing me to think quite carefully about
+how forth works.
+
+This package owes a massive debt to the existence of the literate programming
+project [JonesForth](https://rwmj.wordpress.com/2010/08/07/jonesforth-git-repository/),
+which was an amazing read. To a large degree my package is simply a port of
+that project from x86 assembly + forth to julia + forth, although the mapping
+is in a few places non-trivial due to the fact that julia is a high level
+language. During the bootstrapping process, a huge proportion (say 80%) of the
+library code in src/lib.4th was directly copied from JonesForth. (The fact
+that it was possible to reuse this code was satisfying in its own right!) Since
+that time I've added a significant number of core definitions and modified some
+of the others with the eventual aim of F83 compliance (discussed below).
+
+There's quite a lot to say about the implementation, especially due to its
+high-level grounding, but that will have to wait for another time.
+
+## Installation
+
+forth.jl is not (and probably will never be) a registered julia package. To
+install it, you will therefore need to use the following command:
+
+ julia> Pkg.clone("https://github.com/tgvaughan/forth.jl")
+
+Currently, forth.jl **requires** Julia 0.6. (Incompatabilities exist between
+0.6 and previous versions of julia, particularly the handling of [world age](https://github.com/JuliaLang/julia/pull/17057).)
+
+## Usage
+
+To start the interpreter/compiler running, simply enter the following at
+the julia prompt:
+
+ julia> import forth
+ julia> forth.run()
+
+The first thing the interpreter will do is compile the core definitions in
+the library file. Once this is complete you can start entering forth commands:
+
+ : star 42 emit ; ok
+ star * ok
+
+There's an example Mandelbrot Set drawing program included in the examples
+directory. To run it, use the `INCLUDE-LIB` word to open the file and compile its
+definitions:
+
+ include-lib ../examples/mandelbrot.4th
+ Enter 'mandel' to draw the Mandelbrot Set. ok
+ mandel
+ *
+
+ **
+ ********
+ *********
+ *****
+ *** ********************
+ ****************************** ****
+ **********************************
+ ***************************************
+ ********************************************
+ ** * *******************************************
+ ************* *********************************************
+ ****************** ********************************************
+ ******************* ********************************************
+ ** * * *******************************************************************
+ ******************* *******************************************
+ ***************** ********************************************
+ ************* ********************************************
+ ** * ********************************************
+ ********************************************
+ **************************************
+ ***********************************
+ ****************************** ****
+ ** ********************
+ *****
+ *******
+ *********
+ **
+ ok
+
+(`INCLUDE-LIB` is exactly like INCLUDE, but includes files relative to thte
+platform-dependent forth.jl src/ directory.) To exit, enter ^D on a blank line
+or use the `BYE` word.
+
+## FORTH-83 Compliance
+
+One of my goals has been to have forth.jl contain as much of the
+[F83 required word set](http://forth.sourceforge.net/standard/fst83/fst83-12.htm)
+as makes sense given the underlying VM. (Actually, my main goal goes a bit
+beyond this: I want to forth.jl to be, with a couple of exceptions, compatible
+with the description of forth contained in the second edition of Leo Brodie's
+book "Starting Forth".) I'm fairly happy with my progress so far. Of the
+131 required F83 words, only 20 remain unimplemented. These words fall into
+two categories: those I may possibly implement at some point, and those that I
+do not intend to ever implement for reasons of obsolescence or incompatibility
+with the design of the VM.
+
+### F83 Words that may be implemented someday
+
+ # #> #S -TRAILING <#
+
+These words all have to do with number to string conversion, something I've
+not been interested in enough yet to get on top of.
+
+### F83 Words that won't be implemented
+
+ D+ D< DNEGATE U< UM* UM/MOD BLOCK BUFFER FLUSH
+ SAVE-BUFFERS UPDATE BLK HOLD LOAD FORTH-83
+
+These words don't make sense to implement. The double-length integer words are
+useless because the smallest unit of memory in our VM is a full 64 bit
+integer. For the same reason, there's no point in dealing with unsigned values
+just to gain access to another bit. The block I/O words don't make sense because
+we have access to a filesystem via the OS.
+
+## License
+
+This package is free software and is distributed under version 3.0 of the GNU
+General Public License, which may be found in the file LICENSE in this
+directory.
The Lambda Lab / projects / forth.jl.git / blobdiff