X-Git-Url: https://thelambdalab.xyz/gitweb/index.cgi?p=forth.jl.git;a=blobdiff_plain;f=README.md;h=a6e0645b2a34c19dcd6b0b5fa86dc14107186679;hp=f6d18bc081ecbaef128f6511c943a52a42ef66c9;hb=43cd7e6d8968a85ee9250033080268caafef5a47;hpb=61c71638b131f86c95393f6ded9b14145a26635f diff --git a/README.md b/README.md index f6d18bc..a6e0645 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,20 @@ # 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). +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. @@ -24,6 +26,9 @@ 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 @@ -35,23 +40,14 @@ the julia prompt: 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. + : star 42 emit ; ok + star * ok 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: +directory. To run it, use the `INCLUDE-LIB` word to open the file and compile its +definitions: - include /home/tim/.julia/v0.4/forth/examples/mandelbrot.4th + include-lib ../examples/mandelbrot.4th Enter 'mandel' to draw the Mandelbrot Set. ok mandel * @@ -85,6 +81,41 @@ I can run the example in this way: ** 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