README

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