The next task I set out to complete for Scheme in Scheme was implement lambda.  I can’t really say that I got that far.  After wrestling with it for a while I realized that I didn’t have a good foundation and therefore implementing lambda was going to be difficult.  I had a quasi-virtual machine at that point.  I decided it would be better to convert the the current code into a more fully featured virtual machine instead of trying to retrofit lambda in what was there.  This update can really be split into two pieces — the execution of byte code and the compiler.

Byte Code

I’ve invented a byte code format for my project.  The virtual machine will execute the byte code in the order it’s given to it.  Here are some byte code examples:

#;6> (compile-form '(+ 1 2))
((push 1) (push 2) (add))
#;7> (compile-form '(/ 5 x))
((push 5) (get x) (div))
#;8> (compile-form '(+ 1 2 (- 5 3) (* 2 50)))
((push 1) (push 2) (add) (push 5) (push 3) (sub) (add) (push 2) (push 50) (mul) (add))
#;9> (compile-form '(define x 3))
((push 3) (define x))

The function compile-form takes in a list and transforms it into a list of instructions.  The very simple list (+ 1 2) translates into ((push 1) (push 2) (add)).   Since this is a stack machine the add instruction will pop two arguments off the stack, add them, and push them back onto the stack.  All of the arithmetic operations have implicit parameters which are pushed onto the stack. A lot more logic has been transferred into the compilation step for arithmetic.

(define (instruction/arithmetic env op)
 (let* ((num2   (env/pop! env))
        (num1   (env/pop! env))
        (result (case op
                  [(add) (+ num1 num2)]
                  [(sub) (- num1 num2)]
                  [(mul) (* num1 num2)]
                  [(div) (/ num1 num2)])))
  (env/push! env result))
 env)

All the instructions are pretty simple.  Push objects onto the stack, call the instruction, and then pop off the result.  There are only three instructions currently that take an argument: push, get, and define.  The get instruction pulls a value from a binding in the environment.  So if x was previously bound to 3 via (define x 3) then the byte code (get x) would push 3 onto the stack.  The define instruction operates in the same way except it pops the top off the stack and binds that object to it’s argument.  (define x 3) will produce ((push 3) (define x)) which binds x to 3.

Compiling

Here is the bulk of the code for the compiler:

(define (compile-arg arg)
 (if (self-evaluating? arg)
     `((push ,arg))
     (if (symbol? arg)
         `((get ,arg))
         (compile-form arg))))

;; Compiles the pushes for arithemtic args.  This will, at most, push two
;; arguments onto the stack.  If arguments are lacking, depending on the
;; op, this will push an null-operator (0 for add, 1 for mul).
(define (compile-arithmetic op args)
 (case (length args)
   [(0) `((push ,(default-arithmetic-val op))
          (push ,(default-arithmetic-val op))
          (,op))]
   [(1) `(,@(compile-arg (car args))
          (push ,(default-arithmetic-val op))
          (,op))]
   [(2) `(,@(compile-arg (car args))
          ,@(compile-arg (cadr args))
          (,op))]
 [else (append (compile-arithmetic op (take args 2))
               (append-map (lambda (x) `(,@(compile-arg x) (,op)))
                           (drop args 2)))]))

(define (compile-define binding args)
 (if (symbol? binding)
     ; If the binding is a symbol there should only be one other element
     ; in the list (define binding arg)
     `(,@(compile-arg (car args)) (define ,binding))))

;; Takes in a Scheme form for input and returns a list of instructions.
(define (compile-form input)
  (let ((form-name (car input))
        (args      (cdr input)))
    (case form-name
       [(+) (compile-arithmetic 'add args)]
       [(-) (compile-arithmetic 'sub args)]
       [(*) (compile-arithmetic 'mul args)]
       [(/) (compile-arithmetic 'div args)]
       [(define) (compile-define (car args) (cdr args))]
       [else (list (car input))])))

The first thing to look at is compile-form.  This function is the main entry point into the compiler.  It destructures the list by pulling out the operation (form-name in the code) being performed and the arguments passed to the operation.  It then calls into specific compilation routines based on the operation.

Most of the compilation at this point just deals with a lot of list manipulation.  A list goes into to compile-form and a list comes out.  Each element in the output list is an instruction.  Instruction themselves are lists.  Usually the instructions are only one element long but those that take parameters are two elements long.

The most interesting function in the compiler is probably the arithmetic compiler.  If I open up a scheme interpreter and type (+) it gives me 0.  (+ 1) gives me 1.  I had to special case the zero, one and two argument cases because of this.  All of the arithmetic instructions will pop two objects off the stack and operate on them.  The simple way of handling this is to always generate dummy pushes for missing arguments.  Zero arguments generates two pushes with a default value (for add it’s 0).  One argument pushes a dummy argument and the parameter argument.  Two arguments just push the two parameters onto the stack.

#;2> (compile-form '(+))
((push 0) (push 0) (add))
#;3> (compile-form '(+ 1))
((push 1) (push 0) (add))
#;4> (compile-form '(+ 1 2))
((push 1) (push 2) (add))

When dealing with 3 or more arguments the compiler will create byte code with two pushes, the arithmetic instruction and then interleaving pushes and instructions.

#;1> (compile-form '(- 5 2 3))
((push 5) (push 2) (sub) (push 3) (sub))
#;2> (compile-form '(- 5 2 3 4 1 2 3 5))
((push 5) (push 2) (sub) (push 3) (sub) (push 4) (sub) (push 1) (sub) (push 2) (sub) (push 3) (sub) (push 5) (sub))

The last little bit is the compile-arg function.  It is used to evaluate arguments that are not self-evaluation (simple).  This recursive compilation allows for nested lists.  If I pass the compiler (+ 5 2 (- 3 2)) it will properly generate code to subtract and then add all the numbers up.

#;1> (compile-form '(+ 5 2 (- 3 2)))
((push 5) (push 2) (add) (push 3) (push 2) (sub) (add))
#;2> (repl)
-: (+ 5 2 (- 3 2))
8
-: quit
quit

As always, you can see the code for this part of Scheme In Scheme on my Git Hub account at Part 4.

I’ve been trying to figure out what part of Scheme to implementation next.  Most things that looks simple are actually complex.  I also want to choose forms that will give me a minimal Scheme.  Many things in the language can be written using a combination of other forms.  Looking at the Wikipedia article on Scheme the following things are required to get the minimum Scheme:

1. define
2. lambda
3. if
4. quote, unquote, unquote-splicing, quasiquote
5. define-syntax, let-syntax, letrec-syntax, syntax-rules (or another macro system)
6. set!

Define has already been covered.  lambda seems like a good choice because it will give me a lot more of the language than some of the other forms.  I can write things like let using lambda.  Implementing lambda will also let me dive into implementing a virtual machine.

Scheme In Scheme is going to use a stack based virtual machine.  A stack based virtual machine is a natural fit for Scheme since it’s a functional language.  There are multiple pros and cons of using this type of virtual machine over other types.  I’m using a stack machine because it fits the problem well and will make implementation easier.

I’m going to start with execution of arithmetic forms.  This will allow me to work the code up to full lambda support by breaking the problem up into smaller pieces and building upon the solutions for those pieces.  For my virtual machine I want to turn this:

(+ 1 2)

into this:

(push 1)
(push 2)
(add)
(pop)

This will push the 1 and the 2 onto the stack where they can now be added by (+).  The implied behavior of add is that it will pop the numbers off the stack, add them, and push the result back on the stack.  In scheme executing an add form will add all numbers following the +. Scheme in Scheme, for now, I’ll only be dealing with executing two numbers.  Here is the actual code.

(define (exec-form input env)
 (for-each (lambda (x) (exec-instruction! env 'push (vm-eval x env)))
           (cdr input))
 (exec-instruction! env (car input))
 (exec-instruction! env 'pop))

All arguments are pushed onto the stack through a push operation in a for-each.  Afterwards the instruction is executed and the result is popped off the environment stack and returned from exec-form.  There could have been a direct translation from the addition form to the individual instructions but at this point an intermediate byte code doesn’t really get us much. I will keep it simple for now.

There is one important piece here that escaped me at first: each argument in the input list passed to vm-eval before it is pushed onto the stack.  This allows us to evaluate sub-lists within an expression.  I don’t know if this will be a good long term solution but it works for now.

Note that the second line just grabs the first element of the list and executes it using exec-instruction!.  This makes implementing all arithmetic operations easier.  exec-instruction! is just a big switch statement to execute arbitrary functions linked to a symbol.

(define (exec-instruction! env instruction . arg)
 (case instruction
   [(+)    (instruction/arithmetic env instruction)]
   [(-)    (instruction/arithmetic env instruction)]
   [(*)    (instruction/arithmetic env instruction)]
   [(/)    (instruction/arithmetic env instruction)]
   [(push) (instruction/push env (car arg))]
   [(pop)  (instruction/pop env)]
   [else 'error]))

There are probably is a more dynamic way of doing this.  For now this works out really well and it’s easy to tell what is considered a native operation and what isn’t.  I don’t expect this to grow extremely large in the future since there are only a few more operations that will be added.

vm-eval had to be modified as well to execute arbitrary instructions.  Here is the new code.

(define (vm-eval input env)
 (cond
   ; Semi-hack used to exit the repl
   [(and (symbol? input)
         (equal? input 'quit)) (values 'quit env)]
   [(self-evaulating? input) (values input env)]
   [(symbol? input)  (values (env/get-def env input) env)]

   ; Process define forms
   [(and (list? input)
         (define-form? input))
    (define-form input env)]

   ; Process execution of lists
   [(and (list? input)
         (instruction? (car input)))
    (values (exec-form input env) env)]
   [else 'error]))

Here is a test run of the arithmetic:

#;1> (repl)
-: (+ 1 2)
3
-: (- 4 3)
1
-: (* 5 (+ 1 2))
15
-: (define a 5)
(define a 5)
-: (define x 3)
(define x 3)
-: (/ a x)
1.66666666666667
-: quit
quit

Additional Resources

I’ve had a few people tell me that this project has been useful to them.  Here are some additional resources that might be useful if you plan on implementing your own interpreter.

1. Lispy in Scheme – Another project to implement a Lisp-like language in Scheme.
2. Scheme From Scratch – Series of articles on writing a Scheme interpreter in C.
3. Lua Source Code – Lua isn’t Scheme, but the Lua VM is small and clean.  Poking around this code gave me a lot of insight into how virtual machines operate.
4. Wikipedia Article on Scheme – This link specifically goes to the part of the article about Scheme minimalism.  It’s useful because it outlines exactly what you need to implement a standard Scheme.  It’s pretty amazing that so little needs to be implemented to get so much.

As always, you can see the code for this part of Scheme In Scheme on my Git Hub account at Part 3.

Simple yet Complex

Tic Tac Toe is extremely simple.  Everyone knows how to play it.  This makes it an ideal candidate when learning a new language.  It’s simple enough that it can be implemented in a weekend.  It doesn’t require many complex libraries since text output and input is sufficient to play the game.

The game is open ended enough that it can be written in a way that allows someone to learn specific aspects of a language.  Want to build server-ware with the language?  Write a client-server based Tic Tac Toe game.  The goal is to build GUI applications?  Implement the game with GUI elements and graphics.

Requires both Behavior and State

Tic Tac Toe is good because it involves non-trivial state and behavior.  At any given point in the game, you have to track the state of the board.  This seems simple but because it involves 2 dimensional space it’s complex enough that more complex data structures can be used.  A dictionary that maps positions to pieces; a multi-dimensional array; or just a list of position and piece pairs are all different ways the board state can be modeled.

The behavior is simple enough to be easily written but complex enough to require more than one if statement.  Try thinking about checking a Tic Tac Toe board for a win.  It can be a horizontal or a vertical win.  But it can also be a diagonal win.  There are games where there is no win but the board is full.  All of these conditions must be considered after each piece placement.

Beyond Tic Tac Toe

Got a simple Tic Tac Toe but want to add more features?  Want something harder to tackle?

In college for a Java project I had to write a 4x4x4 Tic Tac Toe game.  It’s a 3 dimensional board with 4 squares in each dimension (for a total of 64 squares).  It plays just like standard Tic Tac Toe but 4 in a row is required to win.  Now there are multiple diagonals and more complex rules.  Regular Tic Tac Toe doesn’t get beyond a simple AI whereas 4x4x4 requires much more complexity.

If that’s too much you can always just increase the number of squares in the 2 dimensional space.  Use a 4×4 or 5×5 game board instead.  Let the player enter an arbitrary number of squares.

Here are some additional ideas.

1. Add an Undo/Redo
2. Allow the player to pick different difficulties.
3. Keep score of the Wins, Loses and Ties.
4. Allow the player to pick different pieces for their moves.
5. Allow saving and loading games.
6. 2 player mode.

I used this technique when learning Android programming.  If you want to see an example of Tic Tac Toe you can look at the Tic Tac Toe in my GitHub account.  Note that it isn’t the best code in the world!

Since we have a nice repl at our disposal we can start focusing on defining an environment using the define form.  There is two different ways of calling define:

(define symbol-name value...)
(define (symbol-name params...) values)

The first define form simply binds a symbol to evaluate to a value.  The second define form binds a lambda to a symbol, so you can do the standard function call.  I’m just going to tackle the first define form for now; it’s a lot more involved than it looks.

Scheme Environment

To have defines in an environment we must first create an environment.

(define (make-env)
 '((defs ((placeholder 123)))))

The environment right now is just a list of defines.  This list consists of only a place holder right now.  The place holder allows us to remove a lot of code that would usually be required to special case defs being keyed to an empty list.  Since eventually top level bindings such as arithmetic operations (+, -, /, *) and list manipulation (car, cons, cdr, …) will exist in a newly created environment this is normal.

Now that we have the environment, we need some ways to manipulate the environment.  Specially, we need functions to get a define from the environment and add a define to the environment.

;; Adds a new symbol to the environment with the given form.
(define (env-add-def env symbol form)
 (replace env 'defs
          (append
           (cdr (assq 'defs env))
           (list (list symbol form)))))

;; Gets the define for symbol in environment env
(define (env-get-def env symbol)
 (let ((form (assq symbol (cadr (assq 'defs env)))))
   (if form
       (cadr form)
       'error)))

All these do is use a liberal amount of assq‘s to treat the environment like a dictionary.  The symbol defs gets us a dictionary of the defines within the environment.  Each entry in that dictionary uses the symbol name as the dictionary key and the form or evaluated value as the dictionary value.

I’m using the symbol error to signify undefined values.  This is a little messy right now but it works for the time being.  Refactoring will come later.

Repl Evolution

The repl has to be changed to accommodate the new environment.  Specifically, we need to keep the state around from call to call.  Since we’re treating the environment as an immutable data structure we’ll have to capture outputs of vm-eval.

(define (repl)
 (define (repl-inner env)
   (display prompt)
   (let-values (((result new-env) (vm-eval (read-input) env)))
     (print-obj result)
     (repl-inner new-env)))
 (repl-inner (make-env)))

Now vm-eval is returning a result object (from the evaluation) and a new environment (since evaluations may result in modifying the environment).  repl-inner is used to recursively call into our repl and it persists the environments state.  vm-eval and print-object must be changed to use the environment.

;; Checks a list to see if the first symbol is define
(define (define-form? input)
 (and (not (null? input))
      (equal? (car input) (string->symbol "define"))
      (>= (length input) 2)))

;; Takes in a define and adds it to the environment
(define (define-form input env)
 (let ((form (if (> (length input) 2)
                 (vm-eval (caddr input) env)
                 '())))

       (if (not (equal? form 'error))
           (values input (env-add-def env (cadr input) form))
           (values 'error env))))

;; Evaluates an input string
(define (vm-eval input env)
 (cond
  [(string? input)  (values input env)]
  [(number? input)  (values input env)]
  [(null? input)    (values input env)]
  [(char? input)    (values input env)]
  [(boolean? input) (values input env)]
  [(symbol? input)  (values (env-get-def env input) env)]

  ; Process define forms
  [(and (list? input)
        (define-form? input))
    (define-form input env)]
  [else 'error]))

;; Prints objects out to stdout
(define (print-obj obj)
 (cond
  [(string? obj) (display
                 (string-append doublequote-char obj doublequote-char))]
  [(char? obj)   (display (string-append "#\\" (string obj)))]
  [(equal? obj 'error)  (display "ERROR!")]
  [else          (display obj)])
                 (newline))

Now we have a couple new functions that will let us work with defines easily.  They’re pretty self-explanatory.  The real interesting thing is the way the define is parsed and processed.  Since the third element in the define can itself be something already in the environment it gets passed through vm-eval.  This allows us to follow (define test1 123) with (define test2 test1) and have test2 evaluate to 123.

vm-eval has now changed to handle symbols.  It looks them up in the environment and displays their values if found.  If not our old friend error shows up and print-object handles that by printing and error string.

Let us test it out!

#;1> ,l repl
; loading repl.scm ...
; loading env.scm ...
; loading library srfi-1 ...
#;1> (repl)
-: "123"
"123"
-: 1234
1234
-: (define test 123)
(define test 123)
-: test         
123
-: (define abc test)
(define abc test)
-: abc
123

I successfully define test and get 123 back when evaluating it.  Then I define abc to be test and get 123 back when evaluating abc.

The code for this iteration of Scheme in Scheme can be found at GitHub.

I thought many of the same things.  The idea did seem crazy at first, but there are quite a few good reasons to write a Scheme interpreter in Scheme.

1. You already have a perfectly good Scheme implementation at your fingertips.  This means it’s less inventing and more replacing parts of the language.
2. Just replacing pieces creates a quicker feedback loop.  You don’t have to spend days writing code to see results.
3. Scheme is a language written to process lists.  Scheme is written in lists.  That makes it a natural choice for this exercise.
4. Writing a Scheme interpreter in a lower level or more verbose language, such as C or C++, is time consuming.
5. It is more of a learning exercise.  Using Scheme keeps it simple.
6. If you want to take it to the next level, you can always translate your Scheme code into a statically typed language for awesomeness.

Another question is why Scheme and not another language?  Scheme is an extremely basic and simple language.  Since it’s simple there is less to implement and therefore our goal is easier to achieve.  According to the Wikipedia Article on Scheme you don’t need to implement a lot of things underneath the hood to get a basic but complete Scheme-like language.  Since it has a powerful macro system, you can write many of the Scheme forms in Scheme itself.  There are a few other languages that writing an interpreter for Scheme can be done in, such as Common Lisp, Clojure, Ruby, Python, and so forth.  The further you get from a Lisp language though the more code you are going to write.

Starting With a Repl

The first thing to hack together is a simple Read Evaluate Print Loop or Repl.  A Repl gives instant gratification – you type something in and the interpreter evaluates it.  Here is an extremely naïve and simple version of what we’ll need.

(define (repl)
  (read-input)
  (vm-eval)
  (print-obj)
  (repl))

This is pretty straight forward.  It reads the input, evaluates it, and prints the result.  To evaluate input and print a result the Repl needs to capture information.  Here is version 1 of the Repl algorithm.

(define (repl)
 (display prompt)
 (print-obj (vm-eval (read-input)))
 (repl))

This captures input from the user, evaluates it and prints it out.  Lather, rinse, repeat!  It’s also a lot more functional than our previous example.

The Bits and Pieces

Now to move on to the actual read, print and evaluate pieces.  Right now the read is extremely simple.

(define (read-input)
  (read))

This code is using the underlying Scheme system.  Second function and I’m already cheating.  (read) will not only read input from the user, but it also parses it and returns an appropriate Scheme value. If I enter a number then (read) returns a Scheme number; (number? (read)) evaluates to #t.  This is fine for now since parsing is complex.  I don’t want to get into having to parse input at this point.

Here is the evaluation function.

(define (vm-eval input)
  (cond
   [(string? input)  input]
   [(number? input)  input]
   [(null? input)    input]
   [(char? input)    input]
   [(boolean? input) input]
   [else "Error!"]))

This isn’t much right now.  It just patriots the input depending on the input’s type. Given a number, string, character etcetera it will return that same object. Symbols will drop down to the else cause.  That’s fine for now.  We can work on evaluating symbols in the future.  It’s called (vm-eval) because (eval) is already claimed by the underlying Scheme system.

After evaluating we need to prints results.

(define (print-obj obj)
  (cond
   [(string? obj) (display
                   (string-append doublequote-char obj doublequote-char))]
   [(char? obj)   (display (string-append "#\\" (string obj)))]
   [else          (display obj)])
  (newline))

This has some simple beautification functionality.  It will surround strings with double-quotes before printing.  It will also print characters as they are entered in Scheme, preceded by #\.  Note that doublequote-char is just a constant for ” in string form.

Trying it out, it will print all the simple types back when reading them in. If it encounters a symbol, a single quote, or anything with parenthesis it chokes and prints “Error!”.

> (load "repl.scm")
"/home/kris/projects/lisp/repl.scm"
> (repl)
-: 1234
1234
-: 3-5i
3-5i
-: .1234123e12
1.234123e11
-: "abc 123"
"abc 123"
-: #\c
#\c
-: #t
#t
-: nil
"Error!"
-:

And that’s how you write an extremely simple Repl in Scheme.  The code can be found at GitHub tagged as Part.1.