From 61c71638b131f86c95393f6ded9b14145a26635f Mon Sep 17 00:00:00 2001 From: Tim Vaughan Date: Mon, 2 May 2016 14:40:29 +1200 Subject: [PATCH] Added README --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..f6d18bc --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +# forth.jl + +A hobby implementation of a FORTH-like system atop the Julia scientific +computing language. It will never be useful for any purpose besides, perhaps, +pedagogical - although I wouldn't advise trying to learn forth by using this +code directly. A better approach is to combine reading something like Leo Brodie's +book Starting Forth with implementing your own forth. + +To a large degree this project is simply a port of the literate programming +project JonesForth 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. A huge proportion (say 80%) of the library code in src/lib.4th +is directly copied from JonesForth. I've added some additional core definitions +and modified some of the others to be a little bit closer to the behaviour of +ANS forth (or at least FORTH 83). + +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") + +## 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 + +Notice that unlike other forths, forth.jl echos a newline after reading each +line of standard input. This is an unfortunate side-effect of the way that +I've implemented the primitive word KEY. Hopefully I'll be able to fix this +in future. + +There's an example Mandelbrot Set drawing program included in the examples +directory. To run it, you'll have to locate this directory on your system +(its location depends on what OS you happen to be using). Once found, use +the "INCLUDE" word to compile its definitions. For example, on my system +I can run the example in this way: + + include /home/tim/.julia/v0.4/forth/examples/mandelbrot.4th + Enter 'mandel' to draw the Mandelbrot Set. ok + mandel + * + + ** + ******** + ********* + ***** + *** ******************** + ****************************** **** + ********************************** + *************************************** + ******************************************** + ** * ******************************************* + ************* ********************************************* + ****************** ******************************************** + ******************* ******************************************** + ** * * ******************************************************************* + ******************* ******************************************* + ***************** ******************************************** + ************* ******************************************** + ** * ******************************************** + ******************************************** + ************************************** + *********************************** + ****************************** **** + ** ******************** + ***** + ******* + ********* + ** + ok + +## 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. -- 2.20.1