README.md

   1 # forth.jl
   2
   3 A hobby implementation of a FORTH-like system atop the Julia scientific
   4 computing language.  It will almost certainly never be useful for any purpose
   5 besides that which it has already fulfilled: forcing me to think quite
   6 carefully about 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 to be a little bit closer to the
  17 behaviour of ANS forth (or at least FORTH 83).
  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 ;
  41      ok
  42     star
  43     * ok
  44
  45 Notice that unlike other forths, forth.jl echos a newline after reading each
  46 line of standard input.  This is an unfortunate side-effect of the way that
  47 I've implemented the primitive word KEY.  Hopefully I'll be able to fix this
  48 in future.
  49
  50 There's an example Mandelbrot Set drawing program included in the examples
  51 directory.  To run it, you'll have to locate this directory on your system (its
  52 location depends on what OS you happen to be using and how julia is installed).
  53 Once found, use the "INCLUDE" word to compile its definitions. For example, on
  54 my system I can run the example in this way:
  55
  56     include /home/tim/.julia/v0.4/forth/examples/mandelbrot.4th
  57     Enter 'mandel' to draw the Mandelbrot Set. ok
  58     mandel
  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                                                                        *********
  87                                                                            **
  88     ok
  89
  90 ## License
  91
  92 This package is free software and is distributed under version 3.0 of the GNU
  93 General Public License, which may be found in the file LICENSE in this
  94 directory.