README.md

   1 # forth.jl
   2
   3 A hobby implementation of a FORTH-like system atop the Julia scientific
   4 computing language.  It will never be useful for any purpose besides, perhaps,
   5 pedagogical - although I wouldn't advise trying to learn forth by using this
   6 code directly. A better approach is to combine reading something like Leo Brodie's
   7 book Starting Forth with implementing your own forth.
   8
   9 To a large degree this project is simply a port of the literate programming
  10 project JonesForth from x86 assembly + forth to julia + forth, although the
  11 mapping is in a few places non-trivial due to the fact that julia is a high
  12 level language.  A huge proportion (say 80%) of the library code in src/lib.4th
  13 is directly copied from JonesForth.  I've added some additional core definitions
  14 and modified some of the others to be a little bit closer to the behaviour of
  15 ANS forth (or at least FORTH 83).
  16
  17 There's quite a lot to say about the implementation, especially due to its
  18 high-level grounding, but that will have to wait for another time.
  19
  20 ## Installation
  21
  22 forth.jl is not (and probably will never be) a registered julia package.  To
  23 install it, you will therefore need to use the following command:
  24
  25     julia> Pkg.clone("https://github.com/tgvaughan/forth.jl")
  26
  27 ## Usage
  28
  29 To start the interpreter/compiler running, simply enter the following at
  30 the julia prompt:
  31
  32     julia> import forth
  33     julia> forth.run()
  34
  35 The first thing the interpreter will do is compile the core definitions in
  36 the library file.  Once this is complete you can start entering forth commands:
  37
  38     : star 42 emit ;
  39      ok
  40     star
  41     * ok
  42
  43 Notice that unlike other forths, forth.jl echos a newline after reading each
  44 line of standard input.  This is an unfortunate side-effect of the way that
  45 I've implemented the primitive word KEY.  Hopefully I'll be able to fix this
  46 in future.
  47
  48 There's an example Mandelbrot Set drawing program included in the examples
  49 directory.  To run it, you'll have to locate this directory on your system
  50 (its location depends on what OS you happen to be using).  Once found, use
  51 the "INCLUDE" word to compile its definitions. For example, on my system
  52 I can run the example in this way:
  53
  54     include /home/tim/.julia/v0.4/forth/examples/mandelbrot.4th
  55     Enter 'mandel' to draw the Mandelbrot Set. ok
  56     mandel
  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                                                            **     ********************
  82                                                                          *****
  83                                                                         *******
  84                                                                        *********
  85                                                                            **
  86     ok
  87
  88 ## License
  89
  90 This package is free software and is distributed under version 3.0 of the GNU
  91 General Public License, which may be found in the file LICENSE in this
  92 directory.