Merged macro quasiquote into analyze.
[scheme.forth.jl.git] / README.md
1 scheme.forth.jl
2 ---------------
3
4 A hobby Scheme interpreter for FORTH 83. Specifically it is targeted at
5 [forth.jl](http://github.com/tgvaughan/forth.jl) which is an implementation of
6 FORTH on top of [Julia](http://www.julialang.org), hence the name.  It began
7 life as a fairly direct port of Peter Micheaux's [Bootstrap
8 Scheme](https://github.com/petermichaux/bootstrap-scheme) (as described in
9 [this wonderful series of blog
10 posts](http://peter.michaux.ca/articles/scheme-from-scratch-introduction)) from
11 C to forth, but also includes variadic compound function support, mark-sweep
12 garbage collection, quasiquotation, and a basic (non-hygienic) macro
13 system.
14
15 In future, I plan to also implement a more complete numerical tower to bring it closer to
16 [R5RS](http://www.schemers.org/Documents/Standards/R5RS/).
17
18 The goal is for the interpreter to be complete enough to be used to complete
19 the majority of the exercises found in [SICP](http://sarabander.github.io/sicp/).
20
21 Running the interpreter
22 =======================
23
24 To run this Scheme interpreter, first open Julia from the src directory contained
25 in this repository.  If you've not done so already, install forth.jl using the
26 following command:
27
28     julia> Pkg.clone("https://github.com/tgvaughan/forth.jl")
29
30 Then, import and run the Forth system:
31
32     julia> import forth
33     julia> forth.run()
34     Welcome to forth.jl!
35
36 Once Forth is running, execute the Scheme source and fire up the
37 REPL using the following commands:
38
39     include scheme.4th  ok
40     scheme repl
41     Welcome to scheme.forth.jl!
42     Use Ctrl-D to exit.
43
44     >
45
46 At this point you can start entering Scheme commands.  For example,
47
48     > (define (factorial n)
49         (if (= n 0)
50           1
51           (* n (factorial (- n 1)))))
52     ; ok
53     > (factorial 5)
54     ; 120
55
56 Metacircular Evaluator
57 ======================
58
59 Of course, one of the things you can do in Scheme (or of course any programming
60 language, this is the fundamental thing) is implement an interpreter for
61 another programming language.  The examples directory in this repository
62 contains a verbatim copy of the source for the "metacircular" scheme interpreter
63 from SICP. To load it, use the following command:
64
65     > (load "../examples/metacirc.scm")
66     ; ok
67
68 Be prepared to wait a couple of minutes. When the interpreter finally loads, enter
69 the following command to run it:
70
71     > (driver-loop)
72
73 You'll then be greeted by the following prompt:
74
75     ;; M-Eval input:
76
77 At this point you can start entering Scheme commands... but be prepared to wait
78 a while for each result.  After all, when evaluating commands in the MCE you are
79 running a program in a Scheme interpreter running inside another Scheme
80 interpreter which is itself running on a Forth system that is implemented atop
81 a virtual register machine running in the Julia numerical computing
82 environment.  **That's four levels of abstraction more than a native Julia
83 program experiences**, so some delay is to be expected!
84
85 For instance, the following example from SICP defines and demonstrates a
86 recursive list append procedure:
87
88     (define (append x y)
89        (if (null? x)
90            y
91            (cons (car x)
92                  (append (cdr x) y))))
93
94      ;;; M-Eval value:
95      ok
96
97      ;;; M-Eval input:
98      (append '(a b c) '(d e f))
99
100      ;;; M-Eval value:
101      (a b c d e f)
102
103 You may have to wait a minute or so for the final result to be printed.
104
105 License
106 =======
107
108 This software is free (as in freedom) and is distributed under the terms
109 of version 3 of the GNU General Public License.  A copy of this license
110 is included in this repository in the file COPYING.