README.md

   1 # forth.jl
   2
   3 A hobby implementation of a forth system atop the Julia scientific computing
   4 language.  It will almost certainly never be useful for any purpose besides
   5 that which it has already fulfilled: forcing me to think quite carefully about
   6 how forth works.
   7
   8 This package owes a massive debt to the existence of the literate programming
   9 project [JonesForth] (https://rwmj.wordpress.com/2010/08/07/jonesforth-git-repository/),
  10 which was an amazing read. To a large degree my package is simply a port of
  11 that project from x86 assembly + forth to julia + forth, although the mapping
  12 is in a few places non-trivial due to the fact that julia is a high level
  13 language.  A huge proportion (say 80%) of the library code in src/lib.4th is
  14 directly copied from JonesForth.  (The fact that it was possible to reuse this
  15 code was satisfying in its own right!) I've added some additional core
  16 definitions and modified some of the others with the eventual aim of F83
  17 compliance (discussed below).
  18
  19 There's quite a lot to say about the implementation, especially due to its
  20 high-level grounding, but that will have to wait for another time.
  21
  22 ## Installation
  23
  24 forth.jl is not (and probably will never be) a registered julia package.  To
  25 install it, you will therefore need to use the following command:
  26
  27     julia> Pkg.clone("https://github.com/tgvaughan/forth.jl")
  28
  29 ## Usage
  30
  31 To start the interpreter/compiler running, simply enter the following at
  32 the julia prompt:
  33
  34     julia> import forth
  35     julia> forth.run()
  36
  37 The first thing the interpreter will do is compile the core definitions in
  38 the library file.  Once this is complete you can start entering forth commands:
  39
  40     : star 42 emit ;  ok
  41     star * ok
  42
  43 There's an example Mandelbrot Set drawing program included in the examples
  44 directory.  To run it, use the `INCLUDE` word to open the file and compile its
  45 definitions.  Although the exact location of the examples directory in your
  46 filesystem is platform dependent, `INCLUDE` includes the forth.jl src/ directory
  47 in its search path so the following should always work:
  48
  49     include ../examples/mandelbrot.4th
  50     Enter 'mandel' to draw the Mandelbrot Set. ok
  51     mandel
  52                                                                                 *
  53
  54                                                                            **
  55                                                                         ********
  56                                                                        *********
  57                                                                          *****
  58                                                           ***     ********************
  59                                                            ****************************** ****
  60                                                           **********************************
  61                                                        ***************************************
  62                                                      ********************************************
  63                                   **    *            *******************************************
  64                                   *************    *********************************************
  65                                ******************  ********************************************
  66                                ******************* ********************************************
  67          **    *     *  *******************************************************************
  68                                ******************* *******************************************
  69                                 *****************  ********************************************
  70                                   *************     ********************************************
  71                                   **    *           ********************************************
  72                                                      ********************************************
  73                                                         **************************************
  74                                                          ***********************************
  75                                                            ****************************** ****
  76                                                            **     ********************
  77                                                                          *****
  78                                                                         *******
  79                                                                        *********
  80                                                                            **
  81     ok
  82
  83 To exit, enter ^D on a blank line or use the `BYE` word.
  84
  85 ## FORTH-83 Compliance
  86
  87 One of my goals has been to have forth.jl contain as much of the
  88 [F83 required word set](http://forth.sourceforge.net/standard/fst83/fst83-12.htm)
  89 as makes sense given the underlying VM. (Actually, my main goal goes a bit
  90 beyond this: I want to be able to, with a couple of exceptions, be compatible
  91 with the description of forth contained in the second edition of Leo Brodie's
  92 book "Starting Forth".)  I'm fairly happy with my progress so far.  Of the
  93 131 required F83 words, only 22 remain unimplemented.  These words fall into
  94 three categories: those I intend to implement in the near future, those I may
  95 possibly implement at some point, and those that I do not intend to ever implement
  96 for reasons of obsolescence or incompatibility with the design of the VM.
  97
  98 ### F83 Words to be implemented soon
  99
 100     PAD ABORT"
 101
 102 The words `PAD` is a simple oversite. `ABORT"` will also be implemented soon.
 103
 104 ### F83 Words that may be implemented someday
 105
 106     # #> #S -TRAILING <#
 107
 108 These words all have to do with number to string conversion, something I've
 109 not been interested in enough yet to get on top of.
 110
 111 ### F83 Words that won't be implemented
 112
 113     D+ D< DNEGATE U< UM* UM/MOD BLOCK BUFFER FLUSH
 114     SAVE-BUFFERS UPDATE BLK HOLD LOAD FORTH-83
 115
 116 These words don't make sense to implement.  The double-length integer words are
 117 useless, because the smallest unit of memory in our VM is a full 64 bit
 118 integer.  For the same reason, there's no point in dealing with unsigned values
 119 just to gain access to another bit.  The block I/O words don't make sense because
 120 we have access to a filesystem via the OS.
 121
 122 ## License
 123
 124 This package is free software and is distributed under version 3.0 of the GNU
 125 General Public License, which may be found in the file LICENSE in this
 126 directory.