-# 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 from the
-Julia package manager (accessed using the `]` key):
-
- (v1.0) pkg> add https://github.com/tgvaughan/forth.jl
+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 from the Julia package manager (accessed using the `]` key):
+
+ (v1.0) pkg> add git://thelambdalab.xyz/forth.jl.git
Be aware that **forth.jl requires Julia 1.0**.
-## Usage
+Usage
+-----
-To start the interpreter/compiler running, simply enter the following at
-the julia prompt:
+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:
+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:
+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
**
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.
+(`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.
+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.
+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
+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.
+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 / commitdiff