X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?p=forth.jl.git;a=blobdiff_plain;f=README.md;h=09c124f6067350c41d2f8aae7a4c5198001bbc6e;hp=54dd58b663a1dc6d30a36575df12bd1ea45b7126;hb=HEAD;hpb=3f94f6047a8788a3ba10ec6c267eff0e08400d7f diff --git a/README.md b/README.md deleted file mode 100644 index 54dd58b..0000000 --- a/README.md +++ /dev/null @@ -1,120 +0,0 @@ -# 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") - -## 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.