Writing A Compiler In Go

Thorsten Ball

Writing A Compiler In Go

Acknowledgments

Introduction

Evolving Monkey

Use This Book

Compilers & Virtual Machines

Compilers

Virtual and Real Machines

What We’re Going to Do, or: the Duality of VM and Compiler

Hello Bytecode!

First Instructions

Adding on the Stack

Hooking up the REPL

Compiling Expressions

Cleaning Up the Stack

Infix Expressions

Booleans

Comparison Operators

Prefix Expressions

Conditionals

Jumps

Compiling Conditionals

Executing Jumps

Welcome Back, Null!

Keeping Track of Names

The Plan

Compiling Bindings

Adding Globals to the VM

String, Array and Hash

String

Array

Hash

Adding the index operator

Functions

Dipping Our Toes: a Simple Function

Local Bindings

Arguments

Built-in Functions

Making the Change Easy

Making the Change: the Plan

A New Scope for Built-in Functions

Executing built-in functions

Closures

The Problem

The Plan

Everything’s a closure

Compiling and resolving free variables

Creating real closures at run time

Taking Time

Resources

Feedback

Changelog

Cover

Table of contents

Acknowledgments

I started writing this book one month after my daughter was born and finished shortly after her first birthday. Or, in other words: this book wouldn’t exist without the help of my wife. While our baby grew into the wonderful girl she is now and rightfully demanded the attention she deserves, my wife always created time and room for me to write. I couldn’t have written this book without her steady support and unwavering faith in me. Thank you!

Thanks to Christian for supporting me from the start again with an open ear and encouragement. Thanks to Ricardo for providing invaluable, in-depth feedback and expertise. Thanks to Yoji for his diligence and attention to detail. Thanks to all the other beta-readers for helping to make this book better!

Introduction

It might not be the most polite thing to do, but let’s start with a lie: the prequel to this book, Writing An Interpreter In Go, was much more successful than I ever imagined it would be. Yes, that’s a lie. Of course, I imagined its success. The name on the top of bestseller lists, me showered with praise and admiration, invited to fancy events, strangers walking up to me in the street, wanting to get their copy signed – who wouldn’t imagine that when writing a book about a programming language called Monkey? But, now, in all seriousness, the truth: I really didn’t expect the book to be as successful as it was.

Sure, I had a feeling that some people might enjoy it. Mainly because it’s the book I myself wanted to read, but couldn’t find. And on my fruitless search I saw other people looking for the exact same thing: a book about interpreters that is easy to understand, doesn’t take shortcuts and puts runnable and tested code front and center. If I could write a book like that, I thought, there might just be a chance that others would enjoy it, too.

But enough about my imagination, here’s what actually happened: readers really enjoyed what I wrote. They not only bought and read the book, but sent me emails to thank me for writing it. They wrote blog posts about how much they enjoyed it. They shared it on social networks and upvoted it. They played around with the code, tweaked it, extended it and shared it on GitHub. They even helped to fix errors in it. Imagine that! They sent me fixes for my mistakes, all the while saying sorry for finding them. Apparently, they couldn’t imagine how thankful I was for every suggestion and correction.

Then, after reading one email in which a reader asked for more, something in me clicked. What lived in the back of my mind as an idea turned into an obligation: I have to write the second part. Note that I didn’t just write “a second part”, but “the second part”. That’s because the first book was born out of a compromise.

When I set out to write Writing An Interpreter In Go the idea was not to follow it up with a sequel, but to only write a single book. That changed, though, when I realized that the final book would be too long. I never wanted to write something that scares people off with its size. And even if I did, completing the book would probably take so long that I would have most likely given up long before.

That led me to a compromise. Instead of writing about building a tree-walking interpreter and turning it into a virtual machine, I would only write about the tree-walking part. That turned into Writing An Interpreter In Go and what you’re reading now is the sequel I have always wanted to write.

But what exactly does sequel mean here? By now you know that this book doesn’t start with “Decades after the events in the first book, in another galaxy, where the name Monkey has no meaning…” No, this book is meant to seamlessly connect to its predecessor. It’s the same approach, the same programming language, the same tools and the codebase that we left at the end of the first book.

The idea is simple: we pick up where we left off and continue our work on Monkey. This is not only a successor to the previous book, but also a sequel to Monkey, the next step in its evolution. Before we can see what that looks like, though, we need look back, to refresh our memory of Monkey.

Evolving Monkey

The Past and Present

In Writing An Interpreter In Go we built an interpreter for the programming language Monkey. Monkey was invented with one purpose in mind: to be built from scratch in Writing An Interpreter In Go and by its readers. Its only official implementation is contained in Writing An Interpreter In Go, although many unofficial ones, built by readers in a variety of languages, are floating around the internet.

In case you forgot what Monkey looks like, here is a small snippet that tries to cram as much of Monkey’s features into as few lines as possible:

let name = "Monkey";
let age = 1;
let inspirations = ["Scheme", "Lisp", "JavaScript", "Clojure"];
let book = {
  "title": "Writing A Compiler In Go",
  "author": "Thorsten Ball",
  "prequel": "Writing An Interpreter In Go"
};

let printBookName = fn(book) {
    let title = book["title"];
    let author = book["author"];
    puts(author + " - " + title);
};

printBookName(book);
// => prints: "Thorsten Ball - Writing A Compiler In Go"

let fibonacci = fn(x) {
  if (x == 0) {
    0
  } else {
    if (x == 1) {
      return 1;
    } else {
      fibonacci(x - 1) + fibonacci(x - 2);
    }
  }
};

let map = fn(arr, f) {
  let iter = fn(arr, accumulated) {
    if (len(arr) == 0) {
      accumulated
    } else {
      iter(rest(arr), push(accumulated, f(first(arr))));
    }
  };

  iter(arr, []);
};

let numbers = [1, 1 + 1, 4 - 1, 2 * 2, 2 + 3, 12 / 2];
map(numbers, fibonacci);
// => returns: [1, 1, 2, 3, 5, 8]

Translated into a list of features, we can say that Monkey supports:

integers

booleans

strings

arrays

hashes

prefix-, infix- and index operators

conditionals

global and local bindings

first-class functions

return statements

closures

Quite a list, huh? And we built all of these into our Monkey interpreter ourselves and – most importantly! – we built them from scratch, without the use of any third-party tools or libraries.

We started out by building the lexer that turns strings entered into the REPL into tokens. The lexer is defined in the lexer package and the tokens it generates can be found in the token package.

After that, we built the parser, a top-down recursive-descent parser (often called a Pratt parser) that turns the tokens into an abstract syntax tree, which is abbreviated to AST. The nodes of the AST are defined in the ast package and the parser itself can be found in the parser package.

After it went through the parser, a Monkey program is then represented in memory as a tree and the next step is to evaluate it. In order to do that we built an evaluator. That’s another name for a function called Eval, defined in the evaluator package. Eval recursively walks down the AST and evaluates it, using the object system we defined in the object package to produce values. It would, for example, turn an AST node representing 1 + 2 into an object.Integer{Value: 3}. With that, the life cycle of Monkey code would be complete and the result printed to the REPL.

This chain of transformations – from strings to tokens, from tokens to a tree and from a tree to object.Object – is visible from start to end in the main loop of the Monkey REPL we built:

// repl/repl.go

package repl

func Start(in io.Reader, out io.Writer) {
    scanner := bufio.NewScanner(in)
    env := object.NewEnvironment()

    for {
        fmt.Printf(PROMPT)
        scanned := scanner.Scan()
        if !scanned {
            return
        }

        line := scanner.Text()
        l := lexer.New(line)
        p := parser.New(l)

        program := p.ParseProgram()
        if len(p.Errors()) != 0 {
            printParserErrors(out, p.Errors())
            continue
        }

        evaluated := evaluator.Eval(program, env)
        if evaluated != nil {
            io.WriteString(out, evaluated.Inspect())
            io.WriteString(out, "\n")
        }
    }
}

That’s where we left Monkey at the end of the previous book.

And then, half a year later, the The Lost Chapter: A Macro System For Monkey resurfaced and told readers how to get Monkey to program itself with macros. In this book, though, The Lost Chapter and its macro system won’t make an appearance. In fact, it’s as if the The Lost Chapter was never found and we’re back at the end of Writing An Interpreter In Go. That’s good, though, because we did a great job implementing our interpreter.

Monkey worked exactly like we wanted it to and its implementation was easy to understand and to extend. So one question naturally arises at the beginning of this second book: why change any of it? Why not leave Monkey as is?

Because we’re here to learn and Monkey still has a lot to teach us. One of the goals of Writing An Interpreter In Go was to learn more about the implementation of the programming languages we’re working with on a daily basis. And we did. A lot of these “real world” languages did start out with implementations really similar to Monkey’s. And what we learned by building Monkey helps us to understand the fundamentals of their implementation and their origins.

But languages grow and mature. In the face of production workloads and an increased demand for performance and language features, the implementation and architecture of a language often change. One side effect of these changes is that the implementation loses its similarity to Monkey, which wasn’t built with performance and production usage in mind at all.

This gap between fully-grown languages and Monkey is one of the biggest drawbacks of our Monkey implementation: its architecture is as removed from the architecture of actual real-world languages as a soapbox car is from a Formula 1 car. It has four wheels and a seat, sure, it can help to learn the fundamentals of steering, yes, but the fact that it’s missing an engine is hard to ignore.

In this book we’re going to reduce this gap between Monkey and real languages. We’ll put something real under the hood of our Monkey soapbox car.

The Future

We’re going to turn our tree-walking and on-the-fly-evaluating interpreter into a bytecode compiler and a virtual machine that executes the bytecode.

That’s not only immensely fun to build but also one of the most common interpreter architectures out there. Ruby, Lua, Python, Perl, Guile, different JavaScript implementations and many more programming languages are built this way. Even the mighty Java Virtual Machine interprets bytecode. Bytecode compilers and virtual machines are everywhere – and for good reason.

Besides providing a new layer of abstraction – the bytecode that’s passed from the compiler to the virtual machine – that makes the system more modular, the main appeal of this architecture lies in its performance. Bytecode interpreters are fast.

Want numbers? At the end of this book we’ll have an implementation of Monkey that’s three times faster than its predecessor from the first book:

$ ./monkey-fibonacci -engine=eval
engine=eval, result=9227465, duration=27.204277379s
$ ./monkey-fibonacci -engine=vm
engine=vm, result=9227465, duration=8.876222455s

Yes, three times faster – without low-level tweaking or extensive optimizations. Sound good? Ready to write some code? Perfect. Let’s get the practicalities out of the way and we can start.

Use This Book

Like the first one, this book comes with only a tiny number of instructions: you best read it from start to finish and you’ll get the most out of it if you follow along by reading, typing out and playing around with the presented code. That’s it.

These books are practical books. They are about writing code and building something. If you want to immerse yourself in the theory of programming-language construction you’re better off by choosing one of the canonical textbooks. That’s not to say that you won’t learn anything here, no. I’ll try my best to guide you along and explain what everything is and how the pieces fit together. It just won’t be as academic as a textbook on compilers. But that’s exactly how I intend it to be.

This book, just like its predecessor, comes with a folder called code. If your copy of the book came without it, you can download it here:

https://compilerbook.com/wacig_code_1.0.zip

In this folder you’ll find subfolders for each of the chapters in which we write code. Each contains the codebase as it stands at the end of the corresponding chapter, which can be helpful if you get stuck while following along.

The subfolder 00, however, is special and also what differentiates this book from the first one: we don’t start with a clean slate, but build upon the codebase of the previous book. It doesn’t correspond to a chapter of this book, but contains the complete codebase as we left it at the end of the previous one. That also means it doesn’t include the macro system from The Lost Chapter, but if you’re a fan of the macros, it shouldn’t be too hard to keep the macro-expansion step around.

The code contained in these folders is the focus of this book. I try to show most of it, but sometimes I’ll only refer to something located in the codebase, without actually showing it. Why? Most of the time because it’s a repetition of something we’ve seen before and showing it would take up too much space.

So much about the content of the code folder. Now, let’s talk about tools because I have some good news: you don’t need many. In fact, a text editor and an installation of the Go programming language should be enough. Which version of Go? At least Go 1.10, because that’s what I’m using at the time of writing and because we will use a tiny number of features that were only introduced in Go 1.8 and 1.9.

I also recommend using direnv to work with the code folder. direnv can change the environment of your shell according to an .envrc file. Whenever you cd into a folder, direnv checks whether the folder contains an .envrc file and executes it. Each subfolder in code contains such an .envrc file that sets the GOPATH correctly for this subfolder. That allows us to just cd into a subfolder and execute the code really easily.

And that’s all there is to say about the practicalities of this book. Read it, code along and, most importantly, have fun.

Compilers & Virtual Machines

For most programmers the word “compiler” has an intimidating ring to it. And even if you’re not intimidated by it, you can’t deny that compilers and what they do is surrounded by an air of mystery and amazement. They produce machine code seemingly nobody mortal can read or write. They do magic optimizations that somehow make code run faster. They can take a long time to run – minutes or even tens of minutes. If the rumours are true they sometimes even run for hours. If it takes that long, what they’re doing must be extraordinary.

Speaking of rumours: it’s said that compilers are incredibly huge and incredibly complex. In fact, they can often be found listed among the most complex software projects to ever exist – with the claims backed up by numbers. Here’s a taste: the LLVM & Clang projects currently consist of around 3 million lines of code. The GNU Compiler Collection, GCC, is even bigger. 15 million lines of code.

There are not a lot of people that look at these numbers, open their text editor and say “you know what? Let’s build one!” They certainly do not evoke the sense that one could write a compiler in an afternoon.

Virtual machines, too, are largely understood to be mystical creatures, roaming through the dark lower layers of software development, seldom seen in light and even less understood. They, too, attract their fair share of rumours and speculations. Some say that virtual machines have something to do with compilers. Others insist that their programming language is, in fact, such a virtual machine. Another group claims that virtual machines allow them to run an operating system inside another operating system.

It doesn’t help that all of it is true.

But here’s the thing. At their core, compilers and virtual machines are ideas – patterns – just like “interpreter” or “web server” are ideas that can have multiple implementations, ranging from tiny to massive. Being intimidated by them after looking at a project like GCC makes as much sense as giving up on building a website after looking at GitHub.

Sure, it’s not a small task to build a compiler for a virtual machine. But it’s also not as insurmountable as reputation suggests. And once we have a better understanding of these core ideas, of what a compiler and a virtual machine essentially are, you’ll see that you can, in fact, build a compiler in an afternoon.

The first step towards that is finding out what “compiling” means.

Compilers

If I’d ask you to name a compiler, you’d probably and without missing a beat would give me a name like GCC, or Clang, or the Go compiler. In any case, it would most certainly be a compiler for a programming language. Chances are that it’s a compiler that produces executables. I would, too, because that’s just what we associate with the word “compiler”.

But compilers come in all shapes and sizes and compile all kinds of things, not just programming languages, including regular expressions, database queries and even HTML templates. I bet you use one or two compilers every day without even realizing it. That’s because the definition of “compiler” itself is actually quite loose, much more so than one would expect. Here is Wikipedia’s version:

A compiler is computer software that transforms computer code written in one programming language (the source language) into another computer language (the target language). Compilers are a type of translator that support digital devices, primarily computers. The name compiler is primarily used for programs that translate source code from a high-level programming language to a lower level language (e.g., assembly language, object code, or machine code) to create an executable program.

Compilers are translators. That’s vague. And a compiler that translates high-level languages to produce executables is just one special type of compiler? Sounds counter-intuitive, doesn’t it? You’d think that producing executables is just what a compiler does: that’s what GCC does, that’s what Clang does, that’s what the Go compiler does. Shouldn’t that be the first line of the definition? How can this be non-essential?

The solution to this riddle is another one: what’s an executable if not source code in a language the computer can natively understand? Hence, “compiling to native code” is the same as compiling to machine code. Yes, really, producing executables is just one variation of “translating source code”.

You see, compilers are fundamentally about translation, because translation is how they implement a programming language.

Let’s make sense of that sentence by taking a step back here. Programming means giving instructions to a computer. We, the programmers, write these instructions in programming languages the computer can understand. There is no point in using any other language. Now, implementing a programming language means making the computer understand it. There are two ways to do that: either interpret the language for the computer on-the-fly or translate it into another language, one the computer already understands.

It’s exactly like we, as humans, can help a friend understand a language she doesn’t speak. We can either listen, translate in our head and repeat the translation to her, or we can write the translation down so she can read and understand it herself. We can either act as an interpreter or as a compiler.

This might sound like interpreters and compilers are opposites. But while their approach is different, they share a lot of things in their construction. They both have a frontend that reads in source code written in the source language and turns it into a data structure. In both, compiler and interpreter, this frontend is usually made up of a lexer and a parser that together generate a syntax tree. So here, in the front part, they have a lot of similarities. After that, when they both traverse the AST, that’s when their paths diverge.

Since we already built an interpreter we know what it does when traversing the AST: it evaluates it. That is, it executes the instructions encoded in the tree. If a node in the tree represents the source language’s statement puts("Hello World!"), then the interpreter would print “Hello World!” when evaluating the node.

A compiler, on the other hand, wouldn’t print anything. Instead, it would generate source code in another language, called the target language. The source code would contain the target language’s equivalent of the source language’s puts("Hello World!"). The resulting code could then be executed by the computer and "Hello World!" would appear on the screen.

This is where things get really interesting. In which target language does the compiler generate source code? Which language does the computer understand? And how does the compiler generate code in this language? As text, or in a binary format? In a file, or in memory? But much more importantly: what exactly does it generate in this target language? What if the target language doesn’t have an equivalent of puts? What should the compiler generate instead?

Generally speaking, we have to give the same answer to every one of these questions. Software development’s number one answer, the only hard, capital-T Truth in programming: “it depends.”

Sorry to let you down there, but the answers to these questions depend on a multitude of variables and requirements: the source language, the architecture of the machine that executes the target language, how the output is going to be used (is it executed directly? compiled again? interpreted?), how fast the output needs to run, how fast the compiler itself needs to run, how big the generated source code can be, how much memory the compiler is allowed to use, how much memory the resulting program can use, and how…

The variety between compilers is so high that we can’t make a lot of universal statements about their architecture. That being said, we can ignore the details for a minute now and sketch out the architecture of something like the archetype of a compiler:

This shows the life cycle of source code that’s being translated to machine code. Here’s what happens.

First, the source code is tokenized and parsed by the lexer and the parser. We’re familiar with this part from our interpreter. It’s called the frontend. The source code is turned from text into an AST.

After that a component called the “optimizer” (or sometimes also called “compiler” – I know, I know, …) might translate the AST into another internal representation (IR). This additional IR might just be another syntax tree, or maybe a binary format, or even a textual format. The reasons for this additional translation into another IR are manifold, but the major one is that the IR might lend itself better to optimizations and translation into the target language than the AST would.

This new IR then goes through an optimization phase: dead code is eliminated, simple arithmetic is pre-calculated, code that doesn’t need to be in the body of a loop is moved out of it, … A ton of possible optimizations exists.

Finally, the code generator, also called the backend, generates the code in the target language. This is where the compilation happens. Here’s where the code hits the file system, so to say. After that, we can execute the result and see the computer perform what we instructed it to in the original source code.

This is how the simplest compilers work. And even here a thousand variations are possible. For example, the optimizer could do multiple “passes” over the IR, meaning that it traverses the IR multiple times and each time does a different optimization: removing dead code in one pass, inlining function calls in another one, for example. Or maybe the compiler doesn’t do optimizations on the IR at all, but only on the source code in the target language. Or only on the AST, or on both. Or it doesn’t do any optimizations ever. Or maybe it doesn’t even have another IR besides the AST. And maybe it doesn’t output machine code, but assembly language, or another high-level language. Or it has multiple backends that can generate machine code for multiple architectures. It all depends on the specific use case.

And then again, a compiler doesn’t even have to be a tool you run on the command line, that reads in source code and outputs code in a file, like gcc or go. It can just as well be a single function that takes in an AST and returns a string. That’s also a compiler. A compiler can be written in a few hundred lines of code or have millions of them.

But underlying all of these lines of code is the fundamental idea of translation. Compilers take in source code in one language and generate source code in another one. The rest – again – “depends”, with the majority on the target language. What the target language is capable of and by which machine it can be executed shapes the design of a compiler like nothing else.

Now, what if we didn’t have to choose a target language, but could invent our own? And what if we don’t leave it at that and also dream up the machine that executes this language?

Virtual and Real Machines

You probably associate “virtual machine” with software like VMWare or Virtualbox. These are programs that emulate a computer, including a disk drive, hard drive, graphics card, etc. They allow you to, for example, run a different operating system inside this emulated computer. Yes, these are virtual machines. But that’s not what we’re here to talk about. That’s the other type of virtual machine.

What we are going to talk about (and later build) are virtual machines that are used to implement programming languages. Sometimes they consist of just a few functions, other times they make up a few modules and on occasion they’re a collection of classes and objects. It’s hard to pin their shape down. But that doesn’t matter. What’s important is this: they don’t emulate an existing machine. They are the machine.

The “virtual” is due to the fact they only exist in software, not in hardware, and are thus purely abstract constructs. The “machine” describes their behaviour. These software constructs act like a machine. And not just any machine, no. They mimic the behaviour of their hardware equivalent: computers.

That means, in order to understand and build a virtual machine, we need to learn how a real machine works.

Real Machines

“So, how does a computer work?”

What might sound like an intimidating question can actually be answered in five minutes and with a piece of paper. I don’t know how fast you can read and I’m certain I can’t show you what I draw on a scrap of paper, but let me try anyway.

Nearly every computer in your life is built according to the Von Neumann architecture, which describes a way to build a fully-functioning computer with a surprisingly tiny number of parts.

In Von Neumann’s model a computer has two central parts: a processing unit, which contains an arithmetic logic unit (ALU) and multiple processor registers, and a control unit with an instruction register and a program counter. Together they’re called the central processing unit, often shortened to CPU. Besides that, the computer also contains memory (RAM), mass storage (think: hard drive) and input/output devices (keyboard and display).

CPU, memory, mass storage and I/O. Here’s a rough sketch of such a computer:

As soon as the computer is turned on, the CPU:

Fetches an instruction from memory. The program counter tells the CPU where in memory it can find the next instruction.

Decodes the instruction. To identify which operation should be executed.

Executes the instruction. This can mean either modifying the contents of its registers, or transferring data from the registers to memory, or moving data around in memory, or generating output, or reading input…

… and then goto 1 again.

These three steps are called the fetch-decode-execute cycle, or instruction cycle. Yes, that’s the cycle known from sentences like “the clock speed of a computer is expressed in cycles per second, e.g. 500 MHz” or “we’re wasting CPU cycles here”.

That was a brief and easy to understand description of how a computer works. But we can make it even easier for us. In this book we don’t care about mass storage components and only tangentially about the I/O mechanisms. What we’re interested in is the interplay between CPU and memory. That means we can make that our focus and safely ignore hard drives and displays.

We start our investigation with this question: how does the CPU address different parts of memory? Or, in other words: how does the CPU know where to store and retrieve things that are located in memory?

We’re given a first hint by how the CPU fetches instructions. The program counter, a part of the CPU, keeps track of where to fetch the next instruction. And “counter” is to be taken quite literally here: the computer simply uses numbers to address different parts of memory. Yes, numbers.

At this point I’m tempted to write “just think of memory as a huge array”, but I’m scared of someone hitting me over the head with a heavy, leather-bound tome called “Things about memory that are absolutely and without any doubt not like an array, you doofus”, so I won’t. But, yes, just like we, as programmers, use numbers as indexes to access single elements in an array, the CPU uses numbers as addresses when accessing data in memory.

Instead of “array elements” computer memory is segmented into “words”. Now what’s a “word”? It’s the smallest addressable region of memory. It’s the base unit when accessing memory. The size of a word varies and depends on the CPU type among other things. In the computers you and I use, however, 32 and 64 bits word sizes are the standard.

Let’s say we have a fictional computer with a word size of 8 bits and 13 bytes of memory. One word in memory can hold one ASCII character and if we store the string Hello, World! to memory it looks like this:

The letter “H” has the memory address 0, “e” has 1, the first “l” has 2, “W” has 7 and so on. We could access every single letter of the string Hello, World! by using the memory addresses 0 to 12. “Hey CPU, fetch the word at memory address 4” would result in the CPU fetching the letter “o”. Straightforward, right? I know what you’re thinking right now and, yes, if we take such a number – a memory address – and save it to another place in memory, we create a pointer.

That’s the basic idea behind addressing data in memory and how the CPU knows where to fetch and store data. As always, though, the real world is a mess.

As I already mentioned, the size of a word differs between different computers. Sometimes it’s 8 bits, sometimes 16, 24, 32, or 64 bits. Sometimes the word size used by the CPU is independent of the address size. And if that’s not enough to deal with: some computers do something entirely different and use byte-addressing instead of the just described word-addressing.

And if you’re using word-addressing and want to address a single byte (which is not that uncommon) you not only have to deal with different word sizes but also work with offsets. That in turn is expensive and has to be optimized.

On top of that: the idea that we can simply tell the CPU where to store and retrieve data in memory is something like a fairytale. It’s correct on a conceptual level and helpful when learning, but memory access today is abstracted away and sits behind layers and layers of security and performance optimizations. Memory is not the wild west anymore – we can’t just go around and access any memory location we want. Security rules and a mechanism called virtual memory try their best to stop that from happening.

Let me stop right here, though, before we take a huge detour and end up talking about the inner workings of virtual memory. That’s not why we’re here. What you can take from this excursion is that there’s more to memory access today than passing a number to the CPU. Not only are there security rules in place, but in the last few decades of computing emerged a set of less strict conventions around the use of memory.

One novel aspect of the Von Neumann architecture was that a computer’s memory contains not only data, but also programs, which are the CPU instructions that make up a program. To our programmer ears the idea of mixing data and code sounds like a recipe for tears. And to the ears of programmers a few generations ago, it probably sounded like that, too. Because what they did was to establish conventions around the use of memory that stopped that from happening.

While programs are stored in the same memory as any other data, they’re most often not stored in the same locations. Specific areas of memory are used to store specific things. That’s not only by convention, but also dictated by the operating system, the CPU and the rest of the computer architecture.

“Dumb” data, as in “the contents of a text file” or “the response of a HTTP request”, goes in one region of memory. The instructions that make up a program are stored and accessed in another region, where the CPU can easily fetch them. Another region holds the static data that’s used by a program and yet another region is empty and uninitialized, but reserved so that it can be used by a program once it’s running. The instructions belonging to the operating system kernel have their own special region in memory.

By the way: while programs and “dumb data” may reside in different memory locations, again, the important thing here is that they are both stored in the same memory. Saying “data and programs are both stored in memory” makes it sound as if they’re distinct, when in fact programs – made up of instructions – are just data too. Instructions only become instructions once the CPU fetches them from memory, decodes them, and finds out that they are, in fact, proper instructions and then executes them. If the CPU attempts to decode data that’s not a valid instruction, well, then the consequences will depend on how the CPU was designed. It could trigger an event and give the program a chance to recover or it could just stop.

For us, the most interesting thing about this is one particular memory region. It’s the memory region that holds the stack. Yes, the stack. Drum roll, fanfare, spot light, deep voice: The Stack. You might have heard of him. “Stack overflow” is probably his most famous work, followed by the less popular but equally respected “stack trace”.

So, what is it? It’s a region in memory where data is managed in a last-in-first-out (LIFO) manner. The data in it grows and shrinks, you push elements on to the stack and later pop them off. Just like the stack data structure. But unlike this generic data structure, the stack is focused on one purpose: it’s used to implement the call stack.

Yes, let’s stop right there; it is confusing. “Stack”, “the stack”, “stack data structure”, “call stack” – not really self-explanatory, is it? It doesn’t help that these names are often used interchangeably and thrown around and mixed together. But, thankfully, if we are careful with the names and pay attention to the “why” behind them, things become much clearer. So let’s try this again and do this step by step.

We have a memory region where the CPU accesses and stores data in a LIFO manner. It does this in order to implement a specialized version of a stack, called a call stack.

Why does it need a call stack? Because the CPU (or maybe: the programmer that wants the CPU to work as intended) needs to keep track of certain information in order to execute a program. The call stack helps with that. What information? First and foremost: which function is currently being executed and which instruction to execute next, once the current function is fully executed. This piece of information, which instruction to fetch after the current function, is called the return address. It’s where the CPU returns to after executing the current function. Without this the CPU would just increment the program counter and execute the instruction at the next higher address in memory. And that might be the absolute opposite of what should happen. Instructions are not laid out in memory in the order of execution, next to each other. Imagine what would happen if all the return statements in your Go code would vanish – that’s why the CPU needs to keep track of the return addresses. The call stack also helps to save execution-relevant data that’s local to functions: the arguments of the function call and the local variables only used in the function.

The return address, arguments and local variables – we could theoretically save this information in any other accessible part of memory, in any way we see fit. But, as it turns out, using a stack for this is perfect, because function calls are often nested. When entering a function, the data is pushed on to the stack. And while executing the current function, there is no need to access the local data of the outer, calling function. It’s enough to just access the top part of the stack, so to say. And once the current function returns, the local data is simply popped off – there’s no need for it anymore. That leaves us with the local data of the outer function on the top of the stack. Neat, right?

So that’s why we need the call stack and why it’s implemented as a stack. The only question now is: why the notorious name? Why is it the Stack and not just “well, I guess, yeah, it’s a stack, huh”? Because using this region of memory to implement a call stack is a convention so strongly held and widespread that by now it’s been cast into hardware. Certain CPUs support instructions solely for pushing and popping things on the stack. Every program that’s running on them makes use of this memory region in this way to implement this mechanism. There is no way around it. That’s why it’s the stack and not just any stack.

But keep in mind that the concept of a call stack is just that, a concept. It’s not bound to a specific implementation with a specific memory region. One could implement a call stack in any other place in memory – but without hardware or operating-system support then. In fact, that’s what we’re going to do. We’re going the implement our own call stack, a virtual call stack. But before we do that and switch over from the physical to the virtual, we need to look at one more concept to be fully prepared.

Now that you know how the stack works, you can imagine how often the CPU needs to access this region of memory while executing a program. It’s a lot. That means that the speed with which the CPU can access memory puts a limit on how fast it can execute programs. And while memory access is fast (a CPU can access main memory around a million times while you blink an eye) it’s not instant and still has a cost.

That’s why computers have another place where they can store data: processor registers. Registers are part of the CPU and accessing them is much faster than accessing the main memory. Naturally, one might ask, why not store everything in registers? Because there are only a few of them and they can’t hold as much data as main memory, typically only one word per register. A CPU of the x86-64 architecture, for example, has 16 general purpose registers, each holding 64 bits of data.

Registers are used to store data that’s small but frequently accessed. The memory address pointing to the top of the stack, for example, is commonly stored in a register – “commonly” being an understatement here. This specific usage of a register is so prevalent that most CPUs have a single, designated register just for storing this pointer, the so called stack pointer. The operands and the results of certain CPU instructions may also be stored in registers. If a CPU would need to add two numbers, both of them would be stored in registers and the result of the addition would end up in one too. That’s not all, though. There are many more use cases for registers. Here’s another one: if there’s a large piece of data frequently being accessed in a program it makes sense to store the address of it to a register so it can be accessed by the CPU really fast. The most important one for us, though, is the stack pointer. We’ll meet that one again soon.

And now… take a deep breath, lean back and relax, because: that’s it! Now that we’ve mentioned registers and know what a stack pointer is, we’ve covered everything we need to know about how real machines work. It’s time for us to go abstract, from the physical to the virtual.

What Is a Virtual Machine?

Let me get straight to the point: a virtual machine is a computer built with software. It’s a software entity that mimics how a computer works. I’ll admit, “software entity” doesn’t say much, but I used this phrase on purpose, to drive home one point: a virtual machine can be anything. A function, a struct, an object, a module, or even a whole program. What matters is what it does.

A virtual machine has a run loop that goes through the fetch-decode-execute cycle, just like a computer. It has a program counter; it fetches instructions; it decodes and executes them. It also has a stack, just like a real computer. Sometimes it has a call stack and sometimes even registers. All built in software.

Let me put code where my mouth is. Here is a virtual machine in 50 lines of JavaScript:

let virtualMachine = function(program) {
  let programCounter = 0;
  let stack = [];
  let stackPointer = 0;

  while (programCounter < program.length) {
    let currentInstruction = program[programCounter];

    switch (currentInstruction) {
      case PUSH:
        stack[stackPointer] = program[programCounter+1];
        stackPointer++;
        programCounter++;
        break;

      case ADD:
        right = stack[stackPointer-1]
        stackPointer--;
        left = stack[stackPointer-1]
        stackPointer--;

        stack[stackPointer] = left + right;
        stackPointer++;
        break;

      case MINUS:
        right = stack[stackPointer-1]
        stackPointer--;
        left = stack[stackPointer-1]
        stackPointer--;

        stack[stackPointer] = left - right;
        stackPointer++;
        break;
    }

    programCounter++;
  }

  console.log("stacktop: ", stack[stackPointer-1]);
}

It has a programCounter, it has a stack and a stackPointer. It has a run loop that executes as long as there are instructions in the program left to execute. It fetches the current instruction pointed to by the programCounter, decodes it and executes it. One iteration of this loop is one “cycle” of this virtual machine.

We can build a program for it and execute it like this:

let program = [
  PUSH, 3,
  PUSH, 4,
  ADD,
  PUSH, 5,
  MINUS
];

virtualMachine(program);

Can you already recognize the expression encoded in these instructions? It’s this:

(3 + 4) - 5

If you didn’t, that’s fine. You’ll be able to soon enough. The program is not that hard to read once you get used to doing arithmetic on a stack: first PUSH 3 and 4, then ADD the two topmost elements by popping them off the stack, adding them and pushing the result back on to the stack; finally, PUSH 5 to get the 5 on to the stack, then MINUS it with the second element from the top and leave the result on to the stack.

The result that ends up on top of the virtualMachine’s stack is printed once the machine finishes its run loop:

$ node virtual_machine.js
stacktop:  2

Boom.

Now, while that’s an actual working virtual machine, it’s also a rather simple one. As you can imagine, it’s not a showcase for what the whole spectrum of virtual-machine implementations is capable of and looks like. You can write a virtual machine in around 50 lines of code, like we just did, but also in 50 thousand lines or more. And going from here to there means making all kinds of choices regarding functionality and performance.

One of the most significant design decisions is whether the machine will be a stack machine or a register machine. It’s so significant that virtual machines are grouped based on this architectural choice, just like programming languages are sorted into “compiled” or “interpreted” buckets. The difference between a stack and a register machine is – put in the most simple terms – whether the machine uses a stack to do its computations (like we did in our example above) or registers (virtual ones!). The debate’s still open on what’s the better (read: faster) choice, since it’s mostly about trade-offs and which ones you’re prepared to make.

A stack machine and a matching compiler are said to be easier to build. The machine needs fewer parts and the instructions it executes are simpler, since they “only” make use of the stack. The problem is that you need to execute a lot of instructions, because you need to push and pop everything on and off the stack in order to get anything done. This puts a limit on how far one can take the cardinal rule of performance optimization: instead of trying to do a lot faster, first try to do less.

Building a register machine is more work, because the registers are an addition; it still has a stack. It’s not as prominent as in a stack machine, but it’s still necessary to implement a call stack. The advantage of a register machine is that its instructions can make use of the registers and are thus much denser compared to their stack counterparts. Instead of putting things on the stack, pushing and popping them to get them in the correct order, instructions can refer to the registers directly. Generally speaking, a program needs less instructions on a register machine than on a stack machine. That in turn results in better performance. But then again, writing the compiler that produces such dense instructions takes more effort. As I said: it’s about making trade-offs.

Besides this main architectural choice there’s a myriad of other decisions that go into building a virtual machine. There are the big questions regarding how to use memory and how to represent values internally (a topic which we already touched upon when we built the Monkey object system for our evaluator). But then there are seemingly tiny things that turn out to be endless, twisted rabbit holes you can get lost in. Let’s take a peek into one.

In our example above we used a switch statement do the dispatching in the run loop of our machine. Dispatching in a virtual machine means selecting an implementation for an instruction before executing it. In our switch statement the implementation of these instructions can be found right next to the case, inline. In case MINUS we subtract two values, in case ADD we add them, and so on. That’s dispatching. And while a switch statement looks like the obvious and only choice it’s far from that.

A switch statement is just the opening of the rabbit hole. And when you’re looking for maximum performance, you have to go in all the way. In there, you’ll find dispatching done with jump tables, with computed GOTO statements, with indirect and direct threaded code. Because, believe it or not, with a sufficient number of case branches (a few hundred or more) a switch might be the slowest of these solutions. The goal is to reduce the overhead of dispatching so much that from a performance perspective the fetch-decode part of a fetch-decode-execute cycle disappears. That should give you a taste of how deep the rabbit holes are.

We now have a rough overview of what a virtual machine is and what goes into building one. Don’t worry if you’re still missing some details. Since we’re going to build our own, we’re going to revisit a lot of the topics, ideas and, yes, the rabbit holes.

Why Build One?

Let’s put what we just learned into perspective. Why would you build a virtual machine to implement a programming language? I have to admit that this is the question I’ve carried around with me the longest. Even after I had built a few tiny virtual machines and had read through the source code of larger ones, I still asked myself: why?

When we implement a programming language we want it to be universal. It should be able to execute all possible programs and not just – as one example of many – functions we built into it. Universal computation is what we’re after and computers offer a solid model for it. If we construct a programming language based on that model, it’s going to have the same computational capabilities as the computer. It’s also one of the fastest ways to execute programs.

But if executing programs like a computer is the best and fastest way, why not, you know, just let the computer execute the programs? Portability. We could write a compiler for our programming language that allows us to execute the translated programs natively on a computer. These programs would be really fast. But we would also have to write a new compiler for every computer architecture we want to run our programs on. That’s a lot of work. Instead, we can translate our programs into instructions for a virtual machine. And the virtual machine itself runs on as many architectures as its implementation language. In the case of the Go programming language that’s pretty portable.

And there’s another reason for implementing a programming language with a virtual machine, which I think is the most fascinating one. It’s this: virtual machines are domain specific. That’s what makes them different from their non-virtual counterparts. Computers offer us a universal solution to all of our computational needs and are decidedly not domain specific. And that’s okay, that’s exactly what we need from a computer on which we want to run all sorts of programs. But what if we don’t need a machine to be that universal? What if we only need a subset of the features a computer has to offer to its programmers?

As programmers we know that no feature comes without cost. Increased complexity and degraded performance are just two of the prices we regularly pay for them. Computers today have a lot of features. A CPU of the x86-64 family supports between 900 and 4000 instructions, depending on how you count them. That includes at least six different ways to do a bitwise XOR on two operands. This is handy and what makes computers so versatile. But it’s not free. The versatility has a cost, just like every other feature. Think back to the switch statement in our tiny VM and take a second to ponder the performance implications of adding 3997 more case branches. If you’re not sure whether it will actually be slower, ask yourself how easy it is to maintain the code or to program for this VM. The good news is that we can turn this around. If we get rid of the features we don’t need, we can go faster. Less complexity, less maintenance, less mass. This is where virtual machines come into play.

A virtual machine is like a custom-built computer. It has custom parts and a custom machine language. It’s tuned to a single programming language. All the unneeded features are stripped off and what’s left is highly specialized. Since you don’t need to be as universal as a general-purpose computer, you can focus. You can concentrate your efforts into making this highly-specialized and custom-made machine work as best and go as fast as possible. This – the specialization, the domain specificity – is as important as getting rid of the unneeded mass.

Why this is so important becomes even clearer when we take a look at the instructions a virtual machine executes, something which we steered clear of up until now. Remember what we fed our tiny virtual machine? Here it is again:

let program = [
  PUSH, 3,
  PUSH, 4,
  ADD,
  PUSH, 5,
  MINUS
];

virtualMachine(program);

Now, what is that? What’s PUSH, what’s ADD, what’s MINUS? Here are their definitions:

const PUSH = 'PUSH';
const ADD = 'ADD';
const MINUS = 'MINUS';

PUSH, ADD and MINUS are just constants referring to strings. There’s no magic sauce. What a letdown. Boo! The silver lining of this revelation is that these definitions are as toy like and for illustration purposes only as the rest of the VM. They don’t answer the larger, more interesting question looming here: what exactly do virtual machines execute?

Bytecode

Virtual machines execute bytecode. Like the machine code that computers execute, bytecode is made up of instructions that tell the machine what to do. Push this, pop that, add these, call this function. It’s called bytecode because the opcodes contained in each instruction are one byte in size.

An “opcode” is the “operator” part of an instruction, sometimes also called “op”. The PUSH we’ve seen earlier is such an opcode, except that in our toy example it was a multi-byte string and not just one byte. In a proper implementation PUSH would just be the name that refers to an opcode, which itself is one byte wide. These names, like PUSH or POP, are called mnemonics. They help us programmers remember and talk about opcodes.

The operands (also called arguments or parameters) to these opcodes are also contained in the bytecode. They’re placed alongside each other, with the operands following the opcodes. The operands, though, aren’t necessarily one byte wide. For example, if an operand is an integer and greater than 255, it would take multiple bytes to represent it. Some opcodes have multiple operands, some just one and some don’t have any at all. Whether the bytecode is designed for a register or a stack machine has a huge influence here.

You can imagine bytecode as a sequence of opcodes and operands, laid out in memory next to each other:

This helps to illustrate the general idea, but bytecode is a binary format and not nearly as readable. Meaning that you can’t read it like a text file. The mnemonics, like PUSH, don’t show up in the actual bytecode. They are replaced by the opcodes they refer to, and those are just numbers – bytes. Which numbers exactly is up to the person defining the bytecode. The PUSH mnemonic might stand for the number 0 and POP might refer to the number 23.

The operands are also encoded and, again, it depends on its value into how many bytes. In case an operand needs multiple bytes to be accurately represented, the order in which it’s encoded plays a big role. There are two possible orders, called little endian and big endian. Little endian means that the least significant byte of the original data comes first and is stored in the lowest memory address. Big endian is the opposite: the most significant byte comes first.

If we, as bytecode designers, were to declare that PUSH refers to 1, ADD to 2 and integers are stored in big endian, we could encode the example from above and lay it out in memory like this:

What we just did – taking a human-readable representation of bytecode and turning it into binary data – is done by programs called assemblers. You’ve probably heard of them in the context of non-virtual machine code. Same thing here. Assembly language is the readable version of the bytecode, containing mnemonics and readable operands, and an assembler turns it into binary bytecode. The reverse, transforming the binary representation into a readable representation, is done by disassemblers.

Alright! So much for the purely technical aspects of bytecode. Any further exploration would get too specific too fast. Bytecode formats are just too diverse and specialized to allow us to make more general statements here. Just like the virtual machine that executes it, bytecode is created with a very specific goal in mind.

Bytecode is a domain-specific language for a domain-specific machine. It’s the bespoke machine language for the custom-built virtual machine. That’s where its power lies. Instead of being universal and supporting every conceivable use case, bytecode can be specialized. It only has to support the features needed by the source language, the language being compiled to bytecode.

And not only that. On top of only allowing a narrow set of instructions, it can contain domain-specific instructions that only make sense in the context of the domain-specific virtual machine. The bytecode for the Java Virtual Machine (JVM), for example, contains these instructions: invokeinterface to invoke an interface method, getstatic to get a static field of a class, new to create a new object of the specified class. Ruby’s bytecode has the putself instruction to load self on the stack, send to send a message to an object, putobject to load any object on to the stack. And Lua’s bytecode has dedicated instructions for accessing and manipulating tables and tuples. You won’t find any of that in the instruction set of a general-purpose x86-64 CPU.

This ability to specialize by using a custom bytecode format is one of the biggest reasons for building a virtual machine in the first place. Not only do compilation, maintenance and debugging get easier but the resulting code is also denser, because it takes less instructions to express something. That in turn makes the code faster to execute.

Now, if all that talk about custom virtual machines, tailor-made machine code, hand-built compilers didn’t wet your appetite, this is your last chance to turn around. We’re about to get our hands dirty.

What We’re Going to Do, or: the Duality of VM and Compiler

Building a virtual machine and a matching compiler requires us first to solve a variation of the chicken-and-egg problem: which one do we build first? The compiler, that outputs bytecode for a machine that doesn’t exist yet? Or the virtual machine, that no one produces any code for?

Here’s the answer I choose for this book: we are going to build both – at the same time.

Building one completely before the other (and it doesn’t matter which one) is frustrating. It’s hard to understand what’s going on and what is the purpose of what you’re doing. If you’re building the compiler and defining the bytecode first, it’s tough to make sense of why things are the way they are without knowing how the virtual machine will later execute it. Building the virtual machine before the compiler comes with its own challenges, because the bytecode needs to be defined first. That’s hard to do without closely looking at the source-language constructs the bytecode aims to represent, which means you’re going to spell out the compiler anyway.

Of course, if you already have experience with building one or the other, you know where you want to end up and can thus choose either option. For us, though, the goal is to learn how to build both from the ground up.

That’s why we’re going to start small. We’re going to build a tiny virtual machine that only supports a tiny number of instructions and a matching tiny compiler that only knows how to output these instructions. That allows us to immediately see why we’re building what we’re building and how all the pieces fit together. We’ll also have a running system right from the start. That gives us fast feedback cycles and allows us to tune, experiment and gradually build up our virtual machine and compiler. It also makes the whole journey a lot of fun.

Now you know what the plan is. And you also know enough about compilers and virtual machines that we don’t get lost along the way. Let’s get to it.

Hello Bytecode!

Our goal for this chapter is to compile and execute this Monkey expression:

1 + 2

That doesn’t sound like an ambitious goal, but in order to reach it, we will have to learn many new things and build up a lot of the infrastructure we’re going to use in the upcoming chapters. And by choosing the simple expression 1 + 2 we won’t be distracted by the Monkey code itself and how it should work. We can concentrate on our compiler and virtual machine.

At the end of this chapter we want to be able to:

take the Monkey expression 1 + 2

tokenize and parse it using our existing lexer, token and parser packages

take the resulting AST, whose nodes are defined in our ast package

pass it to the newly-built compiler, which compiles it to bytecode

take the bytecode and hand it over to the also newly-built virtual machine which will execute it

make sure that the virtual machine turned it into 3.

The 1 + 2 expression will travel through all the major parts of our new interpreter:

In terms of data structures, you can see that there will be quite a few transformations until we end up with the 3 as our result:

Since we’ll be using a lot of the packages we built in the previous book, we can already handle everything up to the AST. After that we’re entering unchartered territory. We need to define bytecode instructions, build a compiler and construct a virtual machine – just to turn 1 + 2 into 3. Sounds daunting? Worry not, we’ll do this step by step and build from the ground up, as always, and start with the bytecode.

First Instructions

As I mentioned in the previous chapter, the architecture of the virtual machine is the single-biggest influence on what the bytecode looks like. That means we need to decide what type of machine we’re going to build before we can start to specify bytecode.

So without further ado, let’s pull back the curtain: we’re going to build a stack machine! Why? Because stack machines are far easier to understand and to build for beginners than register machines. Less concepts, less moving parts. And all the performance considerations – is a register machine faster? – do not play a huge role for us. Our priorities are learning and understanding.

Later on we’ll see more of the implications this decision has, but the immediate and most practical one is that we now have to do stack arithmetic. That means, in order to reach our declared goal of compiling and executing the Monkey expression 1 + 2, we have to translate it to bytecode instructions that make use of a stack. The stack is where a stack machine does its work – we can’t just tell it to add two numbers, without making use of the stack.

Thankfully, we saw a similar example before and already know how to do arithmetic with a stack. We first get the operands 1 and 2 on to the stack and then tell the VM: “add these!”. This “add these!” instruction should then cause the VM to take the two topmost elements from the stack, add them together and push the result back on to the stack. Here’s what stack should look like before and after the instruction:

So in order to fully implement this we need to tell the VM:

Push 1 on to the stack

Push 2 on to the stack

Add the two topmost elements together

We need to create three instructions. As programmers, though, we know that we only need to define two separate instruction types, since pushing 2 on to the stack should be the same as pushing 1, except that the “argument” is different. So, two instruction types in total: one for pushing something on to the stack and one for adding things that are already on the stack.

We’ll implement both in the same way. First we define their opcodes and how they are encoded in bytecode. Then we extend the compiler so it can produce these instructions. As soon as the compiler knows how to do that, we can create the VM that decodes and executes them. And we start with the instructions that tell the VM to push something on to the stack.

Starting With Bytes

Here we are. We need to define our first bytecode instruction. How do we do that? Well, since creating definitions while programming is not much more than telling the computer what we know, let’s ask ourselves: what do we know about bytecode?

We know that it’s made up of instructions. And we also know, that the instructions themselves are a series of bytes and a single instruction consists of an opcode and an optional number of operands. An opcode is exactly one byte wide, has an arbitrary but unique value and is the first byte in the instruction. Looks like we know quite a lot and the best thing is, that this is precise enough to be turned into code – literally.

As our first official practical act of coding in this book, we create a new package, called code, where we start to define our Monkey bytecode format:

// code/code.go

package code

type Instructions []byte

type Opcode byte

Instructions is a slice of bytes and an Opcode is a byte. Perfect, they match our descriptions in prose pretty well. But there are two definitions missing here.

The first one is Instruction – singular. Why didn’t we define it here as []byte? Because it’s far more handy to pass around and work with a []byte and treat it implicitly as an instruction than to encode this definition in Go’s type system. You’ll see soon enough how often we’re going to use []byte and how cumbersome type assertions and type casting from and to an Instruction type would be there.

The other missing definition is one for Bytecode. There should at least be some definition of bytecode that tells us it’s made up of instructions, right? The reason for its absence is we’d run into a nasty import-cycle if we were to define Bytecode here in the code package. But it won’t be missing for too long. Once we get to the compiler, we’ll define it there – in the compiler’s package.

Now that we have definitions for Opcode and Instructions, we can define our first opcode, the one that tells the VM to push something on the stack. And here’s a surprise: the opcode won’t have “push” in its name. In fact, it won’t be solely about pushing things. Allow me to explain.

We said earlier that when we compile the Monkey expression 1 + 2, we want to generate three different instructions; two of which tell the VM to push 1 and 2 on to the stack. A first instinct might tell us to implement these by defining a “push”-instruction with an integer as its operand with the idea being that the VM then takes the integer operand and pushes it on to the stack. And for integers that would work fine, because we could easily encode them and put them directly into the bytecode. But what if later on we wanted to push other things contained in Monkey code? String literals, for example. Putting those into the bytecode is also possible, true, since it’s just made of bytes after all, but it would also be a lot of bloat and would sooner or later become unwieldy.

That’s where the idea of constants come into play. In this context, “constant” is short for “constant expression” and refers to expressions whose value doesn’t change, is constant, and can be determined at compile time:

That means we don’t need to run the program to know what these expressions evaluate to. A compiler can find them in the code and store the value they evaluate to. After that, it can reference the constants in the instructions it generates, instead of embedding the values directly in them. And while “reference” sounds like a special data type, it’s far easier than that. A plain integer does the job just fine and can serve as an index into a data structure that holds all constants, often called a constant pool.

And that’s exactly what our compiler is going to do. When we come across an integer literal (a constant expression) while compiling, we’ll evaluate it and keep track of resulting *object.Integer by storing it in memory and assigning it a number. In the bytecode instructions we’ll refer to the *object.Integer by this number. After we’re done compiling and pass the instructions to the VM for execution, we’ll also hand over all the constants we’ve found by putting them in a data structure – our constant pool – where the number that has been assigned to each constant can be used as an index to retrieve it.

Back to our first opcode. It’s called OpConstant and it has one operand: the number we previously assigned to the constant. When the VM executes OpConstant it retrieves the constant using the operand as an index and pushes it on to the stack. Here’s out first opcode definition:

// code/code.go

// [...]

const (
    OpConstant Opcode = iota
)

While this looks exactly like the meager three lines of code that they are, this addition is the groundwork for all future Opcode definitions. Each definition will have an Op prefix and the value it refers to will be determined by iota. We let iota generate increasing byte values for us, because we just don’t care about the actual values our opcodes represent. They only need to be distinct from each other and fit in one byte. iota makes sure of that for us.

What’s missing from this definition is the part that says OpConstant has one operand. There’s no technical reason for writing this down, since we could share this piece of knowledge implicitly between compiler and VM. For debugging and testing purposes, though, it’s handy being able to lookup how many operands an opcode has and what its human-readable name is. In order to achieve that, we’ll add proper definitions and some tooling to the code package:

// code/code.go

import "fmt"

type Definition struct {
    Name          string
    OperandWidths []int
}

var definitions = map[Opcode]*Definition{
    OpConstant: {"OpConstant", []int{2}},
}

func Lookup(op byte) (*Definition, error) {
    def, ok := definitions[Opcode(op)]
    if !ok {
        return nil, fmt.Errorf("opcode %d undefined", op)
    }

    return def, nil
}

The Definition for an Opcode has two fields: Name and OperandWidths. Name helps to make an Opcode readable and OperandWidths contains the number of bytes each operand takes up.

The definition for OpConstant says that its only operand is two bytes wide, which makes it an uint16 and limits its maximum value to 65535. If we include 0 the number of representable values is then 65536. That should be enough for us, because I don’t think we’re going to reference more than 65536 constants in our Monkey programs. And using an uint16 instead of, say, an uint32, helps to keep the resulting instructions smaller, because there are less unused bytes.

With this definition in place we can now create our first bytecode instruction. Without any operands involved that would be as simple as adding an Opcode to an Instructions slice. But in the case of OpConstant we need to correctly encode the two-byte operand.

For that we’ll now create a function that allows us to easily create a single bytecode instruction that’s made up of an Opcode and an optional number of operands. We’ll call it Make, which gives us the pretty great identifier code.Make in other packages.

And here’s what we’ve been waiting for, the first test of this book, showing what we want Make to do:

// code/code_test.go

package code

import "testing"

func TestMake(t *testing.T) {
    tests := []struct {
        op       Opcode
        operands []int
        expected []byte
    }{
        {OpConstant, []int{65534}, []byte{byte(OpConstant), 255, 254}},
    }

    for _, tt := range tests {
        instruction := Make(tt.op, tt.operands...)

        if len(instruction) != len(tt.expected) {
            t.Errorf("instruction has wrong length. want=%d, got=%d",
                len(tt.expected), len(instruction))
        }

        for i, b := range tt.expected {
            if instruction[i] != tt.expected[i] {
                t.Errorf("wrong byte at pos %d. want=%d, got=%d",
                    i, b, instruction[i])
            }
        }
    }
}

Don’t be put off by tests only containing one test case. We’ll extend it later on when we add more Opcodes to our code vocabulary.

For now, we only pass OpConstant and the operand 65534 to Make. We then expect to get back a []byte holding three bytes. Of these three, the first one has to be the opcode, OpConstant, and the other two should be the big-endian encoding of 65534. That’s also why we used 65534 and not the maximum value 65535: this way we can check that the most significant byte comes first. 65534 will be encoded in big endian as the byte sequence 0xFF 0xFE and 65535 would be encoded as 0xFF 0xFF – hard to recognize an order.

Since Make doesn’t exist yet, the test does not fail, but fails to compile, so here’s the first version of Make:

// code/code.go

import (
    "encoding/binary"
    "fmt"
)

func Make(op Opcode, operands ...int) []byte {
    def, ok := definitions[op]
    if !ok {
        return []byte{}
    }

    instructionLen := 1
    for _, w := range def.OperandWidths {
        instructionLen += w
    }

    instruction := make([]byte, instructionLen)
    instruction[0] = byte(op)

    offset := 1
    for i, o := range operands {
        width := def.OperandWidths[i]
        switch width {
        case 2:
            binary.BigEndian.PutUint16(instruction[offset:], uint16(o))
        }
        offset += width
    }

    return instruction
}

And that’s how you make bytecode.

The first thing we’re doing here is to find out how long the resulting instruction is going to be. That allows us to allocate a byte slice with the proper length. Note that we don’t use the Lookup function to get to the definition, which gives us a much more usable function signature for Make in the tests later on. By circumventing Lookup and not having to return possible errors, we can use Make to easily build up bytecode instructions without having to check for errors after every call. The risk of producing empty byte slices by using an unknown opcode is one we’re willing to take, since we’re on the producing side here and know what we’re doing when creating instructions.

As soon as we have the final value of instructionLen, we allocate the instruction []byte and add the Opcode as its first byte – by casting it into one. Then comes the tricky part: we iterate over the defined OperandWidths, take the matching element from operands and put it in the instruction. We do that by using a switch statement with a different method for each operand, depending on how wide the operand is.

As we define additional Opcodes, we soon have to extend this switch statement. For now, we only make sure that a two-byte operand is encoded in big endian. And while it’s not hard to do that by hand, we use binary.BigEndian.PutUint16 from the standard library for this, with the benefit of having the name of the encoding immediately visible.

After encoding the operand, we increment offset by its width and the next iteration of the loop. Since the OpConstant opcode in our test case has only one operand, the loop performs only one iteration before Make returns instruction.

And, would you look at that, our fist test is compiling and passing:

$ go test ./code
ok      monkey/code 0.007s

We successfully turned OpConstant and the operand 65534 into three bytes. That means we created our first bytecode instruction!

The Smallest Compiler

Now that we have a toolbox called code, we can start working on the compiler. Since we want a system that works from end to end as soon as possible, and not a system that can only be turned on once it’s feature-complete, our goal in this section is to build the smallest possible compiler. It should only do one thing for now: produce two OpConstant instructions that later cause the VM to correctly load the integers 1 and 2 on to the stack.

In order to achieve that, this minimal compiler has to do the following: traverse the AST we pass in, find the *ast.IntegerLiteral nodes, evaluate them by turning them into *object.Integer objects, add the objects to the constant pool, and finally emit OpConstant instructions that reference the constants in said pool.

Sounds good? Perfect! Let’s start by defining Compiler and its interface in a new compiler package:

// compiler/compiler.go

package compiler

import (
    "monkey/ast"
    "monkey/code"
    "monkey/object"
)

type Compiler struct {
    instructions code.Instructions
    constants    []object.Object
}

func New() *Compiler {
    return &Compiler{
        instructions: code.Instructions{},
        constants:    []object.Object{},
    }
}

func (c *Compiler) Compile(node ast.Node) error {
    return nil
}

func (c *Compiler) Bytecode() *Bytecode {
    return &Bytecode{
        Instructions: c.instructions,
        Constants:    c.constants,
    }
}

type Bytecode struct {
    Instructions code.Instructions
    Constants    []object.Object
}

It really is minimal, isn’t it? The Compiler is a small struct with only two fields: instructions and constants. Both are internal fields and will later be modified by the Compile method. instructions will hold the generated bytecode and constants is a slice that serves as our constant pool.

But I bet the thing that caught your eye immediately is the definition we’ve been looking for earlier, in the code package: Bytecode! There it is and it doesn’t need a lot of explanation. It contains the Instructions the compiler generated and the Constants the compiler evaluated.

Bytecode is what we’ll pass to the VM and make assertions about in our compiler tests. Speaking of which, the Compile method is empty and we’re now going to write our first compiler test that tells us what it should do.

// compiler/compiler_test.go

package compiler

import (
    "monkey/code"
    "testing"
)

type compilerTestCase struct {
    input                string
    expectedConstants    []interface{}
    expectedInstructions []code.Instructions
}

func TestIntegerArithmetic(t *testing.T) {
    tests := []compilerTestCase{
        {
            input:             "1 + 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
            },
        },
    }

    runCompilerTests(t, tests)
}

func runCompilerTests(t *testing.T, tests []compilerTestCase) {
    t.Helper()

    for _, tt := range tests {
        program := parse(tt.input)

        compiler := New()
        err := compiler.Compile(program)
        if err != nil {
            t.Fatalf("compiler error: %s", err)
        }

        bytecode := compiler.Bytecode()

        err = testInstructions(tt.expectedInstructions, bytecode.Instructions)
        if err != nil {
            t.Fatalf("testInstructions failed: %s", err)
        }

        err = testConstants(t, tt.expectedConstants, bytecode.Constants)
        if err != nil {
            t.Fatalf("testConstants failed: %s", err)
        }
    }
}

What’s happening here doesn’t take long to explain: we take Monkey code as input, we parse it, produce an AST, hand it to the compiler and then make assertions about the bytecode the compiler produced.

We do that by constructing a compilerTestCase in which we define the input, which constants we expect in the constant pool and which instructions we expect the compiler to generate. Then we hand the tests slice with the compilerTestCases to runCompilerTests to run them.

That’s a slightly different approach to constructing tests compared to the first book. The reason for that is Go 1.9, which introduced the wonderful t.Helper method. t.Helper, which we call in runCompilerTests, allows us to remove duplicated logic in test functions by defining test helpers. Think of it as inlining runCompilerTests into TestIntegerArithmetic. That in turn allows to abstract away the common behaviour shared by every compiler test we’re going to write, which greatly reduces the noise in every test function and the page count of this book.

Now, let’s talk about the helpers used in runCompilerTests.

The parse function contains some of the things we built in the first book: the lexer and the parser. We hand it a string and get back an AST:

// compiler/compiler_test.go

import (
    "monkey/ast"
    "monkey/code"
    "monkey/lexer"
    "monkey/parser"
    "testing"
)

func parse(input string) *ast.Program {
    l := lexer.New(input)
    p := parser.New(l)
    return p.ParseProgram()
}

That’s the prelude. The main part of runCompilerTests revolves around the two fields of the Bytecode the compiler produced. First, we want to make sure that the bytecode.Instructions are correct. For that we have the testInstructions helper function:

// compiler/compiler_test.go

import (
    "fmt"
    // [...]
)

func testInstructions(
    expected []code.Instructions,
    actual code.Instructions,
) error {
    concatted := concatInstructions(expected)

    if len(actual) != len(concatted) {
        return fmt.Errorf("wrong instructions length.\nwant=%q\ngot =%q",
            concatted, actual)
    }

    for i, ins := range concatted {
        if actual[i] != ins {
            return fmt.Errorf("wrong instruction at %d.\nwant=%q\ngot =%q",
                i, concatted, actual)
        }
    }

    return nil
}

As you can see, it uses another helper called concatInstructions:

// compiler/compiler_test.go

func concatInstructions(s []code.Instructions) code.Instructions {
    out := code.Instructions{}

    for _, ins := range s {
        out = append(out, ins...)
    }

    return out
}

We need concatInstructions because the expectedInstructions field in compilerTestCase is not just a slice of bytes, but a slice of slices of bytes. And that’s because we use code.Make to generate the expectedInstructions, which produces a []byte. So in order to compare the expectedInstructions with the actual instructions, we need to turn the slice of slices into a flattened slice by concatenating the instructions.

The other helper used by runCompilerTests is testConstants, which resembles a lot of the test helpers we used in our evaluator package back in the first book:

// compiler/compiler_test.go

import (
    // [...]
    "monkey/object"
    // [...]
)

func testConstants(
    t *testing.T,
    expected []interface{},
    actual []object.Object,
) error {
    if len(expected) != len(actual) {
        return fmt.Errorf("wrong number of constants. got=%d, want=%d",
            len(actual), len(expected))
    }

    for i, constant := range expected {
        switch constant := constant.(type) {
        case int:
            err := testIntegerObject(int64(constant), actual[i])
            if err != nil {
                return fmt.Errorf("constant %d - testIntegerObject failed: %s",
                    i, err)
            }
        }
    }

    return nil
}

There’s a lot of noise here, but what’s happening here is not complicated. testConstants iterates through the expected constants and compares them with the actual constants the compiler produced. The switch statement is a sign of things to come. We will extend it with new case branches as soon as we expect more than integers to end up in the constant pool. For now it only uses one other helper, testIntegerObject, which is a nearly-identical replica of the testIntegerObject we used in our evaluator tests:

// compiler/compiler_test.go

func testIntegerObject(expected int64, actual object.Object) error {
    result, ok := actual.(*object.Integer)
    if !ok {
        return fmt.Errorf("object is not Integer. got=%T (%+v)",
            actual, actual)
    }

    if result.Value != expected {
        return fmt.Errorf("object has wrong value. got=%d, want=%d",
            result.Value, expected)
    }

    return nil
}

That’s all there is to TestIntegerArithmetic. The test itself is not complex, but establishes how we will write compiler tests in the future by bringing with it a lot of different test helpers. It looks like a lot of code for such a small test, but I promise you that we’ll get a lot of mileage out of this test setup.

Now, how does the test itself do? Well, not so good:

$ go test ./compiler
--- FAIL: TestIntegerArithmetic (0.00s)
 compiler_test.go:31: testInstructions failed: wrong instructions length.
  want="\x00\x00\x00\x00\x00\x01"
  got =""
FAIL
FAIL    monkey/compiler 0.008s

But considering that we didn’t write any code for the compiler yet, except defining its interface, that’s not so bad, is it? What’s bad though is the output:

want="\x00\x00\x00\x00\x00\x01"

No one looks at that and goes “Ah, I see…” I know that you’re anxious to get that compiler running and humming, but I can’t let this unreadable gibberish stand. I mean, it’s correct, those are the bytes we want, printed in hexadecimal, but it’s just not helpful. And believe me, soon enough this output would drive us nuts. So before we start filling out the compiler’s Compile() method, we’re going to invest in our developer happiness and teach our code.Instructions how to properly print themselves.

Bytecode, Disassemble!

You can teach types to print themselves in Go by giving them a String() method. That also holds true for bytecode instructions. It’s pretty easy to do, actually, but, as you already know, we wouldn’t print anything without writing a test for it, right?

// code/code_test.go

func TestInstructionsString(t *testing.T) {
    instructions := []Instructions{
        Make(OpConstant, 1),
        Make(OpConstant, 2),
        Make(OpConstant, 65535),
    }

    expected := `0000 OpConstant 1
0003 OpConstant 2
0006 OpConstant 65535
`

    concatted := Instructions{}
    for _, ins := range instructions {
        concatted = append(concatted, ins...)
    }

    if concatted.String() != expected {
        t.Errorf("instructions wrongly formatted.\nwant=%q\ngot=%q",
            expected, concatted.String())
    }
}

That’s what we expect from the to-be-implemented Instructions.String method: nicely-formatted multi-line output that tells us everything we need to know. There’s a counter at the start of each line, telling us which bytes we’re looking at, there are the opcodes in their human-readable form, and then there are the decoded operands. A lot more pleasant to look at than \x00\x00\x00\x00\x00\x01, right? We could also name the method MiniDisassembler instead of String because that’s what it is.

The test won’t compile, because the String method is undefined. So here’s the first piece of code we need to add:

// code/code.go

func (ins Instructions) String() string {
    return ""
}

Correct, we return a blank string. Why? Because that gives the compiler something to chew on and us the ability to run tests again:

$ go test ./code
--- FAIL: TestInstructionsString (0.00s)
 code_test.go:49: instructions wrongly formatted.
  want="0000 OpConstant 1\n0003 OpConstant 2\n0006 OpConstant 65535\n"
  got=""
FAIL
FAIL    monkey/code 0.008s

Perfect, it fails. That’s a lot more useful to us than an undefined: String compiler error that stops us from running the tests, because we now need to write another test and run it.

This other test is for a function that will be the heart of Instructions.String. Its name is ReadOperands and here’s what we want it to do:

// code/code_test.go

func TestReadOperands(t *testing.T) {
    tests := []struct {
        op        Opcode
        operands  []int
        bytesRead int
    }{
        {OpConstant, []int{65535}, 2},
    }

    for _, tt := range tests {
        instruction := Make(tt.op, tt.operands...)

        def, err := Lookup(byte(tt.op))
        if err != nil {
            t.Fatalf("definition not found: %q\n", err)
        }

        operandsRead, n := ReadOperands(def, instruction[1:])
        if n != tt.bytesRead {
            t.Fatalf("n wrong. want=%d, got=%d", tt.bytesRead, n)
        }

        for i, want := range tt.operands {
            if operandsRead[i] != want {
                t.Errorf("operand wrong. want=%d, got=%d", want, operandsRead[i])
            }
        }
    }
}

As you can see, ReadOperands is supposed to be Make’s counterpart. Whereas Make encodes the operands of a bytecode instruction, it’s the job of ReadOperands to decode them.

In TestReadOperands we Make a fully-encoded instruction and pass its definition to ReadOperands, along with the subslice of the instruction containing the operands. ReadOperands should then return the decoded operands and tell us how many bytes it read to do that. As you can probably imagine by now, we’re going to extend the tests table as soon as we have more opcodes and different instruction types.

The test fails because ReadOperands is not defined:

$ go test ./code
# monkey/code
code/code_test.go:71:22: undefined: ReadOperands
FAIL    monkey/code [build failed]

In order to get it to pass we have to implement a ReadOperands function that reverses everything Make did:

// code/code.go

func ReadOperands(def *Definition, ins Instructions) ([]int, int) {
    operands := make([]int, len(def.OperandWidths))
    offset := 0

    for i, width := range def.OperandWidths {
        switch width {
        case 2:
            operands[i] = int(ReadUint16(ins[offset:]))
        }

        offset += width
    }

    return operands, offset
}

func ReadUint16(ins Instructions) uint16 {
    return binary.BigEndian.Uint16(ins)
}

Just like in Make, we use the *Definition of an opcode to find out how wide the operands are and allocate a slice with enough space to hold them. We then go through the Instructions slice and read in and convert as many bytes as defined in the definition. And again: the switch statement will be extended soon.

Let me explain why ReadUint16 is a separate, public function. In Make we did the encoding of operands to bytes inline. Here, though, we want to expose the function so it can be used directly by the VM, allowing us to skip the definition lookup required by ReadOperands.

We now have one less failing test and can start to unwind and go back to the failing tests that brought us here. The first one is TestInstructionString, which is still chewing on the blank string:

$ go test ./code
--- FAIL: TestInstructionsString (0.00s)
 code_test.go:49: instructions wrongly formatted.
  want="0000 OpConstant 1\n0003 OpConstant 2\n0006 OpConstant 65535\n"
  got=""
FAIL
FAIL    monkey/code 0.008s

Now that we have ReadOperands, we can get rid of the blank string and properly print instructions:

// code/code.go

import (
    "bytes"
    // [...]
)

func (ins Instructions) String() string {
    var out bytes.Buffer

    i := 0
    for i < len(ins) {
        def, err := Lookup(ins[i])
        if err != nil {
            fmt.Fprintf(&out, "ERROR: %s\n", err)
            continue
        }

        operands, read := ReadOperands(def, ins[i+1:])

        fmt.Fprintf(&out, "%04d %s\n", i, ins.fmtInstruction(def, operands))

        i += 1 + read
    }

    return out.String()
}

func (ins Instructions) fmtInstruction(def *Definition, operands []int) string {
    operandCount := len(def.OperandWidths)

    if len(operands) != operandCount {
        return fmt.Sprintf("ERROR: operand len %d does not match defined %d\n",
            len(operands), operandCount)
    }

    switch operandCount {
    case 1:
        return fmt.Sprintf("%s %d", def.Name, operands[0])
    }

    return fmt.Sprintf("ERROR: unhandled operandCount for %s\n", def.Name)
}

I don’t think I have to explain to you how this works because we’ve seen variations of this going-through-a-byte-slice mechanism a few times now. The rest is string formatting. But here’s something worth looking at:

$ go test ./code
ok      monkey/code 0.008s

The tests in the code package now pass. Our mini-disassembler works. We can unwind even further and rerun the failing compiler test that kicked off this ride through the code package:

$ go test ./compiler
--- FAIL: TestIntegerArithmetic (0.00s)
 compiler_test.go:31: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpConstant 1\n"
  got =""
FAIL
FAIL    monkey/compiler 0.008s

Isn’t that beautiful? Alright, granted, beautiful may be a tad too much, but it sure isn’t the eyesore that was want="\x00\x00\x00\x00\x00\x01".

We just leveled up. With such debuggable output, working on our compiler went from “fumbling in the dark” to “here, let me get that for you”.

Back to the Task at Hand

Let’s take inventory. We have a lexer, a parser, the dotted outline of a compiler and a failing test that tells us that we need to generate two bytecode instructions. In our toolbox are the definition of an opcode and its operand, the Make function that lets us create bytecode instructions, our object system that we can use to pass Monkey values around, and readable and stunning Instructions.

And here’s a reminder of what our compiler needs to do: walk the AST recursively, find *ast.IntegerLiterals, evaluate them and turn them into *object.Integers, add those to the constants field, and add OpConstant instructions to its internal instructions slice.

Can you say “walk in the park”?

Let’s start by walking the AST. That’s something we already did in the Eval function we wrote in the previous book and there is no reason to change the approach. Here is how we get to our *ast.IntegerLiterals:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    case *ast.Program:
        for _, s := range node.Statements {
            err := c.Compile(s)
            if err != nil {
                return err
            }
        }

    case *ast.ExpressionStatement:
        err := c.Compile(node.Expression)
        if err != nil {
            return err
        }

    case *ast.InfixExpression:
        err := c.Compile(node.Left)
        if err != nil {
            return err
        }

        err = c.Compile(node.Right)
        if err != nil {
            return err
        }

    case *ast.IntegerLiteral:
  // TODO: What now?!
    }

    return nil
}

We first go through all the node.Statements in our *ast.Program and call c.Compile with each of them. That gets us one level deeper in the AST, where we find an *ast.ExpressionStatement. That’s what represents the 1 + 2 in our test. We then compile the node.Expression of that *ast.ExpressionStatement and end up with an *ast.InfixExpression of which we have to compile the node.Left and the node.Right sides.

So far, so recursive. But the TODO is right, what do we do with the *ast.IntegerLiterals?

We need to evaluate them. That’s safe to do, remember, because literals are constant expressions and their value does not change. A 2 will always evaluate to 2. And even though “evaluate” sounds sophisticated, it means creating an *object.Integer:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IntegerLiteral:
        integer := &object.Integer{Value: node.Value}

    // [...]
    }

    // [...]
}

Okay, so now we have the result of the evaluation – integer – at hand and can add it to our constant pool. To do that, we’ll add another helper to our compiler, called addConstant:

// compiler/compiler.go

func (c *Compiler) addConstant(obj object.Object) int {
    c.constants = append(c.constants, obj)
    return len(c.constants) - 1
}

We append the obj to the end of the compilers constants slice and give it its very own identifier by returning its index in the constants slice. This identifier will now be used as the operand for the OpConstant instruction that should cause the VM to load this constant from the constants pool on to the stack.

We’re now able to add constants and to remember their identifier; time to emit a first instruction. Don’t be put off by the term: “emit” is compiler-speak for “generate” and “output”. It translates to: generate an instruction and add it to the results, either by printing it, writing it to a file or by adding it to a collection in memory. We’re going to do the last one:

// compiler/compiler.go

func (c *Compiler) emit(op code.Opcode, operands ...int) int {
    ins := code.Make(op, operands...)
    pos := c.addInstruction(ins)
    return pos
}

func (c *Compiler) addInstruction(ins []byte) int {
    posNewInstruction := len(c.instructions)
    c.instructions = append(c.instructions, ins...)
    return posNewInstruction
}

I’m sure that you understand all of it but I want you to make a mental note of the fact that emit returns the starting position of the just-emitted instruction. Add to this note that we’ll use the return value later on when we need to go back in c.instructions and modify it…

In the Compile method we can now use addConstant and emit to make one delicate change:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IntegerLiteral:
        integer := &object.Integer{Value: node.Value}
        c.emit(code.OpConstant, c.addConstant(integer))

    // [...]
    }

    // [...]
}

One new line, emitting the OpConstant instruction. It’s enough:

$ go test ./compiler
ok      monkey/compiler 0.008s

It’s strange that it says ok here, because we just turned the status of our first compiler test from FAIL to woah-what-?-we-did-it-!-we-have-a-compiler-!.

Powering On the Machine

Let’s do another inventory check. Here’s where we stand. We have one opcode defined, OpConstant. We have a tiny compiler that knows how to walk an AST and emit such an OpConstant instruction. Our tiny compiler also knows how to evaluate constant integer literal expressions and how to add them to its constant pool. And the compiler’s interface allows us to pass around the result of the compilation, including the emitted instructions and the constant pool.

While the instruction set of our bytecode may currently only be able to express “push this constant on to the stack” and not “do something with it”, it’s enough for us to get to work on our VM. Yes, really, it’s time for us to build our machine.

The goal for this section is to build up a VM that we can initialize with the Bytecode produced by the compiler, start and have it fetch, decode, and execute OpConstant instructions. The result of all that should be numbers being pushed on to the VM’s stack.

Sounds like a test? Well, it’s not hard to turn it into one. But before we can do that, we need to prepare by doing something unorthodox. We’ll now copy and paste our parse and testIntegerObject test helpers from our compiler tests to a new vm_test.go file:

// vm/vm_test.go

package vm

import (
    "fmt"
    "monkey/ast"
    "monkey/lexer"
    "monkey/object"
    "monkey/parser"
)

func parse(input string) *ast.Program {
    l := lexer.New(input)
    p := parser.New(l)
    return p.ParseProgram()
}

func testIntegerObject(expected int64, actual object.Object) error {
    result, ok := actual.(*object.Integer)
    if !ok {
        return fmt.Errorf("object is not Integer. got=%T (%+v)",
            actual, actual)
    }

    if result.Value != expected {
        return fmt.Errorf("object has wrong value. got=%d, want=%d",
            result.Value, expected)
    }

    return nil
}

Yes, yes, I hear you, duplication is bad, you’re right. But for now, the duplication is the most affordable solution while being easy to understand. It also won’t fall on our feet – trust me, I’ve read this book before.

Then we lay the groundwork for all future VM tests by copying the approach of the compiler tests and making it easy to define and run new test cases with the help of t.Helper:

// vm/vm_test.go

import (
    // [...]
    "monkey/compiler"
    // [...]
    "testing"
)

type vmTestCase struct {
    input    string
    expected interface{}
}

func runVmTests(t *testing.T, tests []vmTestCase) {
    t.Helper()

    for _, tt := range tests {
        program := parse(tt.input)

        comp := compiler.New()
        err := comp.Compile(program)
        if err != nil {
            t.Fatalf("compiler error: %s", err)
        }

        vm := New(comp.Bytecode())
        err = vm.Run()
        if err != nil {
            t.Fatalf("vm error: %s", err)
        }

        stackElem := vm.StackTop()

        testExpectedObject(t, tt.expected, stackElem)
    }
}

func testExpectedObject(
    t *testing.T,
    expected interface{},
    actual object.Object,
) {
    t.Helper()

    switch expected := expected.(type) {
    case int:
        err := testIntegerObject(int64(expected), actual)
        if err != nil {
            t.Errorf("testIntegerObject failed: %s", err)
        }
    }
}

The runVmTests function takes care of setting up and running each vmTestCase: lex and parse the input, take the AST, pass it to the compiler, check the compiler for errors and then hand the *compiler.Bytecode over to the New function.

The New function should return a new instance of the virtual machine, assigned to vm. This is where we get to the heart of each test case. We start the vm with a call to vm.Run and after making sure it ran without an error, we use a method called StackTop to get the object that’s left sitting on top of the VM’s stack. We then pass that to testExpectedObject to make sure that this object matches what we expected in the vmTestCase.expected field.

Whew! Quite a lot of preparation and setup. But, trust me, this is going to make it so easy to write VM tests in the future. I mean, take a look at this, our first test:

// vm/vm_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []vmTestCase{
        {"1", 1},
        {"2", 2},
        {"1 + 2", 2}, // FIXME
    }

    runVmTests(t, tests)
}

Isn’t that wonderful? No noise, no boilerplate. We just write down the Monkey code and what we expect to end up on the stack when the VM executes it.

Please note that we do not expect 3 but 2 to be sitting on top of the stack after compiling and executing 1 + 2. Sounds wrong, right? Well, it is wrong. At the end of this chapter executing 1 + 2 should, of course, result in 3. But right now we only have OpConstant defined, which makes the only thing we can test and implement the pushing of constants on the stack. And in this test case, the 2 is the second integer to be pushed, so that’s what we’re going to test.

The other two test cases, with only the integers 1 and 2 as their input, are sanity checks. They do not test separate functionality. Pushing a sole integer on to the stack is included in, well, pushing two of them. But these test cases do not have a huge cost and don’t take up a lot of space, so I added them to explicitly make sure that a single integer literal in an expression statement ends with an integer being pushed on to the stack.

Currently, though, nothing’s pushed because we haven’t defined VM yet. But we can do that now, since we already know which parts VM needs to have: instructions, constants and a stack.

// vm/vm.go

package vm

import (
    "monkey/code"
    "monkey/compiler"
    "monkey/object"
)

const StackSize = 2048

type VM struct {
    constants    []object.Object
    instructions code.Instructions

    stack []object.Object
    sp    int // Always points to the next value. Top of stack is stack[sp-1]
}

func New(bytecode *compiler.Bytecode) *VM {
    return &VM{
        instructions: bytecode.Instructions,
        constants:    bytecode.Constants,

        stack: make([]object.Object, StackSize),
        sp:    0,
    }
}

Our virtual machine is a struct with four fields. It holds the constants and instructions generated by the compiler and has a stack. Rather simple for something with such a grand name, isn’t it?

The stack is preallocated to have a StackSize number of elements, which should be enough for us. sp is the stackpointer, which we’ll increment or decrement to grow or shrink the stack, instead of modifying the stack slice itself.

Here’s the convention we’ll use for stack and sp: sp will always point to the next free slot in the stack. If there’s one element on the stack, located at index 0, the value of sp would be 1 and to access the element we’d use stack[sp-1]. A new element would be stored at stack[sp], before sp is incremented.

Knowing this, we define the StackTop method we use in our VM tests:

// vm/vm.go

func (vm *VM) StackTop() object.Object {
    if vm.sp == 0 {
        return nil
    }
    return vm.stack[vm.sp-1]
}

Now the only thing that’s keeping us from running the tests is the missing Run method of the VM:

$ go test ./vm
# monkey/vm
vm/vm_test.go:41:11: vm.Run undefined (type *VM has no field or method Run)
FAIL    monkey/vm [build failed]

The Run method is what turns the VM into a virtual machine. It contains its heartbeat, the main loop, the fetch-decode-execute cycle:

// vm/vm.go

func (vm *VM) Run() error {
    for ip := 0; ip < len(vm.instructions); ip++ {
        op := code.Opcode(vm.instructions[ip])

        switch op {
        }
    }

    return nil
}

That’s the first part of the cycle, the “fetch”. We iterate through vm.instructions by incrementing the instruction pointer, ip, and fetch the current instruction by directly accessing vm.instructions. Then we turn the byte into an Opcode. It’s important that we do not use code.Lookup here to get from a byte to an Opcode. That would be far too slow. It costs time to move the byte around, lookup the opcode’s definition, return it and take it apart.

I know that this doesn’t sound like my usual chant of “we’re here to learn, not to build the fastest thing ever”, but we’re in the hot path here; everything we can get rid of, we should throw out. Using code.Lookup here would be like putting a sleep statement in the loop. And in contrast to a generic method that wants to lookup an opcode (like our mini-disassembler in Instructions.String) we have to encode our knowledge about the instructions into the VM’s Run method anyway. We can’t just delegate the execution away and treat every instruction the same.

Alas, fast as it may be, the “fetch” part alone is not enough:

$ go test ./vm
--- FAIL: TestIntegerArithmetic (0.00s)
 vm_test.go:20: testIntegerObject failed:\
   object is not Integer. got=<nil> (<nil>)
 vm_test.go:20: testIntegerObject failed:\
   object is not Integer. got=<nil> (<nil>)
 vm_test.go:20: testIntegerObject failed:\
   object is not Integer. got=<nil> (<nil>)
FAIL
FAIL    monkey/vm   0.006s

Time to “decode” and “execute”. Decoding means adding a new case branch and decoding the operands of the instruction:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        case code.OpConstant:
            constIndex := code.ReadUint16(vm.instructions[ip+1:])
            ip += 2
        }
    // [...]
}

With the code.ReadUint16 function we decode the operands in the bytecode, starting with the byte positioned right after the opcode, at ip+1. And we use code.ReadUint16 and not code.ReadOperands for the same reason we don’t use code.Lookup when fetching the instruction: speed.

After decoding the operands, we must be careful to increment ip by the correct amount – the number of bytes we read to decode the operands. The result is that the next iteration of the loop starts with ip pointing to an opcode instead of an operand.

We still can’t run the tests, because the compiler now tells us to use the declared but unused constIndex. We better do that, by adding the “execute” part of our VM cycle:

// vm/vm.go

import (
    "fmt"
    // [...]
)

func (vm *VM) Run() error {
    // [...]
        switch op {
        case code.OpConstant:
            constIndex := code.ReadUint16(vm.instructions[ip+1:])
            ip += 2

            err := vm.push(vm.constants[constIndex])
            if err != nil {
                return err
            }
        }
    // [...]
}

func (vm *VM) push(o object.Object) error {
    if vm.sp >= StackSize {
        return fmt.Errorf("stack overflow")
    }

    vm.stack[vm.sp] = o
    vm.sp++

    return nil
}

We use constIndex to get to the constant in vm.constants and then push it on to the stack. The succinctly named vm.push method that takes care of checking the stack size, adding the object and incrementing the stackpointer, sp.

Our virtual machine has come to life:

$ go test ./vm
ok      monkey/vm   0.007s

That means we have successfully defined our own bytecode format, built a compiler that translates a subset of Monkey into this bytecode format and created a virtual machine that executes the bytecode. Again, ok is rather somber – itstimetodance would be more appropriate.

We’ve also built a lot of infrastructure and tools to compile and execute these two OpConstant instruction. And at the moment that might feel excessive, but believe me, it’s going to pay off. We can already see the benefits when we add another opcode now.

Adding on the Stack

At the beginning of this chapter we set out to compile and execute the Monkey expression 1 + 2. Now we’re nearly there. All that’s left to do is to actually add the integers we’ve pushed on to the stack. For that, we need a new opcode.

The new opcode is called OpAdd and tells the VM to pop the two topmost elements off the stack, add them together and push the result back on to the stack. In contrast to OpConstant, it doesn’t have any operands. It’s simply one byte, a single opcode:

// code/code.go

const (
    OpConstant Opcode = iota
    OpAdd
)

var definitions = map[Opcode]*Definition{
    OpConstant: {"OpConstant", []int{2}},
    OpAdd:      {"OpAdd", []int{}},
}

Right next to OpConstant we add the new definition of OpAdd. There’s nothing remarkable here, except that the OperandWidths field in the *Definition holds an empty slice to signify that OpAdd doesn’t have any operands. And that’s only remarkable in how unremarkable it is. But we still need to make sure that our tooling can handle an opcode without any operands. First on the list is Make:

// code/code_test.go

func TestMake(t *testing.T) {
    tests := []struct {
        op       Opcode
        operands []int
        expected []byte
    }{
        // [...]
        {OpAdd, []int{}, []byte{byte(OpAdd)}},
    }

    // [...]
}

One new test case to make sure that Make knows how to encode a single Opcode into a byte slice. And guess what? It already does:

$ go test ./code
ok      monkey/code 0.006s

That means we can now use Make to test whether the Instructions.String method can also handle OpAdd. We change the test input and the expectation to include it:

// code/code_test.go

func TestInstructionsString(t *testing.T) {
    instructions := []Instructions{
        Make(OpAdd),
        Make(OpConstant, 2),
        Make(OpConstant, 65535),
    }

    expected := `0000 OpAdd
0001 OpConstant 2
0004 OpConstant 65535
`

    // [...]
}

But, we didn’t get so lucky this time, the test fails:

$ go test ./code
--- FAIL: TestInstructionsString (0.00s)
 code_test.go:51: instructions wrongly formatted.
  want="0000 OpAdd\n0001 OpConstant 2\n0004 OpConstant 65535\n"
  got="0000 ERROR: unhandled operandCount for OpAdd\n\n\
    0001 OpConstant 2\n0004 OpConstant 65535\n"
FAIL
FAIL    monkey/code 0.007s

The error message points in the right direction, though. We need to extend the switch statement in the Instructions.fmtInstruction method to handle opcodes with no operands:

// code/code.go

func (ins Instructions) fmtInstruction(def *Definition, operands []int) string {
    // [...]

    switch operandCount {
    case 0:
        return def.Name
    case 1:
        return fmt.Sprintf("%s %d", def.Name, operands[0])
    }

    return fmt.Sprintf("ERROR: unhandled operandCount for %s\n", def.Name)
}

That turns our tests from red to green again:

$ go test ./code
ok      monkey/code 0.006s

And since OpAdd doesn’t have any operands, we don’t need to change ReadOperands, which means we’re done with updating our tools. OpAdd is now fully defined and ready to be used in our compiler.

Now, think back to our first compiler test, TestIntegerArithmetic. We asserted that the Monkey expression 1 + 2 should result in two OpConstant instructions. That was wrong back then and it’s still wrong. But we set out to build the smallest possible compiler that only does one thing, pushing integers on to the stack, so that was okay. Now we want to add those numbers, which means it’s time to fix the test by adding the missing OpAdd instruction:

// compiler/compiler_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []compilerTestCase{
        {
            input:             "1 + 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpAdd),
            },
        },
    }
    // [...]
}

expectedInstructions is now correct. Two OpConstant instructions to push the two constants on to the stack and then an OpAdd instruction that should cause the VM to add them together.

Since we only updated our tools but not yet the compiler, the test now tells us which instruction we’re not emitting:

$ go test ./compiler
--- FAIL: TestIntegerArithmetic (0.00s)
 compiler_test.go:26: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpConstant 1\n0006 OpAdd\n"
  got ="0000 OpConstant 0\n0003 OpConstant 1\n"
FAIL
FAIL    monkey/compiler 0.007s

It’s my unwavering opinion that the Instructions.String method is worth its bytes in gold.

This failing test now tells us – nicely formatted and readable! – that we need to emit an OpAdd instruction. And since we already came across an *ast.InfixExpression in the compiler’s Compile method, we know where to do that:

// compiler/compiler.go

import (
    "fmt"
    // [...]
)

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.InfixExpression:
        err := c.Compile(node.Left)
        if err != nil {
            return err
        }

        err = c.Compile(node.Right)
        if err != nil {
            return err
        }

        switch node.Operator {
        case "+":
            c.emit(code.OpAdd)
        default:
            return fmt.Errorf("unknown operator %s", node.Operator)
        }

    // [...]
    }

    // [...]
}

In the new switch statement we check the Operator field of the *ast.InfixExpression node. In case we have a + at hand (which we do in our test) we c.emit an OpAdd instruction. Then, to be safe, we add a default branch that returns an error in case we don’t know how to compile a specific infix operator. And yes, you guessed it, we’re going to add more case branches later on.

And that’s it. Our compiler is now able to emit OpAdd instructions:

$ go test ./compiler
ok      monkey/compiler 0.006s

This starts to feel like a winning streak. And now, instead of going on any detour, we move directly to the VM and implement OpAdd there too.

The best part about that is that we don’t have to write a new test – we just have to fix our old one. Because in the vm package we also wrote a “wrong” test before. Remember our assertion about 1 + 2 leaving 2 on the stack? We need to change that:

// vm/vm_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {"1 + 2", 3},
    }

    runVmTests(t, tests)
}

Now we expect a 3 instead of a 2. But that alone makes the test fail:

$ go test ./vm
--- FAIL: TestIntegerArithmetic (0.00s)
 vm_test.go:20: testIntegerObject failed:\
   object has wrong value. got=2, want=3
FAIL
FAIL    monkey/vm   0.007s

We now have to actually do something with the integers we pushed on to the stack, which means we’ve finally arrived at stack arithmetic. And what’s the first thing we need to do to add two numbers together? Exactly, pop the operands off the stack. To help with that, we add another helper to VM:

// vm/vm.go

func (vm *VM) pop() object.Object {
    o := vm.stack[vm.sp-1]
    vm.sp--
    return o
}

We first take the element from the top of the stack, located at vm.sp-1, and put it on the side. Then we decrement vm.sp, allowing the location of element that was just popped off being overwritten eventually.

In order to use this new pop method we first need to add the “decode” part for the new OpAdd instruction. But since that’s not really worth mentioning on its own, here it is with the first part of the “execute”:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpAdd:
            right := vm.pop()
            left := vm.pop()
            leftValue := left.(*object.Integer).Value
            rightValue := right.(*object.Integer).Value

        }
    // [...]
}

Extending the “decode” part of the run-loop means adding the new case code.OpAdd. After that, we’re ready to implement the operation itself, the “execute”. In this case we start by popping the operands off the stack and unwrapping their values into leftValue and rightValue.

It looks innocent enough, but here is where subtle bugs can creep in. We implicitly assume that the right operand of the infix operator is the last one to be pushed on to the stack. In the case of + the order of the operands doesn’t matter, so the implicitness is not an immediate problem. But there are other operators where the wrong order of the operands can cause wrong results. And I’m not talking about some exotic operator here – minus also needs its operand to be in the correct order.

That was just the start of the implementation of OpAdd and the VM test is still failing, so let’s finish it with one elegant addition:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpAdd:
            right := vm.pop()
            left := vm.pop()
            leftValue := left.(*object.Integer).Value
            rightValue := right.(*object.Integer).Value

            result := leftValue + rightValue
            vm.push(&object.Integer{Value: result})

        // [...]
        }
    // [...]
}

Here’s what the two added lines are doing: add leftValue and rightValue together, turn the result into an *object.Integer and push that on to the stack. And here’s what that amounts to:

$ go test ./vm
ok      monkey/vm   0.006s

Passing tests! We did it: we achieved the goal of this chapter and successfully compiled and executed the Monkey expression 1 + 2.

We can lean back now, take a big breath, relax and ponder how it feels to write a compiler and a virtual machine. I bet it wasn’t as hard as you thought it would be. Granted, our compiler and the VM are not what you’d call “feature rich”. But we’re not done yet – far from that – and we’ve built important infrastructure that’s essential to both the compiler and the VM. We can be proud of ourselves.

Hooking up the REPL

Before we move on, we can hook up the compiler and the VM to our REPL. That allows us to get instant feedback when we want to experiment with Monkey. All that takes is to remove the evaluator and the environment setup from our REPL’s Start function and replace it with the calls to the compiler and the VM we already know from our tests:

// repl/repl.go

import (
    "bufio"
    "fmt"
    "io"
    "monkey/compiler"
    "monkey/lexer"
    "monkey/parser"
    "monkey/vm"
)

func Start(in io.Reader, out io.Writer) {
    scanner := bufio.NewScanner(in)

    for {
        fmt.Printf(PROMPT)
        scanned := scanner.Scan()
        if !scanned {
            return
        }

        line := scanner.Text()
        l := lexer.New(line)
        p := parser.New(l)

        program := p.ParseProgram()
        if len(p.Errors()) != 0 {
            printParserErrors(out, p.Errors())
            continue
        }

        comp := compiler.New()
        err := comp.Compile(program)
        if err != nil {
            fmt.Fprintf(out, "Woops! Compilation failed:\n %s\n", err)
            continue
        }

        machine := vm.New(comp.Bytecode())
        err = machine.Run()
        if err != nil {
            fmt.Fprintf(out, "Woops! Executing bytecode failed:\n %s\n", err)
            continue
        }

        stackTop := machine.StackTop()
        io.WriteString(out, stackTop.Inspect())
        io.WriteString(out, "\n")
    }
}

First we tokenize the input, then we parse it, then we compile and execute the program. We also replace the previous printing of Eval’s return value with printing the object that sits on top of the VM’s stack.

Now we can start up the REPL and see our compiler and VM work behind the scenes:

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> 1
1
>> 1 + 2
3
>> 1 + 2 + 3
6
>> 1000 + 555
1555

Beautiful. But, of course, it all comes crashing down as soon as we want to do more than add two numbers together:

>> 99 - 1
Woops! Compilation failed:
 unknown operator -
>> 80 / 2
Woops! Compilation failed:
 unknown operator /

We still have work to do. Let’s get to it.

Compiling Expressions

In the previous two chapters we learned a lot of new and strange things, built a tiny compiler, a virtual machine and defined bytecode instructions. In this one, we’ll use our newfound knowledge of bytecode compilation and execution, and combine it with what we know from the first book to add support for all the infix and prefix operators Monkey supports.

That not only allows us to familiarize ourselves with our codebase and further extend its infrastructure but to also catch our breath. Besides, we have some cleaning up to do before we can move on. The thing most in need of a scrub? Our stack.

Cleaning Up the Stack

In their current state, the only thing our compiler and our VM are capable of is adding two numbers. Give them the expression 1 + 2 and our VM will correctly put 3 on its stack. That’s exactly what we want, but there’s one issue lurking in the shadows: the 3 stays on the stack and will stay there for all eternity if we don’t do something about it.

The problem is not with the expression 1 + 2 itself, but rather where it occurs. It’s part of an expression statement. As a quick refresher, we have three types of statements in Monkey: let statements, return statements and expression statements. Whereas the first two explicitly reuse the value their child-expression nodes produce, expression statements merely wrap expressions so they can occur on their own. The value they produce is not reused, by definition. But now our problem is that we do reuse it, because we involuntarily keep it on the stack.

Take a look at the following Monkey program:

1;
2;
3;

That’s three separate expression statements. And you know what ends up on the stack? Not just the value produced last, 3, but everything: 1, 2 and 3. If we have a Monkey program consisting of lots of expression statements we could fill up the stack by accident. That’s not good.

In order to fix that, we need to do two things. First, we need to define a new opcode that tells the VM to pop the topmost element off the stack. Second, we need to emit this opcode after every expression statement.

We start with the definition of the opcode, the aptly name OpPop:

// code/code.go

const (
    // [...]

    OpPop
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpPop:      {"OpPop", []int{}},
}

OpPop doesn’t have any operands, just like OpAdd. Its only job is to tell the VM to pop the topmost element off the stack and for that it doesn’t need an operand.

Now we need to use this new opcode to clean the stack after every expression statement. Thankfully, it’s easy to assert this new behaviour in our test suite, since we don’t have a lot of compiler tests yet, which is also why I thought it wise to introduce OpPop now instead of two chapters down the road. We only need to change our single test case in TestIntegerArithmetic:

// compiler/compiler_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []compilerTestCase{
        {
            input:             "1 + 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpAdd),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

The only change here is the new line containing the code.Make(code.OpPop) call. We assert that the compiled expression statement should be followed by an OpPop instruction. The desired behaviour can be made even clearer by adding another test with multiple expression statements:

// compiler/compiler_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input:             "1; 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpPop),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Please note the ; that separates the 1 from the 2. Both integer literals are separate expression statements and after each statement an OpPop instruction should be emitted. That’s not what currently happens. Instead we tell our VM to fill up its stack by loading constants on to it:

$ go test ./compiler
--- FAIL: TestIntegerArithmetic (0.00s)
 compiler_test.go:37: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpConstant 1\n0006 OpAdd\n0007 OpPop\n"
  got ="0000 OpConstant 0\n0003 OpConstant 1\n0006 OpAdd\n"
FAIL
FAIL    monkey/compiler 0.007s

But here comes the good part. In order to fix this and properly clean the stack, all we need to do is to add a single call to c.emit to our compiler:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.ExpressionStatement:
        err := c.Compile(node.Expression)
        if err != nil {
            return err
        }
        c.emit(code.OpPop)

    // [...]
    }

    // [...]
}

After compiling the node.Expression of an *ast.ExpressionStatement we emit an OpPop. That’s all it takes:

$ go test ./compiler
ok      monkey/compiler 0.006s

Okay, that’s not all it takes. We still have some work left to do, because now we need to tell our VM how to handle this OpPop instruction, which would also be a tiny addition if it weren’t for our tests.

In our VM tests we used vm.StackTop to make sure that our VM put the correct things on to its stack, but with OpPop in play we can’t do that anymore. Now, what want to assert is that “this should have been on the stack, right before you popped it off, dear VM”. In order to do that, we add a test-only method to our VM and get rid of StackTop:

// vm/vm.go

func (vm *VM) LastPoppedStackElem() object.Object {
    return vm.stack[vm.sp]
}

As per our convention vm.sp always points to the next free slot in vm.stack. This is where a new element would be pushed. But since we only pop elements off the stack by decrementing vm.sp (without explicitly setting them to nil), this is also where we can find the elements that were previously on top of the stack. With LastPoppedStackElem, we can change our VM tests to make sure OpPop is actually handled correctly:

// vm/vm_test.go

func runVmTests(t *testing.T, tests []vmTestCase) {
    t.Helper()

    for _, tt := range tests {
        // [...]

        stackElem := vm.LastPoppedStackElem()

        testExpectedObject(t, tt.expected, stackElem)
    }
}

We changed the call from vm.StackTop to vm.LastPoppedStackElem. It’s enough to break our tests:

$ go test ./vm
--- FAIL: TestIntegerArithmetic (0.00s)
 vm_test.go:20: testIntegerObject failed:\
   object is not Integer. got=<nil> (<nil>)
 vm_test.go:20: testIntegerObject failed:\
   object is not Integer. got=<nil> (<nil>)
 vm_test.go:20: testIntegerObject failed:\
   object has wrong value. got=2, want=3
FAIL
FAIL    monkey/vm   0.007s

In order to get them to pass again, we need to tell our VM to keep its stack clean and tidy:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpPop:
            vm.pop()

        }
    // [...]
}

With that, stack hygiene is restored:

$ go test ./vm
ok      monkey/vm   0.006s

But we also need to fix our REPL, where we still use StackTop, by replacing it with LastPoppedStackElem:

// repl/repl.go

func Start(in io.Reader, out io.Writer) {
    // [...]

    for {
        // [...]

        lastPopped := machine.LastPoppedStackElem()
        io.WriteString(out, lastPopped.Inspect())
        io.WriteString(out, "\n")
    }
}

Perfect! That means we can move on and safely do more arithmetic on the stack without the stack slowly blowing up in our face.

Infix Expressions

Monkey supports eight infix operators and four of them are being used for arithmetic: +, -, * and /. We’ve already added support for + with the OpAdd opcode. Now we need to add three more. And since all three of them work the same way in regards to their use of operands and the stack, we’ll add them together.

The first step is to add the Opcode definitions to the code package:

// code/code.go

const (
    // [...]

    OpSub
    OpMul
    OpDiv
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpSub: {"OpSub", []int{}},
    OpMul: {"OpMul", []int{}},
    OpDiv: {"OpDiv", []int{}},
}

OpSub stands for the -, OpMul for the * and OpDiv for the / infix operator. With these opcodes defined, we can use them in our compiler tests to make sure the compiler knows how to output them:

// compiler/compiler_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input:             "1 - 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpSub),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "1 * 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpMul),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "2 / 1",
            expectedConstants: []interface{}{2, 1},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpDiv),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Hopefully the only thing that gives you pause here is the last test case, where I changed the order of the operands. Other than that, these are boringly similar to our previous test case for 1 + 2, except for the operator itself and the expected opcode. But, alas, similarity is not something a compiler understands natively:

$ go test ./compiler
--- FAIL: TestIntegerArithmetic (0.00s)
 compiler_test.go:67: compiler error: unknown operator -
FAIL
FAIL    monkey/compiler 0.006s

What we need to change is the switch statement in our compiler’s Compile method that checks node.Operator:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.InfixExpression:
        // [...]

        switch node.Operator {
        case "+":
            c.emit(code.OpAdd)
        case "-":
            c.emit(code.OpSub)
        case "*":
            c.emit(code.OpMul)
        case "/":
            c.emit(code.OpDiv)
        default:
            return fmt.Errorf("unknown operator %s", node.Operator)
        }

    // [...]
    }

    // [...]
}

Only six lines in this snippet are new: the case branches for "-", "*" and "/". And they make the tests pass:

$ go test ./compiler
ok      monkey/compiler 0.006s

Alright, the compiler now outputs three more opcodes. Our VM must now step up to this challenge. And here too, the first thing to do is add test cases:

// vm/vm_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {"1 - 2", -1},
        {"1 * 2", 2},
        {"4 / 2", 2},
        {"50 / 2 * 2 + 10 - 5", 55},
        {"5 * (2 + 10)", 60},
        {"5 + 5 + 5 + 5 - 10", 10},
        {"2 * 2 * 2 * 2 * 2", 32},
        {"5 * 2 + 10", 20},
        {"5 + 2 * 10", 25},
        {"5 * (2 + 10)", 60},
    }

    runVmTests(t, tests)
}

Some might say that this is excessive, going overboard. But what I want to show you here is the power of stack arithmetic. We not only have the three test cases necessary to make sure the OpSub, OpMul and OpDiv opcodes are recognized by the VM, but there’s also a series of test cases that mix the infix operators, playing with their varying levels of precedence and manipulating them by hand with added parentheses. For now, they all fail, which is not the point I wanted to make:

$ go test ./vm
--- FAIL: TestIntegerArithmetic (0.00s)
 vm_test.go:30: testIntegerObject failed: object has wrong value.\
   got=2, want=-1
 vm_test.go:30: testIntegerObject failed: object has wrong value.\
   got=5, want=55
 vm_test.go:30: testIntegerObject failed: object has wrong value.\
   got=12, want=60
 vm_test.go:30: testIntegerObject failed: object has wrong value.\
   got=2, want=32
 vm_test.go:30: testIntegerObject failed: object has wrong value.\
   got=12, want=20
 vm_test.go:30: testIntegerObject failed: object has wrong value.\
   got=12, want=25
 vm_test.go:30: testIntegerObject failed: object has wrong value.\
   got=12, want=60
FAIL
FAIL    monkey/vm   0.007s

My point is how minimal the required changes are to make all of them pass. First, we replace the existing case code.OpAdd in our VM with this:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpAdd, code.OpSub, code.OpMul, code.OpDiv:
            err := vm.executeBinaryOperation(op)
            if err != nil {
                return err
            }

        }
    // [...]
}

Everything that has to with binary operations is now neatly tucked away behind the executeBinaryOperation method:

// vm/vm.go

func (vm *VM) executeBinaryOperation(op code.Opcode) error {
    right := vm.pop()
    left := vm.pop()

    leftType := left.Type()
    rightType := right.Type()

    if leftType == object.INTEGER_OBJ && rightType == object.INTEGER_OBJ {
        return vm.executeBinaryIntegerOperation(op, left, right)
    }

    return fmt.Errorf("unsupported types for binary operation: %s %s",
        leftType, rightType)
}

It doesn’t do much more than type assertions and possibly producing an error and delegates most of the work to executeBinaryIntegerOperation:

// vm/vm.go

func (vm *VM) executeBinaryIntegerOperation(
    op code.Opcode,
    left, right object.Object,
) error {
    leftValue := left.(*object.Integer).Value
    rightValue := right.(*object.Integer).Value

    var result int64

    switch op {
    case code.OpAdd:
        result = leftValue + rightValue
    case code.OpSub:
        result = leftValue - rightValue
    case code.OpMul:
        result = leftValue * rightValue
    case code.OpDiv:
        result = leftValue / rightValue
    default:
        return fmt.Errorf("unknown integer operator: %d", op)
    }

    return vm.push(&object.Integer{Value: result})
}

Here is where we finally unwrap the integers contained in the left and right operands and produce a result according to the op. There shouldn’t be any surprises here, because this method has a really similar counterpart in the evaluator package we built in the first book.

Here’s the result of adding these two methods:

$ go test ./vm
ok      monkey/vm   0.010s

Addition, subtraction, multiplication, division – they all work. As a single operations, combined, grouped by parentheses; all we do is pop operands off the stack and push the result back. Stack arithmetic – pretty neat.

Booleans

These four operators we added comprise only a subset of the operators available in Monkey. There are also has the comparison operators ==, !=, >, < and the two prefix operators ! and -. Our next goal is to implement all of them and that includes teaching our Monkey VM about another Monkey data type: booleans. Without booleans we couldn’t represent the results of these operators (well, except for the - prefix), but booleans also exist as literal expressions in Monkey:

true;
false;

We’re going to start by adding support for these two literals. That way we already have our boolean data type in place when we add the operators.

So what does a boolean literal do? Well, in our evaluator a boolean literal evaluates to the boolean value it designates: true or false. Now we’re working with a compiler and a VM, so we have to adjust our expectations a little bit. Instead of boolean literals evaluating to boolean values, we now want them to cause the VM to load the boolean values on to the stack.

That’s pretty close to what integer literals do and those are compiled to OpConstant instructions. We could treat true and false as constants too, but that would be a waste, not only of bytecode but also of compiler and VM resources. Instead, we’ll now define two new opcodes that directly tell the VM to push an *object.Boolean on to the stack:

// code/code.go

const (
    // [...]

    OpTrue
    OpFalse
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpTrue:  {"OpTrue", []int{}},
    OpFalse: {"OpFalse", []int{}},
}

Granted, I didn’t waste a lot of creativity on the naming of these two. But what they do should be clear nonetheless. Both opcodes have no operands and simply tell the VM “push true or false on to the stack”.

We can now use that to create a compiler test in which we make sure that the boolean literals true and false are translated to OpTrue and OpFalse instructions:

// compiler/compiler_test.go

func TestBooleanExpressions(t *testing.T) {
    tests := []compilerTestCase{
        {
            input:             "true",
            expectedConstants: []interface{}{},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpTrue),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "false",
            expectedConstants: []interface{}{},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpFalse),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

This is our second compiler test and has the same structure as the first one. The tests slice will be extended once we implement the comparison operators.

Both test cases fail, because the compiler only knows that it should emit an OpPop after expression statements:

$ go test ./compiler
--- FAIL: TestBooleanExpressions (0.00s)
 compiler_test.go:90: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpPop\n"
  got ="0000 OpPop\n"
FAIL
FAIL    monkey/compiler 0.009s

In order to emit OpTrue or OpFalse instructions we need to add a new case branch for *ast.Boolean to the compiler’s Compile method:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.Boolean:
        if node.Value {
            c.emit(code.OpTrue)
        } else {
            c.emit(code.OpFalse)
        }

    // [...]
    }

    // [...]
}

Yep, that did it, alright:

$ go test ./compiler
ok      monkey/compiler 0.008s

The next step is to tell the VM about true and false. And just like in the compiler package we now create a second test function:

// vm/vm_test.go

func TestBooleanExpressions(t *testing.T) {
    tests := []vmTestCase{
        {"true", true},
        {"false", false},
    }

    runVmTests(t, tests)
}

This test function is very similar to the first one, TestIntegerArithmetic. But since we now have a bool as our expectation here, we need to update the testExpectedObject function used by runVmTests and provide it with a new helper function called testBooleanObject:

// vm/vm_test.go

func testExpectedObject(
    t *testing.T,
    expected interface{},
    actual object.Object,
) {
    t.Helper()

    switch expected := expected.(type) {
    // [...]

    case bool:
        err := testBooleanObject(bool(expected), actual)
        if err != nil {
            t.Errorf("testBooleanObject failed: %s", err)
        }
    }
}

func testBooleanObject(expected bool, actual object.Object) error {
    result, ok := actual.(*object.Boolean)
    if !ok {
        return fmt.Errorf("object is not Boolean. got=%T (%+v)",
            actual, actual)
    }

    if result.Value != expected {
        return fmt.Errorf("object has wrong value. got=%t, want=%t",
            result.Value, expected)
    }

    return nil
}

testBooleanObject is testIntegerObject’s counterpart and not the most fascinating of functions, but we’ll get a lot of use out of it, that’s for sure. What is noteworthy is that our VM tests now blow up:

$ go test ./vm
--- FAIL: TestBooleanExpressions (0.00s)
panic: runtime error: index out of range [recovered]
 panic: runtime error: index out of range

goroutine 19 [running]:
testing.tRunner.func1(0xc4200ba1e0)
 /usr/local/go/src/testing/testing.go:742 +0x29d
panic(0x1116f20, 0x11eefc0)
 /usr/local/go/src/runtime/panic.go:502 +0x229
monkey/vm.(*VM).pop(...)
 /Users/mrnugget/code/02/src/monkey/vm/vm.go:74
monkey/vm.(*VM).Run(0xc420050ed8, 0x800, 0x800)
 /Users/mrnugget/code/02/src/monkey/vm/vm.go:49 +0x16f
monkey/vm.runVmTests(0xc4200ba1e0, 0xc420079f58, 0x2, 0x2)
 /Users/mrnugget/code/02/src/monkey/vm/vm_test.go:60 +0x35a
monkey/vm.TestBooleanExpressions(0xc4200ba1e0)
 /Users/mrnugget/code/02/src/monkey/vm/vm_test.go:39 +0xa0
testing.tRunner(0xc4200ba1e0, 0x11476d0)
 /usr/local/go/src/testing/testing.go:777 +0xd0
created by testing.(*T).Run
 /usr/local/go/src/testing/testing.go:824 +0x2e0
FAIL    monkey/vm   0.011s

It blows up because we’re so tidy and issue an OpPop after every expression statement to keep the stack clean. And when we try to pop something off the stack without first putting something on it, we get an index out of range panic.

The first step towards fixing this is to tell our VM about true and false and defining global True and False instances of them:

// vm/vm.go

var True = &object.Boolean{Value: true}
var False = &object.Boolean{Value: false}

The reasons for reusing global instances of the *object.Booleans are the same as in our evaluator package. First, these are immutable, unique values. true will always be true and false will always be false. Treating them as such by defining them as global variables is an absolute no-brainer in terms of performance. Why create new *object.Booleans with the same value if we can just reference these two? The second reason is that this makes comparisons in Monkey, like true == true, easier to implement and perform, because we can just compare two pointers without having to unwrap the value they’re pointing at.

Of course, defining True and False does not magically make the tests pass. We also need to push them on to the stack when instructed to do so. For that we extend the main loop of our VM:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpTrue:
            err := vm.push(True)
            if err != nil {
                return err
            }

        case code.OpFalse:
            err := vm.push(False)
            if err != nil {
                return err
            }

        }
    // [...]
}

Not much to explain here: we push the globals True and False on to the stack. That means that we are actually pushing something on to the stack before trying to clean it up again, which means our tests don’t blow up anymore:

$ go test ./vm
ok      monkey/vm   0.007s

Alright! Boolean literals work and our VM now knows about True and False. Now we can start to implement the comparison operators, because now we can put their results on to the stack.

Comparison Operators

The four comparison operators in Monkey are: ==, !=, > and <. We will now add support for all four of them by adding three (!) new opcode definitions and supporting them in the compiler and the VM. Here they are:

// code/code.go

const (
    // [...]

    OpEqual
    OpNotEqual
    OpGreaterThan
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpEqual:       {"OpEqual", []int{}},
    OpNotEqual:    {"OpNotEqual", []int{}},
    OpGreaterThan: {"OpGreaterThan", []int{}},
}

They do not have operands and instead do their work by comparing the two topmost elements on the stack. They tell the VM to pop them off and push the result back on. Just like the opcodes for arithmetic operations.

You might be wondering why there is no opcode for <. If we have OpGreaterThan, shouldn’t we have an OpLessThan, too? That’s a valid question, because we could add OpLessThan and that would be fine, but I want to show something that’s possible with compilation and not with interpretation: reordering of code.

The expression 3 < 5 can be reordered to 5 > 3 without changing its result. And because it can be reordered, that’s what our compiler is going to do. It will take every less-than expression and reorder it to emit the greater-than version instead. That way we keep the instruction set small, the loop of our VM tighter and learn about the things we can do with compilation.

Here are new test cases for the existing TestBooleanExpressions function that express this:

// compiler/compiler_test.go

func TestBooleanExpressions(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input:             "1 > 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpGreaterThan),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "1 < 2",
            expectedConstants: []interface{}{2, 1},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpGreaterThan),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "1 == 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpEqual),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "1 != 2",
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpNotEqual),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "true == false",
            expectedConstants: []interface{}{},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpTrue),
                code.Make(code.OpFalse),
                code.Make(code.OpEqual),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "true != false",
            expectedConstants: []interface{}{},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpTrue),
                code.Make(code.OpFalse),
                code.Make(code.OpNotEqual),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

What we want from our compiler is to emit two instructions to get the operands of the infix operators on to the stack and then one instruction with the correct comparison opcode. Pay attention to the expected constants in the 1 < 2 test case: their order is reversed, because the opcode is the same as in the test case before, OpGreaterThan.

Running the tests shows us that the compiler is still clueless about these new operators and opcodes:

$ go test ./compiler
--- FAIL: TestBooleanExpressions (0.00s)
 compiler_test.go:150: compiler error: unknown operator >
FAIL
FAIL    monkey/compiler 0.007s

What we have to do is to extend the case *ast.InfixExpression branch in our Compile method, where we already emit the other infix operator opcodes:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.InfixExpression:
        // [...]

        switch node.Operator {
        case "+":
            c.emit(code.OpAdd)
        case "-":
            c.emit(code.OpSub)
        case "*":
            c.emit(code.OpMul)
        case "/":
            c.emit(code.OpDiv)
        case ">":
            c.emit(code.OpGreaterThan)
        case "==":
            c.emit(code.OpEqual)
        case "!=":
            c.emit(code.OpNotEqual)
        default:
            return fmt.Errorf("unknown operator %s", node.Operator)
        }

    // [...]
    }

    // [...]
}

What’s new are the case branches for the comparison operators and they’re pretty much self-explanatory. Support for the < operator is still missing, though:

$ go test ./compiler
--- FAIL: TestBooleanExpressions (0.00s)
 compiler_test.go:150: compiler error: unknown operator <
FAIL
FAIL    monkey/compiler 0.006s

Since this the operator for which we want to reorder the operands, its implementation is an addition right at the beginning of the case branch for *ast.InfixExpression:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.InfixExpression:
        if node.Operator == "<" {
            err := c.Compile(node.Right)
            if err != nil {
                return err
            }

            err = c.Compile(node.Left)
            if err != nil {
                return err
            }
            c.emit(code.OpGreaterThan)
            return nil
        }

        err := c.Compile(node.Left)
        if err != nil {
            return err
        }
        // [...]

    // [...]
    }

    // [...]
}

What we did here is to turn < into a special case. We turn the order around and first compile node.Right and then node.Left in case the operator is <. After that we emit the OpGreaterThan opcode. We changed a less-than comparison into a greater-than comparison – while compiling. And it works:

$ go test ./compiler
ok      monkey/compiler 0.007s

The goal is, of course, that it looks to VM as if there is no such thing as a < operator. All the VM should worry about are OpGreaterThan instructions. And now that we are sure our compiler only emits those, we can turn to our VM tests:

// vm/vm_test.go

func TestBooleanExpressions(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {"1 < 2", true},
        {"1 > 2", false},
        {"1 < 1", false},
        {"1 > 1", false},
        {"1 == 1", true},
        {"1 != 1", false},
        {"1 == 2", false},
        {"1 != 2", true},
        {"true == true", true},
        {"false == false", true},
        {"true == false", false},
        {"true != false", true},
        {"false != true", true},
        {"(1 < 2) == true", true},
        {"(1 < 2) == false", false},
        {"(1 > 2) == true", false},
        {"(1 > 2) == false", true},
    }

    runVmTests(t, tests)
}

Yes, I went totally overboard here. But aren’t these test cases neat? I guess that’s what great tooling and infrastructure does for you: reduce the cost of adding new tests and, thus, features. Anyway, as neat as they may be, they fail:

$ go test ./vm
--- FAIL: TestBooleanExpressions (0.00s)
 vm_test.go:57: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:1})
 vm_test.go:57: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:2})
 vm_test.go:57: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:1})
 vm_test.go:57: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:1})
 vm_test.go:57: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:1})
 vm_test.go:57: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:1})
 vm_test.go:57: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:2})
 vm_test.go:57: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:2})
 vm_test.go:57: testBooleanObject failed: object has wrong value.\
   got=false, want=true
 vm_test.go:57: testBooleanObject failed: object has wrong value.\
   got=false, want=true
 vm_test.go:57: testBooleanObject failed: object has wrong value.\
   got=true, want=false
 vm_test.go:57: testBooleanObject failed: object has wrong value.\
   got=false, want=true
FAIL
FAIL    monkey/vm   0.008s

You and I know we’re on a roll here and that it doesn’t take much to make all of these error messages disappear. First, we add a new case branch to our VM’s Run method, so it handles the new comparison opcodes:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpEqual, code.OpNotEqual, code.OpGreaterThan:
            err := vm.executeComparison(op)
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

The executionComparison method looks pretty similar to the previously added executeBinaryOperation:

// vm/vm.go

func (vm *VM) executeComparison(op code.Opcode) error {
    right := vm.pop()
    left := vm.pop()

    if left.Type() == object.INTEGER_OBJ || right.Type() == object.INTEGER_OBJ {
        return vm.executeIntegerComparison(op, left, right)
    }

    switch op {
    case code.OpEqual:
        return vm.push(nativeBoolToBooleanObject(right == left))
    case code.OpNotEqual:
        return vm.push(nativeBoolToBooleanObject(right != left))
    default:
        return fmt.Errorf("unknown operator: %d (%s %s)",
            op, left.Type(), right.Type())
    }
}

First we pop the two operands off the stack and check their types. If they’re both integers, we’ll defer to executeIntegerComparison. If not, we use nativeBoolToBooleanObject to turn the Go bools into Monkey *object.Booleans and push the result back on to the stack.

The recipe for this method is simple: pop the operands off the stack, compare them, push the result back on to the stack. We can find the second half of that again in executeIntegerComparison:

// vm/vm.go

func (vm *VM) executeIntegerComparison(
    op code.Opcode,
    left, right object.Object,
) error {
    leftValue := left.(*object.Integer).Value
    rightValue := right.(*object.Integer).Value

    switch op {
    case code.OpEqual:
        return vm.push(nativeBoolToBooleanObject(rightValue == leftValue))
    case code.OpNotEqual:
        return vm.push(nativeBoolToBooleanObject(rightValue != leftValue))
    case code.OpGreaterThan:
        return vm.push(nativeBoolToBooleanObject(leftValue > rightValue))
    default:
        return fmt.Errorf("unknown operator: %d", op)
    }
}

In this method we do not need to pop off anything anymore, but can go straight to unwrapping the integer values contained in left and right. And then, again, we compare the operands and turn the resulting bool into True or False. If you’re excited to learn how that is done, I’m sorry, it’s really rather simple. Here is nativeBoolToBooleanObject:

// vm/vm.go

func nativeBoolToBooleanObject(input bool) *object.Boolean {
    if input {
        return True
    }
    return False
}

In total, that’s three new methods: executeComparison, executeIntegerComparison and nativeBoolToBooleanObject. And that’s all it takes for the tests to pass:

$ go test ./vm
ok      monkey/vm   0.008s

I told you, we’re on a roll here.

Prefix Expressions

Monkey supports the two prefix operators - and !. The first one negates integers and the second one booleans. Adding support for them to our compiler and VM means nearly the same as for the previous operators: define the necessary opcodes, emit them in the compiler and handle them in the VM. The difference is that this time we have to do even less, because the prefix operators only have one operand on the stack, instead of two.

Here are the two opcode definitions that translate to - and !:

// code/code.go

const (
    // [...]

    OpMinus
    OpBang
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpMinus: {"OpMinus", []int{}},
    OpBang:  {"OpBang", []int{}},
}

I don’t think I have to tell you which one’s which.

Next, we need to emit them in the compiler, which means we need to add compiler tests. Here it becomes clear that - is an integer operator and ! negates booleans, because we won’t put them together in their own test function. Instead we add test cases for them to the respective test functions that already exist. Here is the test case for OpMinus in TestIntegerArithmetic:

// compiler/compiler_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input:             "-1",
            expectedConstants: []interface{}{1},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpMinus),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

And here is the test case for OpBang in TestBooleanExpressions:

// compiler/compiler_test.go

func TestBooleanExpressions(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input:             "!true",
            expectedConstants: []interface{}{},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpTrue),
                code.Make(code.OpBang),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Now we have two failing test functions:

$ go test ./compiler
--- FAIL: TestIntegerArithmetic (0.00s)
 compiler_test.go:76: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpMinus\n0004 OpPop\n"
  got ="0000 OpPop\n"
--- FAIL: TestBooleanExpressions (0.00s)
 compiler_test.go:168: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpBang\n0002 OpPop\n"
  got ="0000 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

The failing assertions tell us that we’re missing two instructions. One to load the operand (OpConstant or OpTrue) and one for the prefix operator (OpMinus or OpBang).

Since we already know how to turn integer literals into OpConstant instructions and also how to emit OpTrue (and OpFalse for that matter), it’s irritating that this is not what’s happening in the TestIntegerArithmetic test. There is no OpConstant and no OpTrue in the output. Why?

When we take a closer look at the compiler, however, the cause is easy to spot: in the Compile method we don’t handle *ast.PrefixExpression nodes yet, we skip over them and that means we never compile the integer and boolean literals. Here’s what we need to change:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.PrefixExpression:
        err := c.Compile(node.Right)
        if err != nil {
            return err
        }

        switch node.Operator {
        case "!":
            c.emit(code.OpBang)
        case "-":
            c.emit(code.OpMinus)
        default:
            return fmt.Errorf("unknown operator %s", node.Operator)
        }

    // [...]
    }

    // [...]
}

With that we walk the AST down one level further and first compile the node.Right branch of the *ast.PrefixExpression node. That results in the operand of the expression being compiled to either an OpTrue or an OpConstant instruction. That’s the first of the two missing instructions.

And we also need to emit the opcode for the operator itself. For that we make use of our trusted friend the switch statement and either generate a OpBang or a OpMinus instruction, depending on the node.Operator at hand.

And now we have passing tests:

$ go test ./compiler
ok      monkey/compiler 0.008s

Another milestone reached! By now you know where we’re headed next: the tests of our VM. Here, just like in our compiler tests, we add test cases to the existing TestIntegerArithmetic and TestBooleanExpressions functions:

// vm/vm_test.go

func TestIntegerArithmetic(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {"-5", -5},
        {"-10", -10},
        {"-50 + 100 + -50", 0},
        {"(5 + 10 * 2 + 15 / 3) * 2 + -10", 50},
    }

    runVmTests(t, tests)
}

func TestBooleanExpressions(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {"!true", false},
        {"!false", true},
        {"!5", false},
        {"!!true", true},
        {"!!false", false},
        {"!!5", true},
    }

    runVmTests(t, tests)
}

That’s a lot of new test cases for our VM to chew on, ranging from “tiny” to “completely overboard”, like the test case that exercises every integer operator we have. But these test cases are neat, they’re cheap, I love them and they blow up spectacularly:

$ go test ./vm
--- FAIL: TestIntegerArithmetic (0.00s)
 vm_test.go:34: testIntegerObject failed: object has wrong value.\
   got=5, want=-5
 vm_test.go:34: testIntegerObject failed: object has wrong value.\
   got=10, want=-10
 vm_test.go:34: testIntegerObject failed: object has wrong value.\
   got=200, want=0
 vm_test.go:34: testIntegerObject failed: object has wrong value.\
   got=70, want=50
--- FAIL: TestBooleanExpressions (0.00s)
 vm_test.go:66: testBooleanObject failed: object has wrong value.\
   got=true, want=false
 vm_test.go:66: testBooleanObject failed: object has wrong value.\
   got=false, want=true
 vm_test.go:66: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:5})
 vm_test.go:66: testBooleanObject failed: object is not Boolean.\
   got=*object.Integer (&{Value:5})
FAIL
FAIL    monkey/vm   0.009s

We’re pros, though. Spectacular test failures don’t give us pause. We don’t blink an eye and know what to do. First, we tackle the OpBang instructions and add the missing case branch to our VM’s main loop:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpBang:
            err := vm.executeBangOperator()
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

func (vm *VM) executeBangOperator() error {
    operand := vm.pop()

    switch operand {
    case True:
        return vm.push(False)
    case False:
        return vm.push(True)
    default:
        return vm.push(False)
    }
}

In executeBangOperator we pop the operand off the stack and negate its value by treating everything other than False as truthy. The case True branch is not necessary – technically speaking – but I think it makes sense to keep it around if only for documentation’s sake, because this method is now our VM’s implementation of Monkey’s concept of truthiness.

That fixes four test cases, but an equal number is still failing in TestIntegerArithmetic:

$ go test ./vm
--- FAIL: TestIntegerArithmetic (0.00s)
 vm_test.go:34: testIntegerObject failed: object has wrong value.\
   got=5, want=-5
 vm_test.go:34: testIntegerObject failed: object has wrong value.\
   got=10, want=-10
 vm_test.go:34: testIntegerObject failed: object has wrong value.\
   got=200, want=0
 vm_test.go:34: testIntegerObject failed: object has wrong value.\
   got=70, want=50
FAIL
FAIL    monkey/vm   0.007s

We now have to mirror what we did for OpBang and booleans and add a case branch for OpMinus to the VM’s Run method:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpMinus:
            err := vm.executeMinusOperator()
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

func (vm *VM) executeMinusOperator() error {
    operand := vm.pop()

    if operand.Type() != object.INTEGER_OBJ {
        return fmt.Errorf("unsupported type for negation: %s", operand.Type())
    }

    value := operand.(*object.Integer).Value
    return vm.push(&object.Integer{Value: -value})
}

I’ll spare you the explanation and present to you:

$ go test ./vm
ok      monkey/vm   0.008s

That means we’re done. We successfully added all of Monkey’s prefix and infix operators!

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> (10 + 50 + -5 - 5 * 2 / 2) < (100 - 35)
true
>> !!true == false
false

By now you are quite familiar with the definition of new opcodes and the interaction between compiler and VM. Maybe you’re even bored by the zero-operand instructions we’re emitting, anxious to get to the good stuff. Well, I’ve got good news.

Conditionals

The previous chapter was rather mechanic in that once we knew how to add one operator to our Monkey implementation, we could follow the same recipe for the others. In this chapter, though, we’re going to take it up a notch.

We need to answer a very concrete question: how do we get our VM to execute different bytecode instructions based on a condition? As we’ll see, there’s a number of small puzzles hiding behind this question and solving them is great fun, especially once we get down to the nitty-gritty. Before we do that, though, we have to answer this question without writing any code.

So let’s give this question a little bit of context and frame it. Monkey’s conditionals look like this:

if (5 > 3) {
  everythingsFine();
} else {
  lawsOfUniverseBroken();
}

If the condition 5 > 3 evaluates to a truthy value, the first branch is executed. That’s the branch containing everythingsFine(). If the condition is not truthy, the else branch, containing lawsOfUniverseBroken(), is executed. The first branch is called the “consequence” and the else branch is called the “alternative” of a conditional.

In order to provide a blueprint for a possible implementation of conditionals and to refreshen your memory, let me go over the implementation of conditionals in Writing An Interpreter In Go real quick.

When we come across an *ast.IfExpression in the evaluator package’s Eval function, we evaluate its Condition and check the result with the isTruthy function. In case the value is truthy, we Eval the Consequence of the *ast.IfExpression. If it’s not truthy and the *ast.IfExpression has an Alternative, we Eval that instead. But if we don’t have an Alternative, we return an *object.Null.

All in all, implementing conditionals took us only around 50 lines of code. And the reason why it was so easy to implement was that we had the AST nodes on our hands. We could decide which side of the *ast.IfExpression to evaluate, because we had both available to us in the evaluator.

That’s not the case anymore. Instead of walking down the AST and executing it at the same time, we now turn the AST into bytecode and flatten it. “Flatten” because bytecode is a sequence of instructions and there are no child nodes we can choose to walk down or not. That brings us back to the hidden main question of this chapter and another problem we have to solve: how do we represent conditionals in bytecode?

Let’s say we have the following Monkey code:

if (5 > 2) {
  30 + 20
} else {
  50 - 25
}

We already know how to represent the condition 5 > 2 in bytecode, because we implemented that in the last chapter:

We also know how to represent the consequence, 30 + 20:

Representing the alternative, the 50 - 25, is just a variation of that:

But how do we tell the machine to either execute the one part or the other part, depending on the result of the OpGreaterThan instruction?

If we were to take these instructions and pass them to the VM as a flat sequence, what would happen? The VM would execute all of them, one after the other, happily incrementing its instruction pointer, fetching, decoding and executing, without a care in the world, no decisions or branches in sight. And that’s exactly what we don’t want!

What we want is for the VM to either execute the OpAdd instruction or the OpSub instruction. But since we do pass bytecode around as a flat sequence of instructions, how do we do that? Well, if we reorder our graph of instructions so that it represents a flat sequence of instructions, the question becomes this: what do we fill in the blanks here?

We need put something in the blanks so that based on the result of the OpGreaterThan instruction the VM either ignores the instructions of the consequence or the instructions making up the alternative. It should skip them. Or instead of “skip”, should we maybe say “jump over”?

Jumps

Jumps are instructions that tell machines to jump to other instructions. They’re used to implement branching (conditionals) in machine code, giving them the name “branch instructions”. And with “machine code” I mean the code that computers execute but also the bytecode virtual machines run on. Translated into the technical terms of our VM: jumps are instructions that tell the VM to change its instruction pointer to a certain value. Here’s how that works.

Let’s say – hypothetically speaking – that we had two jump opcodes and called them JUMP_IF_NOT_TRUE and JUMP_NO_MATTER_WHAT. We could use them to fill in the blanks in our graph from above like this:

When the VM executes these instructions sequentially, top to bottom here, it would first execute the instructions making up the condition, ending with the OpGreaterThan instruction. That results in a boolean sitting on the stack. Just as we defined and implemented it in the previous chapter.

The next instruction, JUMP_IF_NOT_TRUE, would tell the VM to jump to the OpConstant 4 instruction, but only if the boolean on the stack is not true. If that’s the case, the VM would jump over the consequence and right to the “else” part of the conditional, the alternative. And in case the boolean on the stack is true, the JUMP_IF_NOT_TRUE would have no effect and the VM would incorrectly execute the consequence part of the conditional. It would increment its instruction pointer and start to fetch, decode and execute the next instruction – OpConstant 2, the start of the consequence.

Here’s where it gets interesting. After executing the consequence of the conditional – the three instructions that end with OpAdd – the VM would then come across the aptly named JUMP_NO_MATTER_WHAT. This instruction comes without any attached condition and tells the VM to directly jump to the first instruction after the alternative of the conditional, skipping it entirely.

That ends our little thought experiment and gives us a clear result: if we had two opcodes like these we could implement conditionals. But still, a last question remains: how would we represent the arrows? How do we tell the VM where to jump to?

Well, why not use numbers? Jumps are instructions that tell the VM to change the value of its instruction pointer and the arrows in the diagram above are nothing more than potential values for the instruction pointer. They can be represented as numbers, contained in the jump instructions as operands and their value being the index of the instruction the VM should jump to. That value is called an offset. Used like this, with the jump target being the index of an instruction, it’s an absolute offset. Relative offsets also exist: they’re relative to the position of the jump instruction itself and denote not where exactly to jump to, but how far to jump.

If we replace the arrows with offsets and give each instructions a unique index that’s independent of its byte size (for illustration purposes), the diagram looks like this:

The operand of JUMP_IF_NOT_TRUE is now 0008. That’s the index of the OpConstant 4 instruction to which the VM should jump in case the condition is not true. The operand of JUMP_NO_MATTER_WHAT is 0011, which is the index of the instruction following the whole conditional.

And that’s how we’re going to implement conditionals! We’ll define two jump opcodes: one comes with a condition (“jump only if true”) and one does not (“just jump”). They’ll both have one operand, the index of the instruction where the VM should jump to.

So that’s our goal. Question is: how do we get there?

Compiling Conditionals

The hard part of emitting jump instructions is not choosing the right opcode. It’s the operands that make it challenging.

Say we’re in our compiler’s recursive Compile method, having just called Compile again, passing in the .Condition field of an *ast.IfExpression. The condition has been successfully compiled and we’ve emitted the translated instructions. Now we want to emit the jump instruction that tells the VM to skip to the consequence of the conditional if the value on the stack is not truthy.

Which operand do we give this jump instruction? Where do we tell the VM to jump to? We don’t know yet. Since we haven’t compiled the consequence or the alternative branch yet, we don’t how many instructions we’re going to emit, which means we don’t know how many instructions we have to jump over. That’s the challenge.

I have to admit that solving this is a lot of fun. And a great part of the fun comes from the fact that it’s pretty easy to write a test and tell the compiler exactly what’s expected – because we’re pretty sure about that part – and then make your way there step by step.

But we can only make assertions once we defined our new opcodes, so we’ll do that now. One for a jump and another one for a conditional jump.

// code/code.go

const (
    // [...]

    OpJumpNotTruthy
    OpJump
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpJumpNotTruthy: {"OpJumpNotTruthy", []int{2}},
    OpJump:          {"OpJump", []int{2}},
}

I’m pretty sure you can tell which one’s which. OpJumpNotTruthy will tell the VM to only jump if the value on top of the stack is not Monkey truthy, i.e., not false nor null. Its single operand is the offset of the instruction the VM should jump to. OpJump will tell the VM to just “jump there”, with “there” being its operand, also an offset of an instruction.

The operand of both opcodes is 16-bit wide. That’s the same width as the operand of OpConstant has, which means we don’t have to extend our tooling in the code package to support it.

We’re now ready to write a first test. And we’ll start slow and only try to handle a conditional without an else part first. Here’s what we want the compiler to emit when we provide it a single-branch conditional:

// compiler/compiler_test.go

func TestConditionals(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `
            if (true) { 10 }; 3333;
            `,
            expectedConstants: []interface{}{10, 3333},
            expectedInstructions: []code.Instructions{
                // 0000
                code.Make(code.OpTrue),
                // 0001
                code.Make(code.OpJumpNotTruthy, 7),
                // 0004
                code.Make(code.OpConstant, 0),
                // 0007
                code.Make(code.OpPop),
                // 0008
                code.Make(code.OpConstant, 1),
                // 0011
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Once parsed, the input turns into an *ast.IfExpression with a Condition and a Consequence. The Condition is the boolean literal true and the Consequence is the integer literal 10. Both are intentionally simple Monkey expressions, because in this test case we do not care about the expressions themselves. What we care about are the jump instructions the compiler emits and that they have correct operands.

That’s why I annotated the expectedInstructions with comments that show the offset of the instructions generated by code.Make. We won’t need these comments later on, but for now, they help us writing out the expected jump instructions, especially since the offsets of the instructions we want to jump to are based on the number of bytes each instruction takes up. An OpPop instruction is one byte wide, for example, but an OpConstant instruction takes up three bytes.

The first instruction we expect the compiler to emit is an OpTrue instruction to tell the VM to push vm.True on to the stack. That’s the Condition. Then it should emit an OpJumpNotTruthy instruction that causes the VM to jump over the Consequence, with the Consequence being the OpConstant instruction that loads the integer 10 on to the stack.

But where does the first OpPop instruction (offset 0007) come from? It’s not part of the Consequence, no. It’s there because conditionals in Monkey are expressions – if (true) { 10 } evaluates to 10 – and stand-alone expressions whose value is unused are wrapped in an *ast.ExpressionStatement. And those we compile with an appended OpPop instruction in order to clear the VM’s stack. The first OpPop is thus the first instruction after the whole conditional, which makes its offset the location where OpJumpNotTruthy needs to jump to in order to skip the consequence.

So now you might be wondering what the 3333; is doing in the Monkey code. It serves as a point of reference. It’s not strictly required, but in order to make sure that our jump offsets are correct it helps to have one expression in the code which we can easily find among the resulting instructions and use as a signpost that tells us where we shouldn’t jump to. Of course, the OpConstant 1 instruction that loads 3333 is also followed by an OpPop instruction, since it’s an expression statement.

Quite the long explanation for one test. Here’s how much the compiler understands of it:

$ go test ./compiler
--- FAIL: TestConditionals (0.00s)
 compiler_test.go:195: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpJumpNotTruthy 7\n0004 OpConstant 0\n0007 OpPop\
    \n0008 OpConstant 1\n0011 OpPop\n"
  got ="0000 OpPop\n0001 OpConstant 0\n0004 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

Neither the condition nor the consequence of the conditional are compiled. In fact, the whole *ast.IfExpression is skipped by the compiler. We can fix the first issue, the condition not being compiled, by extending the compiler’s Compile method like this:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IfExpression:
        err := c.Compile(node.Condition)
        if err != nil {
            return err
        }

    // [...]
    }

    // [...]
}

With this change, the compiler now knows about *ast.IfExpression and emits the instructions that represent node.Condition. And even though the consequence and the conditional jump over it are still missing, we get four out of six instructions right:

$ go test ./compiler
--- FAIL: TestConditionals (0.00s)
 compiler_test.go:195: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpJumpNotTruthy 7\n0004 OpConstant 0\n0007 OpPop\n\
    0008 OpConstant 1\n0011 OpPop\n"
  got ="0000 OpTrue\n0001 OpPop\n0002 OpConstant 0\n0005 OpPop\n"
FAIL
FAIL    monkey/compiler 0.009s

The OpTrue instruction is there, as are the last three: the OpPop following the *ast.IfExpression, the OpConstant to load the 3333 and the OpPop following that, all in the correct order. All that’s left to do now is emit the OpJumpNotTruthy instruction and the instructions to represent the node.Consequence.

With “all that’s left to do now” I, of course, mean: “this is where it gets hairy”. The challenge now is to emit an OpJumpNotTruthy instruction with an offset pointing right after the instructions of the node.Consequence – before compiling the node.Consequence.

Which offset do we use when we don’t even know how far we have to jump yet? The answer is a rather pragmatic “let’s just put garbage in there and fix it later”. You chuckle, but I’m serious. Let’s use a bogus offset and worry about fixing it later:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IfExpression:
        err := c.Compile(node.Condition)
        if err != nil {
            return err
        }

        // Emit an `OpJumpNotTruthy` with a bogus value
        c.emit(code.OpJumpNotTruthy, 9999)

        err = c.Compile(node.Consequence)
        if err != nil {
            return err
        }

    // [...]
    }

    // [...]
}

Even though most programmers already squint their eyes and instinctively know that something fishy is going on when they see a 9999 in code, an inline code comment here helps making the intention clear. Because here we really do want to emit an OpJumpNotTruthy instruction with a garbage offset and then compile the node.Consequence. Again, the 9999 is not what will end up in the VM and we’ll later take care of it. But for now, it should get us a lot more correct instructions in our test.

But, no, we only get one more right and that’s the OpJumpNotTruthy instruction itself:

$ go test ./compiler
--- FAIL: TestConditionals (0.00s)
 compiler_test.go:195: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpJumpNotTruthy 7\n0004 OpConstant 0\n0007 OpPop\n\
    0008 OpConstant 1\n0011 OpPop\n"
  got ="0000 OpTrue\n0001 OpJumpNotTruthy 9999\n0004 OpPop\n\
    0005 OpConstant 0\n0008 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

While we have the OpJumpNotTruthy 9999 instruction, we’re apparently not yet compiling the Consequence.

That’s because it’s an *ast.BlockStatement, which our compiler doesn’t know about yet. In order to get it compiled, we need to extend the Compile method by another case branch:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.BlockStatement:
        for _, s := range node.Statements {
            err := c.Compile(s)
            if err != nil {
                return err
            }
        }

    // [...]
    }

    // [...]
}

That’s exactly the same snippet of code we already have in the case branch for *ast.Program. And it works:

$ go test ./compiler
--- FAIL: TestConditionals (0.00s)
 compiler_test.go:195: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpJumpNotTruthy 7\n0004 OpConstant 0\n\
    0007 OpPop\n0008 OpConstant 1\n0011 OpPop\n"
  got ="0000 OpTrue\n0001 OpJumpNotTruthy 9999\n0004 OpConstant 0\n\
    0007 OpPop\n0008 OpPop\n0009 OpConstant 1\n0012 OpPop\n"
FAIL
FAIL    monkey/compiler 0.010s

We’re getting closer. But, besides the bogus 9999 offset, which we didn’t expect to magically disappear, there’s a new issue visible in the output, a far more subtle one. It’s possible that you missed it, so let me point you to it: there is an additional OpPop instruction generated by the compiler, at position 0007. Its origin is the compilation of node.Consequence – an expression statement.

We need to get rid of this OpPop, because we do want the consequence and the alternative of a conditional to leave a value on the stack. Otherwise, we couldn’t do this:

let result = if (5 > 3) { 5 } else { 3 };

That’s valid Monkey code and it won’t work if we emit an OpPop after the last expression statement in the node.Consequence. The value produced by the consequence would be popped off the stack, the expression wouldn’t evaluate to anything, and the let statement would end up without a value on the right side of its =.

What makes fixing this tricky is that we only want to get rid of the last OpPop instruction in the node.Consequence. Say we had Monkey code like this:

if (true) {
  3;
  2;
  1;
}

What we want here is the 3 and the 2 to be popped off the stack, but the 1 should be kept around so the whole conditional evaluates to 1. So before we tackle our main challenge of giving the OpJumpNotTruthy a real offset, here’s the plan for getting rid of the additional OpPop instruction.

We first change the compiler to keep track of the last two instructions we emitted, including their opcode and the position they were emitted to. For that, we need a new type and two more fields on the compiler:

// compiler/compiler.go

type EmittedInstruction struct {
    Opcode   code.Opcode
    Position int
}

type Compiler struct {
    // [...]

    lastInstruction     EmittedInstruction
    previousInstruction EmittedInstruction
}

func New() *Compiler {
    return &Compiler{
        // [...]
        lastInstruction:     EmittedInstruction{},
        previousInstruction: EmittedInstruction{},
    }
}

lastInstruction is the very last instruction we emitted and previousInstruction is the one before that. We’ll see why we need to keep track of both in a moment. For now, we change the compiler’s emit method to populate both fields:

// compiler/compiler.go

func (c *Compiler) emit(op code.Opcode, operands ...int) int {
    ins := code.Make(op, operands...)
    pos := c.addInstruction(ins)

    c.setLastInstruction(op, pos)

    return pos
}

func (c *Compiler) setLastInstruction(op code.Opcode, pos int) {
    previous := c.lastInstruction
    last := EmittedInstruction{Opcode: op, Position: pos}

    c.previousInstruction = previous
    c.lastInstruction = last
}

With this in place, we can check opcode of the last emitted instruction in a type-safe way, without having to cast from and to bytes. And that’s exactly what we’re going to do. After compiling the node.Consequence of the *ast.IfExpression we check whether the last instruction we emitted was an OpPop instruction and if so, we remove it:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IfExpression:
        // [...]
        c.emit(code.OpJumpNotTruthy, 9999)

        err = c.Compile(node.Consequence)
        if err != nil {
            return err
        }

        if c.lastInstructionIsPop() {
            c.removeLastPop()
        }

    // [...]
    }

    // [...]
}

This uses two helpers, lastInstructionIsPop The two helpers involved are tiny:

// compiler/compiler.go

func (c *Compiler) lastInstructionIsPop() bool {
    return c.lastInstruction.Opcode == code.OpPop
}

func (c *Compiler) removeLastPop() {
    c.instructions = c.instructions[:c.lastInstruction.Position]
    c.lastInstruction = c.previousInstruction
}

lastInstructionIsPop checks whether the opcode of the last instruction is OpPop and removeLastPop shortens c.instruction to cut off the last instruction. After that, it sets c.lastInstruction to c.previousInstruction. And that’s why we need to keep track of both of them, so c.lastInstruction doesn’t go out of sync once we cut off the last OpPop instruction.

$ go test ./compiler
--- FAIL: TestConditionals (0.00s)
 compiler_test.go:195: testInstructions failed: wrong instruction at 2.
  want="0000 OpTrue\n0001 OpJumpNotTruthy 7\n0004 OpConstant 0\n\
    0007 OpPop\n 0008 OpConstant 1\n0011 OpPop\n"
  got ="0000 OpTrue\n0001 OpJumpNotTruthy 9999\n0004 OpConstant 0\n\
    0007 OpPop\n 0008 OpConstant 1\n0011 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

Now we have the correct number of instructions and the right opcodes. The only thing that still makes our test fail is the hideous 9999. Time to get rid of it.

The way we took care of the superfluous OpPop instruction points us into the right direction by making one thing clear: the instructions we emit are not set in stone, we can change them.

Instead of removing our c.emit(code.OpJumpNotTruthy, 9999) call, we’ll leave it exactly as it is. We won’t even change the 9999. Instead, we’ll use Position field of the c.lastInstruction again. That allows us to go back to the OpJumpNotTruthy instruction we emitted and change the 9999 into the real operand. And when do we do that? That’s the kicker, the beautiful bit. We’ll modify the operand of the OpJumpNotTruthy after we compiled the node.Consequence. At that point, we’ll know how far the VM has to jump and have the correct offset with which to replace the 9999.

This is called back-patching and common in compiler’s such as ours, that only traverse the AST once and are thus called single-pass compilers. More advanced compilers might leave the target of the jump instructions empty until they know how far to jump and then do a second pass over the AST (or another IR) and fill in the targets.

Summarized: we’ll keep on emitting the 9999, while remembering where we put it. Once we know where we need to jump to, we’ll go back to the 9999 and change it to the correct offset. You’ll be surprised by how little code is needed to pull that off.

The first thing we need is a tiny method to replace an instruction at an arbitrary offset in the instructions slice:

// compiler/compiler.go

func (c *Compiler) replaceInstruction(pos int, newInstruction []byte) {
    for i := 0; i < len(newInstruction); i++ {
        c.instructions[pos+i] = newInstruction[i]
    }
}

We’ll use replaceInstruction in another method that allows us to replace the operand of an instruction:

// compiler/compiler.go

func (c *Compiler) changeOperand(opPos int, operand int) {
    op := code.Opcode(c.instructions[opPos])
    newInstruction := code.Make(op, operand)

    c.replaceInstruction(opPos, newInstruction)
}

Instead of really changing the operand itself (which can get messy with multi-byte operands), the changeOperand method recreates the instructions with the new operand and uses replaceInstruction to swap the old instruction for the new one – including the operand.

The underlying assumption here is that we only replace instructions of the same type, with the same non-variable length. If that assumption no longer holds, we’d have to tread far more carefully here and update c.lastInstruction and c.previousInstruction accordingly. You can see how another IR that’s type-safe and independent of the byte-size of encoded instructions comes in handy once the compiler and the instructions it emits grow more complex.

Our solution, though, still fits our needs and all in all is not a lot of code. Two tiny methods, replaceInstruction and changeOperand, and all that’s left to do is to use them, which is not much more code either:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IfExpression:
        err := c.Compile(node.Condition)
        if err != nil {
            return err
        }

        // Emit an `OpJumpNotTruthy` with a bogus value
        jumpNotTruthyPos := c.emit(code.OpJumpNotTruthy, 9999)

        err = c.Compile(node.Consequence)
        if err != nil {
            return err
        }

        if c.lastInstructionIsPop() {
            c.removeLastPop()
        }

        afterConsequencePos := len(c.instructions)
        c.changeOperand(jumpNotTruthyPos, afterConsequencePos)

    // [...]
    }

    // [...]
}

The first change is saving the return value of c.emit to jumpNotTruthyPos. That’s the position at which we can find the OpJumpNotTruthy instruction later on. “Later on” means right after the check for and possible removal of a OpPop instruction. After that, len(c.instructions) gives us the offset of the next-to-be-emitted instruction, which is where we want to jump to in case we don’t execute the Consequence of the conditional because the value on top of the stack is not truthy. That’s why we save it to afterConsequencePos, to give it a telling name.

After that, we use the new changeOperand method to get rid of the 9999 operand of the OpJumpNotTruthy instruction, which is located at jumpNotTruthyPos, and replace it with the correct afterConsequencePos.

Did you keep count? If not, I want you to know that the necessary changes add up to three lines. One changed, two added. That’s all:

$ go test ./compiler
ok      monkey/compiler 0.008s

Our compiler now correctly compiles a conditional! The caveat is that it only knows how to compile the consequence. It doesn’t know how to compile a conditional with both a consequence and an alternative else-branch.

But we do and we also know how to write tests:

// compiler/compiler_test.go

func TestConditionals(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input: `
            if (true) { 10 } else { 20 }; 3333;
            `,
            expectedConstants: []interface{}{10, 20, 3333},
            expectedInstructions: []code.Instructions{
                // 0000
                code.Make(code.OpTrue),
                // 0001
                code.Make(code.OpJumpNotTruthy, 10),
                // 0004
                code.Make(code.OpConstant, 0),
                // 0007
                code.Make(code.OpJump, 13),
                // 0010
                code.Make(code.OpConstant, 1),
                // 0013
                code.Make(code.OpPop),
                // 0014
                code.Make(code.OpConstant, 2),
                // 0017
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

This is similar to the previous test case in TestConditionals, except that the input now contains not only the consequence of the conditional, but also the alternative: else { 20 }.

The expectedInstructions make clear what we want the bytecode to look like, with the first part being the same as in the previous test case: the condition is compiled to OpTrue and is followed by the OpJumpNotTruthy instruction that instructs the VM to jump over the compiled consequence.

Then, things start to differ. As the next opcode, we expect an OpJump, the opcode for an unconditional jump instruction. It has to be there because if condition is truthy the VM should only execute the consequence and not the alternative. To stop that from happening the OpJump instruction tells the VM to jump over the alternative.

The OpJump should then be followed by instructions that make up the alternative. In our test case, that’s the OpConstant instruction that loads 20 on to the stack.

Then we’re back on familiar ground. An OpPop is there to pop the value produced by the conditional off the stack and the loading of the bogus 3333 gives us guidance.

I know that it’s not easy to wrap ones head around these jumps, so I hope that this illustration makes it clearer which instruction belongs to which part of the conditional and how the jumps tie them all together:

If that doesn’t help, I’m sure trying to run and fixing the failing test will, because its output tells us what we’re still missing:

$ go test ./compiler
--- FAIL: TestConditionals (0.00s)
 compiler_test.go:220: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpJumpNotTruthy 10\n0004 OpConstant 0\n\
    0007 OpJump 13\n0010 OpConstant 1\n\
    0013 OpPop\n0014 OpConstant 2\n0017 OpPop\n"
  got ="0000 OpTrue\n0001 OpJumpNotTruthy 7\n0004 OpConstant 0\n\
    0007 OpPop\n0008 OpConstant 1\n0011 OpPop\n"
FAIL
FAIL    monkey/compiler 0.007s

What we have here is the condition, then the OpPop following the whole conditional and the pushing and popping of the 3333. What’s missing is the OpJump at the end of the consequence and the instructions representing the alternative. The good news is that we already have all the tools at hand. We just need to move things around a tiny bit and compile the alternative.

The first step, though, is to wrap our patching of the OpJumpNotTruthy instruction in a condition itself:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IfExpression:
        // [...]

        if node.Alternative == nil {
            afterConsequencePos := len(c.instructions)
            c.changeOperand(jumpNotTruthyPos, afterConsequencePos)
        }

    // [...]
    }

    // [...]
}

Preceding this node.Alternative == nil check is the compilation of node.Consequence and what this added block translates to is this: only if we have no node.Alternative can we jump to here, the current position in c.instructions.

But if we do have an node.Alternative we need to emit an OpJump that becomes part of the consequence and over which the OpJumpNotTruthy also has to jump:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IfExpression:
        // [...]

        if node.Alternative == nil {
            afterConsequencePos := len(c.instructions)
            c.changeOperand(jumpNotTruthyPos, afterConsequencePos)
        } else {
            // Emit an `OpJump` with a bogus value
            c.emit(code.OpJump, 9999)

            afterConsequencePos := len(c.instructions)
            c.changeOperand(jumpNotTruthyPos, afterConsequencePos)
        }

    // [...]
    }

    // [...]
}

Don’t worry about the duplication, we’ll take care of that later on. What’s important right now is to make the intention as clear as possible.

The OpJump instruction also has a placeholder operand. That means we have to patch it later, but right now it allows us to change the operand of the OpJumpNotTruthy instruction to the desired value: the position of the instruction right after the consequence and the OpJump instruction.

And why that is the correct operand should be clear by now: the OpJump should skip over the “else”-branch of the conditional in case the condition was truthy. It’s part of the consequence, so to say. And if the condition is not truthy and we need to execute the “else”-branch, we need to use OpJumpNotTruthy to jump after the consequence, which is after the OpJump.

The tests tell us that we’re on the right track:

$ go test ./compiler
--- FAIL: TestConditionals (0.00s)
 compiler_test.go:220: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpJumpNotTruthy 10\n0004 OpConstant 0\n\
    0007 OpJump 13\n0010 OpConstant 1\n\
    0013 OpPop\n0014 OpConstant 2\n0017 OpPop\n"
  got ="0000 OpTrue\n0001 OpJumpNotTruthy 10\n0004 OpConstant 0\n\
    0007 OpJump 9999\n\
    0010 OpPop\n0011 OpConstant 1\n0014 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

The operand of OpJumpNotTruthy is correct, OpJump is in the correct place, only its operand is wrong and the whole alternative is missing. We now have to repeat what we previously did for the consequence:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IfExpression:
        // [...]

        if node.Alternative == nil {
            afterConsequencePos := len(c.instructions)
            c.changeOperand(jumpNotTruthyPos, afterConsequencePos)
        } else {
            // Emit an `OpJump` with a bogus value
            jumpPos := c.emit(code.OpJump, 9999)

            afterConsequencePos := len(c.instructions)
            c.changeOperand(jumpNotTruthyPos, afterConsequencePos)

            err := c.Compile(node.Alternative)
            if err != nil {
                return err
            }

            if c.lastInstructionIsPop() {
                c.removeLastPop()
            }

            afterAlternativePos := len(c.instructions)
            c.changeOperand(jumpPos, afterAlternativePos)
        }

    // [...]
    }

    // [...]
}

We first save the position of the OpJump instruction to jumpPos so that we can later come back and change its operand. Then we patch the operand of the previously emitted OpJumpNotTruthy instruction, located at jumpNotTruthyPos, making it jump right after the just emitted OpJump.

After that, we compile node.Alternative. Here, too, we have to c.removeLastPop() if there is one. Finally, we change the operand of the OpJump instruction to the offset of the next-to-be-emitted instruction, which will be located right after the alternative.

Or, in the words of our test suite:

$ go test ./compiler
ok      monkey/compiler 0.009s

Again, take the ok with a grain of salt. It should say: “Yes! Yes! Yes! We’re compiling conditionals to jump instructions!”

We’re over the hump now. It is time to teach our VM how to execute jumps, and that’s far easier than emitting them.

Executing Jumps

Before we wrote the compiler tests for conditionals, we really had to think through what we want them to say and what we want the compiler to do. That’s not the case now, when writing the same tests for the VM. We already know how conditionals in Monkey are supposed to work and can cleanly express that in test cases and assertions:

// vm/vm_test.go

func TestConditionals(t *testing.T) {
    tests := []vmTestCase{
        {"if (true) { 10 }", 10},
        {"if (true) { 10 } else { 20 }", 10},
        {"if (false) { 10 } else { 20 } ", 20},
        {"if (1) { 10 }", 10},
        {"if (1 < 2) { 10 }", 10},
        {"if (1 < 2) { 10 } else { 20 }", 10},
        {"if (1 > 2) { 10 } else { 20 }", 20},
    }

    runVmTests(t, tests)
}

Half of these test cases would’ve been enough. But they’re easy to write, expressive, neat and cost us basically nothing! It also doesn’t hurt us to be abundantly clear about what we want.

We test whether boolean expressions are correctly evaluated by the VM according to Monkey’s “truthy” standards and that the correct branch of the conditional is taken. Since conditionals are expressions that produce values, they allow us to infer which branch was executed by testing for the produced value of the whole conditional.

As neat as the tests are, the error message they produce is nasty:

$ go test ./vm
--- FAIL: TestConditionals (0.00s)
panic: runtime error: index out of range [recovered]
 panic: runtime error: index out of range

goroutine 20 [running]:
testing.tRunner.func1(0xc4200bc2d0)
 /usr/local/go/src/testing/testing.go:742 +0x29d
panic(0x11190e0, 0x11f1fd0)
 /usr/local/go/src/runtime/panic.go:502 +0x229
monkey/vm.(*VM).Run(0xc420050e38, 0x800, 0x800)
 /Users/mrnugget/code/04/src/monkey/vm/vm.go:46 +0x30c
monkey/vm.runVmTests(0xc4200bc2d0, 0xc420079eb8, 0x7, 0x7)
 /Users/mrnugget/code/04/src/monkey/vm/vm_test.go:101 +0x35a
monkey/vm.TestConditionals(0xc4200bc2d0)
 /Users/mrnugget/code/04/src/monkey/vm/vm_test.go:80 +0x114
testing.tRunner(0xc4200bc2d0, 0x1149b40)
 /usr/local/go/src/testing/testing.go:777 +0xd0
created by testing.(*T).Run
 /usr/local/go/src/testing/testing.go:824 +0x2e0
FAIL    monkey/vm   0.011s

Ugh. Not even an error, but a panic.

Before you dive into the code, though, and try to figure out where the error originates, let me explain: the VM is tripping over the bytecode because it contains opcodes it doesn’t know how to decode. That in itself shouldn’t be a problem, because unknown opcodes are skipped, but not necessarily their operands. Operands are just integers, remember, and might have the same value as an encoded opcode, which might lead the VM to treat them as such. That’s wrong, of course. It’s time we introduce our VM to our jump instructions.

We’ll start with OpJump, because it’s the most straightforward jump instruction we have. It has one 16 bit operand that’s the offset of the instruction the VM should jump to. That’s all we need to know to implement it:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpJump:
            pos := int(code.ReadUint16(vm.instructions[ip+1:]))
            ip = pos - 1

        // [...]
        }
    // [...]
}

We use code.ReadUint16 to decode the operand located right after the opcode. That’s step 1. Step 2 is to set the instruction pointer, ip, to the target of our jump. Here’s where we come across one interesting implementation detail: since we’re in a loop that increments ip with each iteration we need to set ip to the offset right before the one we want. That lets the loop do its work and ip gets set to the value we want in the next cycle.

Solely implementing OpJump doesn’t buy us much though, since it’s OpJumpNotTruthy that’s integral to the implementation of conditionals. But while adding a case branch for code.OpJumpNotTruthy does take slightly more code, it’s not much more complicated:

// vm/vm.go

func (vm *VM) Run() error {
    for ip := 0; ip < len(vm.instructions); ip++ {
        op := code.Opcode(vm.instructions[ip])

        switch op {
        // [...]

        case code.OpJumpNotTruthy:
            pos := int(code.ReadUint16(vm.instructions[ip+1:]))
            ip += 2

            condition := vm.pop()
            if !isTruthy(condition) {
                ip = pos - 1
            }

        // [...]

        }
    }
    // [...]
}

func isTruthy(obj object.Object) bool {
    switch obj := obj.(type) {

    case *object.Boolean:
        return obj.Value

    default:
        return true
    }
}

We again use code.ReadUint16 to read in and decode the operand. After that we manually increase ip by two so we correctly skip over the two bytes of the operand in the next cycle. That’s not a new – we’ve already done that when executing OpConstant instructions.

What’s new is the rest. We pop off the topmost stack element and check if it’s truthy with the helper function isTruthy. If it’s not truthy, we jump, which means that we set ip to the index of the instruction right before the target, letting the for-loop do its work.

If the value is truthy we do nothing and start another iteration of the main loop. The result is that we’re executing the consequence of the conditional, which is made up of the instructions right after the OpJumpNotTruthy instruction.

And now, open a drumroll.wav of your choice in your favorite audio player, pour your preferred beverage, hit play and watch this:

$ go test ./vm
ok      monkey/vm   0.009s

We did it. Yes, we did it! Our bytecode compiler and VM are now able to compile and execute Monkey conditionals!

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> if (10 > 5) { 10; } else { 12; }
10
>> if (5 > 10) { 10; } else { 12; }
12
>>

This is the point where we went from “well, this is toy, isn’t it?” to “oh wow, we’re getting somewhere!”. Stack arithmetic is one thing, but jump instructions are another. We’re in the big leagues now. Except…

>> if (false) { 10; }
panic: runtime error: index out of range

goroutine 1 [running]:
monkey/vm.(*VM).pop(...)
 /Users/mrnugget/code/04/src/monkey/vm/vm.go:117
monkey/vm.(*VM).Run(0xc42005be48, 0x800, 0x800)
 /Users/mrnugget/code/04/src/monkey/vm/vm.go:60 +0x40e
monkey/repl.Start(0x10f1080, 0xc42000e010, 0x10f10a0, 0xc42000e018)
 /Users/mrnugget/code/04/src/monkey/repl/repl.go:43 +0x47a
main.main()
 /Users/mrnugget/code/04/src/monkey/main.go:18 +0x107

We forgot something.

Welcome Back, Null!

At the start of this chapter we looked back at our implementation of conditionals in Writing An Interpreter In Go, and now we have implemented the majority of its behaviour. But there’s one thing we’re still missing: what happens when the condition of a conditional is not truthy but the conditional itself has no alternative? In the previous book the answer to this question was *object.Null, Monkey’s null value.

That makes sense, because conditionals are expressions and expressions, by definition, produce values. So what does an expression that produced nothing evaluate to? Null. Wait, let me try that again, only this time imagine a big organ sound in the background, crows flying overhead, screeching, thunder: They… lightning strikes… evaluate to … sirens … null.

Look, null and I, we’re not the best of friends. I’m not really sure what to think of it, whether it’s good or bad. It’s the cause of many curses but I do understand that there are languages in which some things evaluate to nothing and that “nothing” has to be represented somehow. In Monkey, conditionals with a false condition and no alternative are one of these things, and “nothing” is represented by *object.Null. Long story short: it’s time we introduce *object.Null to our compiler and VM and make this type of conditional work properly.

The first thing we need is a definition of *object.Null in our VM. Since its value is constant, we can define it as a global variable, just like our previous global definitions of vm.True and vm.False:

// vm/vm.go

var Null = &object.Null{}

This is also similar to vm.True and vm.False in that it saves us a lot of work when comparing Monkey objects. We can simply check if an object.Object is *object.Null by checking whether it’s equal to vm.Null. We do not have to unwrap it and take a look at its value.

The reason why we first defined vm.Null, before writing any compiler tests – our usual course of action – is that this time we want do write a VM test first. And that’s because the VM tests allow us to express what we want so succinctly:

// vm/vm_test.go

func TestConditionals(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {"if (1 > 2) { 10 }", Null},
        {"if (false) { 10 }", Null},
    }

    runVmTests(t, tests)
}

func testExpectedObject(
    t *testing.T,
    expected interface{},
    actual object.Object,
) {
    t.Helper()

    switch expected := expected.(type) {
    // [...]
    case *object.Null:
        if actual != Null {
            t.Errorf("object is not Null: %T (%+v)", actual, actual)
        }
    }
}

Here we have two new test cases for our existing TestConditionals function in which the condition is not Monkey truthy to force the evaluation of the alternative. But since there is none, we expect Null to end up on the stack. To test that properly, we extend the testExpectedObject with a new case branch for *object.Null.

Neatly expressed, isn’t it? Well, the error message isn’t:

$ go test ./vm
--- FAIL: TestConditionals (0.00s)
panic: runtime error: index out of range [recovered]
 panic: runtime error: index out of range

goroutine 7 [running]:
testing.tRunner.func1(0xc4200a82d0)
 /usr/local/go/src/testing/testing.go:742 +0x29d
panic(0x1119420, 0x11f1fe0)
 /usr/local/go/src/runtime/panic.go:502 +0x229
monkey/vm.(*VM).pop(...)
 /Users/mrnugget/code/04/src/monkey/vm/vm.go:121
monkey/vm.(*VM).Run(0xc420054df8, 0x800, 0x800)
 /Users/mrnugget/code/04/src/monkey/vm/vm.go:53 +0x418
monkey/vm.runVmTests(0xc4200a82d0, 0xc420073e78, 0x9, 0x9)
 /Users/mrnugget/code/04/src/monkey/vm/vm_test.go:103 +0x35a
monkey/vm.TestConditionals(0xc4200a82d0)
 /Users/mrnugget/code/04/src/monkey/vm/vm_test.go:82 +0x149
testing.tRunner(0xc4200a82d0, 0x1149f40)
 /usr/local/go/src/testing/testing.go:777 +0xd0
created by testing.(*T).Run
 /usr/local/go/src/testing/testing.go:824 +0x2e0
FAIL    monkey/vm   0.012s

The cause for this panic are the OpPop instructions we emit after the conditionals. Since they produced no value, the VM crashes trying to pop something off the stack. Time to change that, time to put vm.Null on to the stack.

We’re going to do two things to pull that off. First, we’re going to define an opcode that tells the VM to put vm.Null on the stack. Then we’re going to modify the compiler to insert an alternative when a conditional doesn’t have one. And the only thing this alternative branch will contain is the new opcode that pushes vm.Null on to the stack.

We define the opcode first so we can use it in our updated compiler tests:

// code/code.go

const (
    // [...]

    OpNull
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpNull:  {"OpNull", []int{}},
}

That’s also similar to the boolean counterparts, OpTrue and OpFalse. OpNull doesn’t have any operands and only instructs the VM to push one value on to the stack.

Instead of now writing a new compiler test, we’re going to update an existing test case in TestConditionals and expect to find OpNull in the generated instructions. Please note that we need to change the first test case, the one in which the conditional doesn’t have an alternative; the other test case stays as it is:

// compiler/compiler_test.go

func TestConditionals(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `
            if (true) { 10 }; 3333;
            `,
            expectedConstants: []interface{}{10, 3333},
            expectedInstructions: []code.Instructions{
                // 0000
                code.Make(code.OpTrue),
                // 0001
                code.Make(code.OpJumpNotTruthy, 10),
                // 0004
                code.Make(code.OpConstant, 0),
                // 0007
                code.Make(code.OpJump, 11),
                // 0010
                code.Make(code.OpNull),
                // 0011
                code.Make(code.OpPop),
                // 0012
                code.Make(code.OpConstant, 1),
                // 0015
                code.Make(code.OpPop),
            },
        },
        // [...]
    }

    runCompilerTests(t, tests)
}

New are the two instructions in the middle: OpJump and OpNull. Remember, OpJump is there to jump over the alternative and now OpNull is the alternative. And since the addition of these two instructions changes the index of existing instructions, the operand for OpJumpNotTruthy also has to be changed from 7 to 10. The rest stays the same.

Running the updated tests confirms that the compiler didn’t learn how to insert artificial alternatives to conditionals on its own yet:

$ go test ./compiler
--- FAIL: TestConditionals (0.00s)
 compiler_test.go:288: testInstructions failed: wrong instructions length.
  want="0000 OpTrue\n0001 OpJumpNotTruthy 10\n0004 OpConstant 0\n\
    0007 OpJump 11\n0010 OpNull\n\
    0011 OpPop\n0012 OpConstant 1\n0015 OpPop\n"
  got ="0000 OpTrue\n0001 OpJumpNotTruthy 7\n0004 OpConstant 0\n\
    0007 OpPop\n0008 OpConstant 1\n0011 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

The best part about fixing this is making the code in our compiler simpler and easier to understand. We no longer have to check whether to emit OpJump or not, because we always want to do that now. Only sometimes do we want to jump over a “real” alternative and sometimes over an OpNull instruction. So, here’s the updated case *ast.IfExpression branch of the Compile method:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IfExpression:
        err := c.Compile(node.Condition)
        if err != nil {
            return err
        }

        // Emit an `OpJumpNotTruthy` with a bogus value
        jumpNotTruthyPos := c.emit(code.OpJumpNotTruthy, 9999)

        err = c.Compile(node.Consequence)
        if err != nil {
            return err
        }

        if c.lastInstructionIsPop() {
            c.removeLastPop()
        }

        // Emit an `OpJump` with a bogus value
        jumpPos := c.emit(code.OpJump, 9999)

        afterConsequencePos := len(c.instructions)
        c.changeOperand(jumpNotTruthyPos, afterConsequencePos)

        if node.Alternative == nil {
            c.emit(code.OpNull)
        } else {
            err := c.Compile(node.Alternative)
            if err != nil {
                return err
            }

            if c.lastInstructionIsPop() {
                c.removeLastPop()
            }
        }

        afterAlternativePos := len(c.instructions)
        c.changeOperand(jumpPos, afterAlternativePos)

    // [...]
    }

    // [...]
}

That’s the complete branch but only its second half has been changed: the duplicated patching of the OpJumpNotTruthy instruction is gone and in its place we can find the new, readable compilation of a possible node.Alternative.

We start by emitting an OpJump instruction and updating the operand of the OpJumpNotTruthy instruction. That happens whether we have a node.Alternative or not. But then we check whether node.Alternative is nil and if it is, we emit the new OpNull opcode. If it’s not nil, we proceed as before: compile node.Alternative and then try to get rid of a possible OpPop instruction.

After that, we change the operand of the OpJump instruction to jump over the freshly-compiled alternative – no matter whether that’s just an OpNull or more.

That code is not only a lot cleaner than our previous version, it also works:

$ go test ./compiler
ok      monkey/compiler 0.009s

Now we can move on to our VM, where our test is still failing and where we have to implement the new OpCode opcode:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpNull:
            err := vm.push(Null)
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

With that, the panic is gone and our tests pass:

$ go test ./vm
ok      monkey/vm   0.009s

That means we’ve successfully made conditionals with a non-truthy condition put Null on to the stack. We have now implemented the complete behaviour of conditionals as described in Writing An Interpreter In Go!

But, sorry to say, there’s one more thing we have to do. With this last passing test, we’ve officially entered a new world. Since a conditional is an expression and expressions can be used interchangeably, it follows that any expression can now produce Null in our VM. It’s a scary world, yes.

For us, the practical implication is that we now have to handle Null in every place where we handle a value produced by an expression. Thankfully, most of these places in our VM – like vm.executeBinaryOperation – throw an error if they come across a value they did not expect. But there are functions and methods that now must handle Null explicitly.

The first of these is vm.executeBangOperator. We can add a test to make sure that it handles Null without blowing up:

// vm/vm_test.go

func TestBooleanExpressions(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {"!(if (false) { 5; })", true},
    }

    runVmTests(t, tests)
}

With this test case we implicitly make sure that a conditional with a non-truthy condition and no alternative results in Null and that the negation of that, through the use of the ! operator, turns it into True. Under the hood, this involves vm.executeBangOperator and in order to get the test to pass, we need to change it:

// vm/vm.go

func (vm *VM) executeBangOperator() error {
    operand := vm.pop()

    switch operand {
    case True:
        return vm.push(False)
    case False:
        return vm.push(True)
    case Null:
        return vm.push(True)
    default:
        return vm.push(False)
    }
}

The negation of Null is now True – exactly as in Writing An Interpreter In Go. The tests pass:

$ go test ./vm
ok      monkey/vm   0.009s

Here comes the weird part. Since a conditional is an expression and its condition is one too, it follows that we can use a conditional as the condition of another conditional. Here, too, I’m sure that you and I wouldn’t do this in the code we write, but be that as it may, it has to work in our VM – even if the inner conditional produces Null:

// vm/vm_test.go

func TestConditionals(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {"if ((if (false) { 10 })) { 10 } else { 20 }", 20},
    }

    runVmTests(t, tests)
}

This looks like it might be a mess to fix, but since our code is squeaky clean and well maintained there’s only one place where we need to make a change; a quite obvious one, too. We need to tell the VM that an *object.Null is not isTruthy:

// vm/vm.go

func isTruthy(obj object.Object) bool {
    switch obj := obj.(type) {

    case *object.Boolean:
        return obj.Value

    case *object.Null:
        return false

    default:
        return true
    }
}

That’s two new lines of code and we’re done:

$ go test ./vm
ok      monkey/vm   0.011s

And now done means done. Our implementation of conditionals is now feature complete and we have a Null-safe VM:

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> if (false) { 10 }
null

Time to play drumroll.wav again, only this time knowing that we didn’t forget something.

Keeping Track of Names

Up until now we’ve referenced values in our Monkey code by using boolean and integer literals. That’s going to change. In this chapter we’re going to implement bindings, by adding support for let statements and identifier expressions. At the end, we’ll be able to bind any value to any name and then have that name resolve to the value.

As preparation, here’s a short refresher of what let statements in Monkey look like:

let x = 5 * 5;

As you can see, a let statement in Monkey starts with the let keyword followed by an identifier. The identifier is the name to which we want to bind a value, in this case it’s x. The right side of the = is an expression. It evaluates to the value the name will be bound to. And since it’s a let statement it’s followed by a semicolon. Let name equal value of expression; that’s it.

Referencing the value to which x has been bound is easy, since identifiers, which is what the x is in the terms of our AST, are expressions and can be used interchangeably. We can use x in every place where an expression is valid:

x * 5 * x * 5;
if (x < 10) { x * 2 } else { x / 2 };
let y = x + 5;

Let statements are valid as either top-level statements or inside a block statement, like the branches of a conditional or the body of a function. In this chapter, we’re only going to add support for the top-level and non-function-body block-statement varieties. We’ll tackle local variables, which is what let statements inside functions produce, when we implement functions and closures.

Our goal for this chapter is to be able to compile the following code to bytecode and have our VM execute it:

let x = 5 * 5;

if (x > 10) {
  let y = x * 2;
  y;
}

And, yes, it should also correctly execute it and produce 50 here.

The Plan

So how do we go about implementing this? Obviously, we need to compile let statements and identifier expressions to bytecode instructions and support these instructions in the VM. That much is clear. And I also don’t think there’s any debate about how many new opcodes we need. We need one to tell the VM to bind a value to an identifier and another one to retrieve the value previously bound to an identifier. But what do these new instructions look like?

The main task when implementing bindings is to have the identifiers correctly resolve to the values they were previously bound to. If you can pass around the identifiers when executing the code – like we did in our evaluator – that’s not much of challenge. You can, for example, use the identifiers as keys to a map in which you store and retrieve the values. But we can’t.

We’re not in our evaluator anymore. We’re now working with bytecode and we can’t just pass around identifiers in bytecode – the operands to our opcodes are integers. How do we then represent the identifier in these new instructions? And, how do we reference the value that should be bound to the identifier?

The answer to the second question consists of two words, so let’s start with that one. Here it comes: the stack. Yep, that’s it, we don’t need more than that. We don’t need to explicitly reference the value we want to bind – we have a stack machine! We can just push the value on to the stack and tell the VM: “now bind the topmost stack element to this identifier”. That fits in beautifully with the rest of our instruction set.

Back to the first question: how do we represent identifiers in our bytecode when we can only use numbers as operands? The answer is hidden in the question itself: we’ll use numbers to represent identifiers. Let me explain that with a bit of Monkey code:

let x = 33;
let y = 66;
let z = x + y;

While compiling this we’ll assign a new, unique number to each identifier we come across. In case we’ve seen the identifier before, we’ll reuse the previously assigned number. How do we generate a new number? We’ll keep it simple and just use increasing numbers, starting with 0. In this example, x would be assigned the 0, y the 1 and z would be assigned the 2.

We’ll also define the two new opcodes we want and call them OpSetGlobal and OpGetGlobal. Both have one 16-bit-wide operand that holds a number: the unique number we previously assigned to an identifier. When we then compile a let statement we’ll emit an OpSetGlobal instruction to create a binding and when we compile an identifier, we’ll emit an OpGetGlobal instruction to retrieve a value. (16 bits for the operand means we’re limited to a maximum of 65536 global bindings – which should be plenty for us and our Monkey programs).

The three Monkey let statements from above would then look like this in bytecode:

That’s the compiler side of things. In the VM we’ll use a slice to implement the creation and retrieval of global bindings. We’ll call this slice our “globals store” and we’ll use the operands of the OpSetGlobal and OpGetGlobal instructions as indexes into it.

When we execute an OpSetGlobal instruction, we’ll read in the operand, pop the topmost value off the stack and save it to the globals store at the index encoded in the operand. To execute an OpGetGlobal instruction we’ll use the operand to retrieve the value from the globals store and push it on to the stack.

Two new opcodes called OpGetGlobal and OpSetGlobal, a mechanism to associate identifiers with numbers while compiling, and a globals store in the VM. Sounds doable, when broken down like this, right?

Of course, things get more complicated once we introduce functions and local variables, but that’s a bridge we’ll cross once we get there. For now, let’s head on over to our compiler.

Compiling Bindings

First up is the definition of the two new opcodes, OpSetGlobal and OpGetGlobal:

// code/code.go

const (
    // [...]

    OpGetGlobal
    OpSetGlobal
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpGetGlobal: {"OpGetGlobal", []int{2}},
    OpSetGlobal: {"OpSetGlobal", []int{2}},
}

Both have a single two-byte operand to hold the unique number of a global binding. Just like we discussed. We can move along and use these new opcodes to write a first compiler test:

// compiler/compiler_test.go

func TestGlobalLetStatements(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `
            let one = 1;
            let two = 2;
            `,
            expectedConstants: []interface{}{1, 2},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpSetGlobal, 1),
            },
        },
        {
            input: `
            let one = 1;
            one;
            `,
            expectedConstants: []interface{}{1},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            let one = 1;
            let two = one;
            two;
            `,
            expectedConstants: []interface{}{1},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpSetGlobal, 1),
                code.Make(code.OpGetGlobal, 1),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Same test setup as before, so let’s talk about what we test in these three test cases. The first one makes sure that a let statement leads to the correct OpSetGlobal instruction being emitted. The second one expects that an identifier resolves to a previous binding by testing for the OpGetGlobal instruction. Note here that the operands of the OpSetGlobal and OpGetGlobal instructions have to match. The third test case asserts that combining the setting and getting of global bindings works, too. Here, too, it’s important that the operands of the instructions match.

We’re going to fix these test cases one after the other, starting with the first one, which isn’t doing so well:

$ go test ./compiler
--- FAIL: TestGlobalLetStatements (0.00s)
 compiler_test.go:361: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpConstant 1\n\
    0009 OpSetGlobal 1\n"
  got =""
FAIL
FAIL    monkey/compiler 0.009s

Looks like we’re not even close. But the reason for the empty result is that Monkey code consists solely of let statements and our compiler currently skips them. We can get better feedback from the test by adding a new case branch to the compiler’s Compile method:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.LetStatement:
        err := c.Compile(node.Value)
        if err != nil {
            return err
        }

    // [...]
    }

    // [...]
}

The first thing we do when we come across a let statement is to compile the expression on the right side of the equal sign. That’s the Value that will be bound to a name and compiling this expression means instructing the VM to put the value on to the stack:

$ go test ./compiler
--- FAIL: TestGlobalLetStatements (0.00s)
 compiler_test.go:361: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpConstant 1\n\
    0009 OpSetGlobal 1\n"
  got ="0000 OpConstant 0\n0003 OpConstant 1\n"
FAIL
FAIL    monkey/compiler 0.009s

Now we can bind it to a name. That means we need to follow up with an OpSetGlobal instruction that tells the VM to create the binding. But which number do we choose for our identifier? The answer comes from a new component we’re going to add to our compiler, a symbol table.

Introducing: the Symbol Table

A symbol table is a data structure used in interpreters and compilers to associate identifiers with information. It can be used in every phase, from lexing to code generation, to store and retrieve information about a given identifier (which can be called a symbol). Information such as its location, its scope, whether it was previously declared or not, of which type the associated value is, and anything else that seems useful while interpreting or compiling.

We’re going to use as symbol table to associate identifiers with a scope and a unique number. For now, it should do two things:

Associate identifiers in the global scope with a unique number

Get the previously associated number for a given identifier

The common names for these two methods on a symbol table are “define” and “resolve”. You “define” an identifier in a given scope to associate some information with it. Later you “resolve” the identifier to this information. The information itself we’ll call the “symbol” – an identifier is associated with a symbol and the symbol itself is what contains information.

Working code helps to explain this. Here are the type definitions that make up our symbol table:

// compiler/symbol_table.go

package compiler

type SymbolScope string

const (
    GlobalScope SymbolScope = "GLOBAL"
)

type Symbol struct {
    Name  string
    Scope SymbolScope
    Index int
}

type SymbolTable struct {
    store          map[string]Symbol
    numDefinitions int
}

func NewSymbolTable() *SymbolTable {
    s := make(map[string]Symbol)
    return &SymbolTable{store: s}
}

The first definition here is that of SymbolScope, a type alias for string. The value of a SymbolScope itself is not important. What’s important is that it’s unique, because we need to differentiate between different scopes. We use strings as the aliased type (as opposed to an integer, for example) for a better debugging experience.

We then define our first scope, GlobalScope. In the coming chapters we’ll add more.

The next definition is that of Symbol. A Symbol is a struct that holds all the necessary information about a symbol we encounter in Monkey code: the Name, the Scope and the Index. Not much more to explain here.

The SymbolTable itself then associates strings with Symbols in its store and keeps track of the numDefinitions it has. The strings are the identifiers we come across in the Monkey code.

The names of the types and fields can feel unfamiliar, if you haven’t used a symbol table before, but worry not: we’re building a map that associates strings with information about them. There is no hidden wisdom or trick you need to wrap your head around. Tests make this much clearer by demonstrating what we expect from the missing Define and Resolve methods of the SymbolTable:

// compiler/symbol_table_test.go

package compiler

import "testing"

func TestDefine(t *testing.T) {
    expected := map[string]Symbol{
        "a": Symbol{Name: "a", Scope: GlobalScope, Index: 0},
        "b": Symbol{Name: "b", Scope: GlobalScope, Index: 1},
    }

    global := NewSymbolTable()

    a := global.Define("a")
    if a != expected["a"] {
        t.Errorf("expected a=%+v, got=%+v", expected["a"], a)
    }

    b := global.Define("b")
    if b != expected["b"] {
        t.Errorf("expected b=%+v, got=%+v", expected["b"], b)
    }
}

func TestResolveGlobal(t *testing.T) {
    global := NewSymbolTable()
    global.Define("a")
    global.Define("b")

    expected := []Symbol{
        Symbol{Name: "a", Scope: GlobalScope, Index: 0},
        Symbol{Name: "b", Scope: GlobalScope, Index: 1},
    }

    for _, sym := range expected {
        result, ok := global.Resolve(sym.Name)
        if !ok {
            t.Errorf("name %s not resolvable", sym.Name)
            continue
        }
        if result != sym {
            t.Errorf("expected %s to resolve to %+v, got=%+v",
                sym.Name, sym, result)
        }
    }
}

In TestDefine we make assertions about the Define method. It should take an identifier as argument, create a definition and return the Symbol. Note that we don’t have to say in which scope we want to create the definition. It’s the job of the symbol table to keep track of that for us. We only call Define("a") and the symbol table associates the identifier "a" with a new Symbol, that contains the Name, the Scope and the Index. The Index is the unique number we’re after.

In TestResolveGlobal we do the reverse: we hand the symbol table an identifier that was previously defined and expect it to return the associated Symbol. Again, the only argument is the identifier: Resolve("a"). If the identifier is undefined, the second return value of Resolve has to be false.

The tests don’t compile, because both methods are missing and I’m going to spare you from reading through the results of running the tests repeatedly while adding the method definition step by step. Instead, let me give you the full version of Define:

// compiler/symbol_table.go

func (s *SymbolTable) Define(name string) Symbol {
    symbol := Symbol{Name: name, Index: s.numDefinitions, Scope: GlobalScope}
    s.store[name] = symbol
    s.numDefinitions++
    return symbol
}

I told you, there’s nothing to worry about; we’re building a map with some additional features. Here’s the evidence. We create a new Symbol, associate it with the name in our store, increase the numDefinitions counter and return the new Symbol. Defined. Done.

The Resolve method is even simpler:

// compiler/symbol_table.go

func (s *SymbolTable) Resolve(name string) (Symbol, bool) {
    obj, ok := s.store[name]
    return obj, ok
}

Sadly, this method won’t stay that small. As we add more scopes in the future, it’ll grow, but for now, what it does is enough: both tests pass.

$ go test -run TestDefine ./compiler
ok      monkey/compiler 0.008s
$ go test -run TestResolveGlobal ./compiler
ok      monkey/compiler 0.011s

Using Symbols in the Compiler

We had to selectively run the TestDefine and TestResolveGlobal functions to get an "ok" because our compiler test is still failing. Now though, armed with our symbol table, we can make it pass! First we need to add the symbol table to the compiler:

// compiler/compiler.go

type Compiler struct {
    // [...]

    symbolTable *SymbolTable
}

func New() *Compiler {
    return &Compiler{
        // [...]
        symbolTable:  NewSymbolTable(),
    }
}

That allows us to define the identifiers in *ast.LetStatements:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.LetStatement:
        err := c.Compile(node.Value)
        if err != nil {
            return err
        }
        symbol := c.symbolTable.Define(node.Name.Value)

    // [...]
    }

    // [...]
}

node.Name is the *ast.Identifier on the left side of the let statement’s equal sign. And node.Name.Value holds the string representation of that identifier. We pass it to the symbol table’s Define method and thus define it in the GlobalScope. The returned symbol now has a Name, a Scope and, most importantly, an Index.

We can now use that Index as operand of a OpSetGlobal instruction and emit that:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.LetStatement:
        err := c.Compile(node.Value)
        if err != nil {
            return err
        }
        symbol := c.symbolTable.Define(node.Name.Value)
        c.emit(code.OpSetGlobal, symbol.Index)

    // [...]
    }

    // [...]
}

With that we just took a huge step towards our goal:

$ go test ./compiler
--- FAIL: TestGlobalLetStatements (0.00s)
 compiler_test.go:361: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpGetGlobal 0\n\
    0009 OpPop\n"
  got ="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpPop\n"
FAIL
FAIL    monkey/compiler 0.011s

Now we’re talki– wait a second! The test is still failing? No, this is the second test case. The first one is passing! What’s failing now is the test case that makes sure resolving a global binding works.

Instead of defining an identifier and emitting an OpSetGlobal instruction we now have to do the opposite. When we come across an *ast.Identifier we need to check with our symbol table whether the identifier was previously used as part of a let statement and if so, we need to emit an OpGetGlobal instruction with the correct operand. “Correct” here means that the operand holds the same number that was used in the previously emitted OpSetGlobal instruction. We can manage that, can’t we?

First we have to tell the compiler about *ast.Identifiers. It should try to resolve the identifier at hand with the symbol table:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.Identifier:
        symbol, ok := c.symbolTable.Resolve(node.Value)
        if !ok {
            return fmt.Errorf("undefined variable %s", node.Value)
        }

    // [...]
    }

    // [...]
}

We take the Value of the *ast.Identifier and ask the symbol table whether it can Resolve it. If not, we return an error. Looks just like any other map access in Go, doesn’t it? But I want you to note that this is a compile time error! Previously, in our evaluator, we could only determine whether a variable was defined or not at run time, while executing the Monkey program. Now we can throw an error before we pass bytecode to the VM. Pretty cool, isn’t it?

In case the identifier can be resolved we have the symbol at hand and can use it to emit the OpGetGlobal instruction:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.Identifier:
        symbol, ok := c.symbolTable.Resolve(node.Value)
        if !ok {
            return fmt.Errorf("undefined variable %s", node.Value)
        }

        c.emit(code.OpGetGlobal, symbol.Index)

    // [...]
    }

    // [...]
}

The operand matches the one used in the OpSetGlobal instruction, the Index associated with the symbol. Our symbol table took care of that. That means the VM does not have to worry about identifiers at all but can just concentrate on storing and retrieving values using this Index. In other words:

$ go test ./compiler
ok      monkey/compiler 0.008s

We did it! We can now use let statements to bind values to an identifier and later use the identifier to get to that value – at least in our compiler.

Adding Globals to the VM

Let me be upfront about this and say that the hardest part is over. We’ve added support for the OpSetGlobal and OpGetGlobal instructions to our compiler and doing the same for VM takes far less effort. It’s fun, though, because writing tests for the VM and making them pass is fun:

// vm/vm_test.go

func TestGlobalLetStatements(t *testing.T) {
    tests := []vmTestCase{
        {"let one = 1; one", 1},
        {"let one = 1; let two = 2; one + two", 3},
        {"let one = 1; let two = one + one; one + two", 3},
    }

    runVmTests(t, tests)
}

In these test cases we create one or two global bindings and then try to resolve the previously bound identifiers to their values. The result should land on the stack, where we can test for it. Alas, it blows up in our face:

$ go test ./vm
--- FAIL: TestGlobalLetStatements (0.00s)
panic: runtime error: index out of range [recovered]
 panic: runtime error: index out of range

goroutine 21 [running]:
testing.tRunner.func1(0xc4200c83c0)
 /usr/local/go/src/testing/testing.go:742 +0x29d
panic(0x111a5a0, 0x11f3fe0)
 /usr/local/go/src/runtime/panic.go:502 +0x229
monkey/vm.(*VM).Run(0xc420050eb8, 0x800, 0x800)
 /Users/mrnugget/code/05/src/monkey/vm/vm.go:47 +0x47c
monkey/vm.runVmTests(0xc4200c83c0, 0xc420073f38, 0x3, 0x3)
 /Users/mrnugget/code/05/src/monkey/vm/vm_test.go:115 +0x3c1
monkey/vm.TestGlobalLetStatements(0xc4200c83c0)
 /Users/mrnugget/code/05/src/monkey/vm/vm_test.go:94 +0xb5
testing.tRunner(0xc4200c83c0, 0x114b5b8)
 /usr/local/go/src/testing/testing.go:777 +0xd0
created by testing.(*T).Run
 /usr/local/go/src/testing/testing.go:824 +0x2e0
FAIL    monkey/vm   0.011s

We’ve seen this before. The VM doesn’t know how to handle the new opcodes and skips them. But since it doesn’t know how far it has to skip in order to jump over the operands, it ends up trying to decode the operands as opcodes. That leads to this nonsense here.

Before we clean that up, though, and properly decode and execute OpSetGlobal and OpGetGlobal instructions, we need a place to store globals.

Since the operand of both opcodes is 16 bits wide, we have an upper limit on the number of global bindings our VM can support. That’s good, because a limit allows us to pre-allocate all the memory we will use:

// vm/vm.go

const GlobalsSize = 65536

type VM struct {
// [...]

    globals []object.Object
}

func New(bytecode *compiler.Bytecode) *VM {
    return &VM{
// [...]

        globals: make([]object.Object, GlobalsSize),
    }
}

This new globals field of VM is the “globals store”. We use a slice as the underlying data structure, because it gives us direct index-based access to single elements without any overhead.

Now we can implement OpSetGlobal:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpSetGlobal:
            globalIndex := code.ReadUint16(vm.instructions[ip+1:])
            ip += 2

            vm.globals[globalIndex] = vm.pop()

        // [...]
        }
    // [...]
}

The first thing we do is decode the operand, globalIndex, and increment the VM’s instruction pointer, ip, by two bytes. Then we pop the top element off the stack, which is the value that should be bound to a name, and save it to the new globals store under the specified index. There it’s easy to retrieve when we need to push it on to the stack again:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpGetGlobal:
            globalIndex := code.ReadUint16(vm.instructions[ip+1:])
            ip += 2

            err := vm.push(vm.globals[globalIndex])
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

Again, we decode the operand, globalIndex, and increment the ip. Then we fetch the value from vm.globals and push it back on to the stack. Gone is the panic:

$ go test ./vm
ok      monkey/vm   0.030s

Instead, we get an enthusiastic "ok" to let us know us that we successfully taught our compiler and our VM to handle global let statements. Look at this:

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> let a = 1;
1
>> let b = 2;
2
>> let c = a + b;
Woops! Compilation failed:
 undefined variable a
>>

What? This is tested behaviour, why doesn’t it work in the REPL? Ah! Of course! In our REPL we create a new compiler and a new VM in each iteration of its main loop. That means we also create a new symbol table and a new globals store every time we type a new line. Easy to fix.

All we need are new constructor functions for our compiler and VM that allow us to keep global state in the REPL:

// compiler/compiler.go

func NewWithState(s *SymbolTable, constants []object.Object) *Compiler {
    compiler := New()
    compiler.symbolTable = s
    compiler.constants = constants
    return compiler
}

This new constructor for Compiler now accepts a *SymbolTable and an []object.Object slice containing the constants of a previous compilation. In order to get out of our current predicament we would only need the *SymbolTable, but soon we’d run into errors where the line that was just typed into the REPL would need to access the constants that were previously entered. This is the correct and future-proof approach.

Yes, we create duplicate allocations. We first call New() in this new constructor and then throw away the symbol table and constants slice it allocated by overwriting them. That’s fine, I think. Especially for our use case, the REPL. It’s not a problem for Go’s GC and when compared to the effort needed to implement it without those allocations, it’s the most efficient approach.

Here is the new constructor for the VM:

// vm/vm.go

func NewWithGlobalsStore(bytecode *compiler.Bytecode, s []object.Object) *VM {
    vm := New(bytecode)
    vm.globals = s
    return vm
}

Now we need to modify the main loop of our REPL so it keeps the global state around – the globals store, the symbol table, the constants – and passes it to new instances of the compiler and the VM:

// repl/repl.go

import (
    // [...]
    "monkey/object"
    // [...]
)

func Start(in io.Reader, out io.Writer) {
    scanner := bufio.NewScanner(in)

    constants := []object.Object{}
    globals := make([]object.Object, vm.GlobalsSize)
    symbolTable := compiler.NewSymbolTable()

    for {
        // [...]

        comp := compiler.NewWithState(symbolTable, constants)
        err := comp.Compile(program)
        if err != nil {
            fmt.Fprintf(out, "Woops! Compilation failed:\n %s\n", err)
            continue
        }

        code := comp.Bytecode()
        constants = code.Constants

        machine := vm.NewWithGlobalsStore(code, globals)
        // [...]
    }
}

We allocate a slice for constants, a globals store and a symbolTable. Then, in each iteration of the loop, we pass the symbolTable and the constants to the compiler, so it continues its work, rather than beginning anew. After the compiler is done, we update the constants reference. That’s necessary because the compiler uses append internally and our previously allocated constants slice is not what comes out the other end. Since the constants are included in the bytecode, we don’t need to explicitly pass them to the VM’s constructor, but just the globals.

Now we have global state in the REPL, which allows us to treat each line entered into it as a part of one program, even though we start the compilation and execution process every time we hit return. Problem fixed. We can now play around with global bindings in the REPL:

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> let a = 1;
1
>> let b = 2;
2
>> let c = a + b;
3
>> c
3

It’s time to lean back and take a big breath, because in the upcoming chapters we’ll build upon and combine everything we’ve done so far. It’s going to be amazing.

String, Array and Hash

In their current form our compiler and VM only support three of Monkey’s data types: integers, booleans and null. But there are three more: strings, arrays and hashes. We implemented all of them in the previous book and now it’s time for us to also add them to our new Monkey implementation.

That doesn’t mean we have to redo all of what we did in Writing An Interpreter In Go. The object system representations of the data types are still there – object.String, object.Array and object.Hash – and we can reuse them, which means we can concentrate on the novel parts of the implementation.

The goal for this chapter is to add the string, array and hash data types to the compiler and the VM so that, in the end, we can execute this piece of Monkey code:

[1, 2, 3][1]
// => 2

{"one": 1, "two": 2, "three": 3}["o" + "ne"]
// => 1

As you can see, besides adding support for literals and the data types themselves, we also need to implement string concatenation and the index operator for arrays and hashes to get this snippet working.

We’re going to start by implementing support for object.String.

String

Since the value of string literals doesn’t change between compile and run time, we can treat them as constant expressions. Similar to our implementation of integer literals, we can turn them into *object.String at compile time and add them to the constant pool in compiler.Bytecode.

From integer literals we also know that this doesn’t take more than a handful of lines of code in the compiler. So why not keep things challenging? Instead of only implementing string literals, we’ll also make it a goal for this section to implement string concatenation, which allows us to concatenate two strings with the + operator.

Our first compiler test in this chapter expects both to work:

// compiler/compiler_test.go

func TestStringExpressions(t *testing.T) {
    tests := []compilerTestCase{
        {
            input:             `"monkey"`,
            expectedConstants: []interface{}{"monkey"},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input:             `"mon" + "key"`,
            expectedConstants: []interface{}{"mon", "key"},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpAdd),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

The first of these two test cases makes sure that the compiler knows how to treat string literals as constants; the second test asserts that it’s possible to concatenate them with the + infix operator.

Of note is that we do not expect any new opcodes. We already have those we need in place: we have an opcode to load a constant expression on to the stack, OpConstant, and we have an opcode to add two things together: OpAdd.

The usage of both opcodes is also unchanged. The operand of OpConstant is still the index of the constant in the constant pool and OpAdd still expects its two operands to sit on top of the stack – it doesn’t matter if those are *object.Integers or *object.Strings.

What’s new is that we now expect strings in the constant pool. That means we need to test that the bytecode.Constants contains the correct *object.Strings and in order to do that, we need to add another case branch to the testConstants function:

// compiler/compiler_test.go

func testConstants(
    t *testing.T,
    expected []interface{},
    actual []object.Object,
) error {
    // [...]

    for i, constant := range expected {
        switch constant := constant.(type) {
        // [...]

        case string:
            err := testStringObject(constant, actual[i])
            if err != nil {
                return fmt.Errorf("constant %d - testStringObject failed: %s",
                    i, err)
            }
        }
    }

    return nil
}

func testStringObject(expected string, actual object.Object) error {
    result, ok := actual.(*object.String)
    if !ok {
        return fmt.Errorf("object is not String. got=%T (%+v)",
            actual, actual)
    }

    if result.Value != expected {
        return fmt.Errorf("object has wrong value. got=%q, want=%q",
            result.Value, expected)
    }

    return nil
}

The new case string branch in testConstants is accompanied by the new testStringObject function, which mirrors the existing testIntegerObject and makes sure that the constants are the strings we expect them to be.

When we now run the tests, we can see that the expected constants are not the issue (yet), but the instructions are:

$ go test ./compiler
--- FAIL: TestStringExpressions (0.00s)
 compiler_test.go:410: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpPop\n"
  got ="0000 OpPop\n"
FAIL
FAIL    monkey/compiler 0.009s

It’s not like we didn’t expect that. We need to emit OpConstant instructions when compiling string literals. To do that, we have to change the Compile method of the compiler to handle *ast.StringLiterals and create *object.String out of them:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.StringLiteral:
        str := &object.String{Value: node.Value}
        c.emit(code.OpConstant, c.addConstant(str))

    // [...]
    }

    // [...]
}

Except for one variable name and one identifier, this is a copy of the case branch for *ast.IntegerLiterals. We take the value out of the AST node, we create an object, and we add it to the constant pool.

A step into the right direction:

$ go test ./compiler
ok      monkey/compiler 0.009s

Sweet, both tests pass. And notice that we didn’t have to do anything special to emit the OpAdd instruction for the concatenation to work. The compiler already takes care of *ast.InfixExpressions by compiling their Left and Right nodes. In the test case these are *ast.StringLiterals, which we can now successfully compile.

Next, we write a test for the VM to make sure that the same Monkey code can be executed by the VM once it’s compiled to bytecode instructions:

// vm/vm_test.go

func TestStringExpressions(t *testing.T) {
    tests := []vmTestCase{
        {`"monkey"`, "monkey"},
        {`"mon" + "key"`, "monkey"},
        {`"mon" + "key" + "banana"`, "monkeybanana"},
    }

    runVmTests(t, tests)
}

These test cases are the same as in the compiler test, except for the additional assertion that adding more than two strings together should also work – because why not?

Here, too, we need a new testStringObject helper function to make sure that it’s *object.Strings that end up on the VM’s stack. It’s also a copy of its testIntegerObject counterpart and makes sure that the strings produced by the VM are the ones we expect:

// vm/vm_test.go

func testExpectedObject(
    t *testing.T,
    expected interface{},
    actual object.Object,
) {
    t.Helper()

    switch expected := expected.(type) {
    // [...]

    case string:
        err := testStringObject(expected, actual)
        if err != nil {
            t.Errorf("testStringObject failed: %s", err)
        }

    }
}

func testStringObject(expected string, actual object.Object) error {
    result, ok := actual.(*object.String)
    if !ok {
        return fmt.Errorf("object is not String. got=%T (%+v)",
            actual, actual)
    }

    if result.Value != expected {
        return fmt.Errorf("object has wrong value. got=%q, want=%q",
            result.Value, expected)
    }

    return nil
}

Running the tests shows us that loading strings on to the stack is already working fine, but concatenation is not:

$ go test ./vm
--- FAIL: TestStringExpressions (0.00s)
 vm_test.go:222: vm error:\
   unsupported types for binary operation: STRING STRING
FAIL
FAIL    monkey/vm   0.029s

Technically speaking, this could have been working without us doing anything. We could have made our previous implementation of OpAdd in the VM so generic that it would work with any object.Object that has an Add method, or something like that. But we didn’t. Instead, we added type checks to be explicit about which data type we support and which not. Now we have to extend the check:

// vm/vm.go

func (vm *VM) executeBinaryOperation(op code.Opcode) error {
    right := vm.pop()
    left := vm.pop()

    leftType := left.Type()
    rightType := right.Type()

    switch {
    case leftType == object.INTEGER_OBJ && rightType == object.INTEGER_OBJ:
        return vm.executeBinaryIntegerOperation(op, left, right)
    case leftType == object.STRING_OBJ && rightType == object.STRING_OBJ:
        return vm.executeBinaryStringOperation(op, left, right)
    default:
        return fmt.Errorf("unsupported types for binary operation: %s %s",
            leftType, rightType)
    }
}

func (vm *VM) executeBinaryStringOperation(
    op code.Opcode,
    left, right object.Object,
) error {
    if op != code.OpAdd {
        return fmt.Errorf("unknown string operator: %d", op)
    }

    leftValue := left.(*object.String).Value
    rightValue := right.(*object.String).Value

    return vm.push(&object.String{Value: leftValue + rightValue})
}

In executeBinaryOperation the conditional has been changed into a switch statement with a new case branch for strings. There, we delegate the actual adding of two strings to executeBinaryStringOperation, which unwraps the *object.Strings, concatenates the underlying Go strings and pushes the result back on to the VM’s stack.

And that’s it:

$ go test ./vm
ok      monkey/vm   0.028s

Monkey strings are now fully implemented, including string concatenation. Next up: arrays.

Array

Arrays are the first composite data type we’re adding to this Monkey implementation. That means, roughly speaking, arrays are composed out of other data types. The practical consequence for us is that we can’t treat array literals as constant expressions.

Since an array is made up of multiple elements and an array literal consists of multiple expressions that produce these elements, the value of the array literal itself might change between compile and run time. Here’s an example:

[1 + 2, 3 + 4, 5 + 6]

Don’t be distracted by these integer expressions. They’re so simple, an optimizing compiler could pre-compute them, yes, but the point is that these could be any type of expression – integer literal, string concatenation, function literal, function call, and so on. Only at run time can we reliably determine what they evaluate to.

Coming from integer and string literals, we now have to change our approach a tiny bit. Instead of building an array at compile time and passing it to the VM in the constant pool, we’ll instead tell the VM how to build it on its own.

To that end, we define a new opcode, called OpArray, with one operand: the number of elements in an array literal. When we then compile an *ast.ArrayLiteral, we first compile all of its elements. Since these are ast.Expressions, compiling them results in instructions that leave N values on the VM’s stack, where N is the number of elements in the array literal. Then, we’re going to emit an OpArray instruction with the operand being N, the number of elements. Compilation done.

When the VM then executes the OpArray instruction it takes the N elements off the stack, builds an *object.Array out of them, and pushes that on to the stack. Done. We told the VM how to build an array.

Let’s put this plan right into practice. Here is the definition of OpArray:

// code/code.go

const (
    // [...]

    OpArray
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpArray: {"OpArray", []int{2}},
}

The single operand is two bytes wide. That gives us 65535 as the highest possible number of elements in an array literal. If you have a Monkey program that needs more than that, please let me know.

Before we translate our plan for this new opcode into compiler code, we need to write a test, as always:

// compiler/compiler_test.go

func TestArrayLiterals(t *testing.T) {
    tests := []compilerTestCase{
        {
            input:             "[]",
            expectedConstants: []interface{}{},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpArray, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "[1, 2, 3]",
            expectedConstants: []interface{}{1, 2, 3},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpArray, 3),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "[1 + 2, 3 - 4, 5 * 6]",
            expectedConstants: []interface{}{1, 2, 3, 4, 5, 6},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpAdd),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpConstant, 3),
                code.Make(code.OpSub),
                code.Make(code.OpConstant, 4),
                code.Make(code.OpConstant, 5),
                code.Make(code.OpMul),
                code.Make(code.OpArray, 3),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

This is also a translation of our plan, only it’s expressed in assertions, not yet in working code. We expect the compiler to compile the elements in the array literal into instructions that leave values on the stack and we expect it to emit an OpArray instruction with the operand being the number of elements in the array literal.

Unsurprisingly, that doesn’t happen yet:

$ go test ./compiler
--- FAIL: TestArrayLiterals (0.00s)
 compiler_test.go:477: testInstructions failed: wrong instructions length.
  want="0000 OpArray 0\n0003 OpPop\n"
  got ="0000 OpPop\n"
FAIL
FAIL    monkey/compiler 0.009s

Thankfully, the fix for this test is not much longer than the prose necessary to explain it:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.ArrayLiteral:
        for _, el := range node.Elements {
            err := c.Compile(el)
            if err != nil {
                return err
            }
        }

        c.emit(code.OpArray, len(node.Elements))

    // [...]
    }

    // [...]
}

Just like we planned:

$ go test ./compiler
ok      monkey/compiler 0.011s

The next part of our plan includes the VM, where we need to implement OpArray, too. We start with a test:

// vm/vm_test.go

func TestArrayLiterals(t *testing.T) {
    tests := []vmTestCase{
        {"[]", []int{}},
        {"[1, 2, 3]", []int{1, 2, 3}},
        {"[1 + 2, 3 * 4, 5 + 6]", []int{3, 12, 11}},
    }

    runVmTests(t, tests)
}

func testExpectedObject(
    t *testing.T,
    expected interface{},
    actual object.Object,
) {
    t.Helper()

    switch expected := expected.(type) {
    // [...]

    case []int:
        array, ok := actual.(*object.Array)
        if !ok {
            t.Errorf("object not Array: %T (%+v)", actual, actual)
            return
        }

        if len(array.Elements) != len(expected) {
            t.Errorf("wrong num of elements. want=%d, got=%d",
                len(expected), len(array.Elements))
            return
        }

        for i, expectedElem := range expected {
            err := testIntegerObject(int64(expectedElem), array.Elements[i])
            if err != nil {
                t.Errorf("testIntegerObject failed: %s", err)
            }
        }

    }
}

The Monkey code in these test cases is exactly the same as in the compiler test. Here, though, it’s even more important to make sure that an empty array literal works, because it’s far easier to run into an off-by-one error in the VM than in the compiler.

And to make sure that an *object.Array is what ends up on the VM’s stack, we extend the testExpectedObject with a new case []int branch that turns our expected []int slices into expectations about an *object.Array.

Neat and reusable! I like it. The bad news is that if we run the tests, we don’t get a helpful error message, but a panic – I’ll spare you the stack trace. The reason the VM panics is because it doesn’t know about OpArray and its operand yet, and interprets the operand as another instruction. Nonsense guaranteed.

But regardless of whether we get a panic or a nice, readable error message from a failing test, it’s clear that we have to implement OpArray in the VM. Decode the operand, take the specified number of elements off the stack, construct an *object.Array, push it back on to the stack. We can do all of that with one case branch and one method:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpArray:
            numElements := int(code.ReadUint16(vm.instructions[ip+1:]))
            ip += 2

            array := vm.buildArray(vm.sp-numElements, vm.sp)
            vm.sp = vm.sp - numElements

            err := vm.push(array)
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

func (vm *VM) buildArray(startIndex, endIndex int) object.Object {
    elements := make([]object.Object, endIndex-startIndex)

    for i := startIndex; i < endIndex; i++ {
        elements[i-startIndex] = vm.stack[i]
    }

    return &object.Array{Elements: elements}
}

The case branch for code.OpArray takes care of decoding the operand, incrementing the ip and telling the new buildArray method where it can find the array elements on the stack.

buildArray then iterates through the elements in the specified section of the stack, adding each to a newly-built *object.Array. This array is then pushed on to the stack, but only – and this is important – after the elements have been taken off. What we end up with is an *object.Array sitting on the stack, containing the specified number of elements:

$ go test ./vm
ok      monkey/vm   0.031s

Alright! Another one in the bag: we’ve fully implemented array literals!

Hash

In order to implement Monkey’s hash data structure we again need a new opcode. Just like an array, its final value can’t be determined at compile time. Doubly so, actually, because instead of having N elements, a hash in Monkey has N keys and N values and all of them are created by expressions:

{1 + 1: 2 * 2, 3 + 3: 4 * 4}

That’s equivalent to this hash literal:

{2: 4, 6: 16}

You and me, we wouldn’t write the first version, I know that, but we still need to make it work. To do that, we follow the same strategy we used for array literals: teaching the VM how to build hash literals.

And again, our first step is to define a new opcode. This one is called OpHash and also has one operand:

// code/code.go

const (
    // [...]

    OpHash
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpHash:  {"OpHash", []int{2}},
}

The operand specifies the number of keys and values sitting on the stack. It’s equally feasible to use the number of pairs, but then we’d have to double it in the VM to get the number of values sitting on the stack. If we can pre-calculate that in the compiler, why not?

With the operand the VM can take the correct number of elements off the stack, create object.HashPairs out of them and build an *object.Hash, which it pushes on to the stack. Again, that’s the DIY strategy we used for our implementation of Monkey’s array, except that building the *object.Hash is slightly more elaborate.

Before we get to that, though, we first need to write a test to make sure our compiler can output OpHash instructions:

// compiler/compiler_test.go

func TestHashLiterals(t *testing.T) {
    tests := []compilerTestCase{
        {
            input:             "{}",
            expectedConstants: []interface{}{},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpHash, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "{1: 2, 3: 4, 5: 6}",
            expectedConstants: []interface{}{1, 2, 3, 4, 5, 6},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpConstant, 3),
                code.Make(code.OpConstant, 4),
                code.Make(code.OpConstant, 5),
                code.Make(code.OpHash, 6),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "{1: 2 + 3, 4: 5 * 6}",
            expectedConstants: []interface{}{1, 2, 3, 4, 5, 6},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpAdd),
                code.Make(code.OpConstant, 3),
                code.Make(code.OpConstant, 4),
                code.Make(code.OpConstant, 5),
                code.Make(code.OpMul),
                code.Make(code.OpHash, 4),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

That looks like a lot of bytecode, but that’s mainly due to the expressions in the hash literals. We want to be sure that they’re compiled correctly, with the resulting instructions leaving a value on the stack. After that, we expect an OpHash instruction with the operand specifying the number of keys and values sitting on the stack.

The tests fails and tell us that we’re missing OpHash instructions:

$ go test ./compiler
--- FAIL: TestHashLiterals (0.00s)
 compiler_test.go:336: testInstructions failed: wrong instructions length.
  want="0000 OpHash 0\n0003 OpPop\n"
  got ="0000 OpPop\n"
FAIL
FAIL    monkey/compiler 0.009s

As I said, building *object.Hashes in the VM takes a little more effort than building *object.Arrays. But compiling them also requires a little trick to work reliably:

// compiler/compiler.go

import (
    // [...]
    "sort"
)

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.HashLiteral:
        keys := []ast.Expression{}
        for k := range node.Pairs {
            keys = append(keys, k)
        }
        sort.Slice(keys, func(i, j int) bool {
            return keys[i].String() < keys[j].String()
        })

        for _, k := range keys {
            err := c.Compile(k)
            if err != nil {
                return err
            }
            err = c.Compile(node.Pairs[k])
            if err != nil {
                return err
            }
        }

        c.emit(code.OpHash, len(node.Pairs)*2)

    // [...]
    }

    // [...]
}

Since node.Pairs is a map[ast.Expression]ast.Expression and Go does not guarantee a consistent order when iterating through the keys and values of a map, we need to manually sort the keys before we can compile them. If we didn’t do that, the emitted instructions would be in random order.

That’s not an issue per se and, in fact, our compiler and VM would work fine without the sorting. Our tests, though, would break randomly. They have assertions about the constants in a certain order. Not for order’s sake, of course, but because we want to make sure we have the right ones.

In order to stop our tests’ success rate from depending on the mercy of randomness, we need to guarantee a specific arrangement of elements by sorting the keys first. Since we don’t really care about which order exactly, as long there is one, we sort them by their String representation.

After that, we iterate through the keys, compile them, fetch the corresponding value from node.Pairs and compile that, too. The order of key first and then the value is important, because we’ll need to reconstruct it in the VM.

As the last step in this case branch we emit an OpHash instruction, its operand being the number of keys and values.

When we now run our tests…

$ go test ./compiler
ok      monkey/compiler 0.009s

… we can see that it’s time to move on to the VM.

It’s not hard to build *object.Hashes in the VM, but we need to do a few different things to make it work and it’s good to have tests to rely on:

// vm/vm_test.go

func TestHashLiterals(t *testing.T) {
    tests := []vmTestCase{
        {
            "{}", map[object.HashKey]int64{},
        },
        {
            "{1: 2, 2: 3}",
            map[object.HashKey]int64{
                (&object.Integer{Value: 1}).HashKey(): 2,
                (&object.Integer{Value: 2}).HashKey(): 3,
            },
        },
        {
            "{1 + 1: 2 * 2, 3 + 3: 4 * 4}",
            map[object.HashKey]int64{
                (&object.Integer{Value: 2}).HashKey(): 4,
                (&object.Integer{Value: 6}).HashKey(): 16,
            },
        },
    }

    runVmTests(t, tests)
}

func testExpectedObject(
    t *testing.T,
    expected interface{},
    actual object.Object,
) {
    t.Helper()

    switch expected := expected.(type) {
    // [...]

    case map[object.HashKey]int64:
        hash, ok := actual.(*object.Hash)
        if !ok {
            t.Errorf("object is not Hash. got=%T (%+v)", actual, actual)
            return
        }

        if len(hash.Pairs) != len(expected) {
            t.Errorf("hash has wrong number of Pairs. want=%d, got=%d",
                len(expected), len(hash.Pairs))
            return
        }

        for expectedKey, expectedValue := range expected {
            pair, ok := hash.Pairs[expectedKey]
            if !ok {
                t.Errorf("no pair for given key in Pairs")
            }

            err := testIntegerObject(expectedValue, pair.Value)
            if err != nil {
                t.Errorf("testIntegerObject failed: %s", err)
            }
        }

    }
}

This test and the accompanying new case branch in testExpectedObject not only make sure that the VM knows how to build *object.Hashes, but also give us a refresher of how *object.Hash works.

object.Hash has a Pairs field that contains a map[HashKey]HashPair. A HashKey can be created by calling the HashKey method of an object.Hashable, an interface that *object.String, *object.Boolean and *object.Integer implement. A HashPair then has a Key and a Value field, both containing an object.Object. This is where the real key and the real value are stored. But the HashKey is necessary to have consistent hashing of Monkey objects. Read through the HashKey methods in the object package to get a more detailed refresher of how that works.

We expect the VM to store the correct HashPairs under the correct HashKeys. We do not really care about what gets stored; we mostly care about the how, which is why we use boring integers and why the expected hash in each test case is a map[object.HashKey]int64. That way we can concentrate on finding the correct value under the correct hash key.

When we run the tests now, we run into the same problem we previously faced when running the array test for the first time: a panic. I’ll again refrain from showing you this unsightly mess, but rest assured that its cause, again, is the fact that our VM doesn’t know about OpHash nor its operand yet. Let’s fix that.

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpHash:
            numElements := int(code.ReadUint16(vm.instructions[ip+1:]))
            ip += 2

            hash, err := vm.buildHash(vm.sp-numElements, vm.sp)
            if err != nil {
                return err
            }
            vm.sp = vm.sp - numElements

            err = vm.push(hash)
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

This is also remarkably close to the case branch for OpArray, except that now we’re using the new buildHash to build a hash instead of an array. And buildHash might return an error:

// vm/vm.go

func (vm *VM) buildHash(startIndex, endIndex int) (object.Object, error) {
    hashedPairs := make(map[object.HashKey]object.HashPair)

    for i := startIndex; i < endIndex; i += 2 {
        key := vm.stack[i]
        value := vm.stack[i+1]

        pair := object.HashPair{Key: key, Value: value}

        hashKey, ok := key.(object.Hashable)
        if !ok {
            return nil, fmt.Errorf("unusable as hash key: %s", key.Type())
        }

        hashedPairs[hashKey.HashKey()] = pair
    }

    return &object.Hash{Pairs: hashedPairs}, nil
}

Similar to buildArray, buildHash also takes in the startIndex and endIndex of the elements sitting on the stack. It then iterates through them in pairs, key and value, creating an object.HashPair out of each. For each pair it generates an object.HashKey and adds the pair to hashedPairs. As its final act, it builds the *object.Hash and returns it.

In the case code.OpHash branch of vm.Run this newly built *object.Hash is then pushed on to the stack, but only after the elements have been taken off.

And that’s how our VM builds hashes:

$ go test ./vm
ok      monkey/vm   0.033s

Look at that! We’ve implemented hashes! That completes our implementation of Monkey data types. The only problem is that we can’t really do anything with them yet.

Adding the index operator

As we said at the beginning of the chapter, our goal is to make this piece of Monkey code work:

[1, 2, 3][1]
{"one": 1, "two": 2, "three": 3}["o" + "ne"]

We’re nearly there: we already support array literals, hash literals, and also string concatenation. What we don’t have yet is the index operator, which allows us to retrieve a single element from an array or a hash.

What’s interesting about the index operator is that it’s quite generic. While we only want to use it with arrays and hashes, its syntactic form allows for much more:

<expression>[<expression>]

The data structure being indexed and the index itself can be produced by any expression. And since a Monkey expression can produce any Monkey object that means, on a semantic level, that the index operator can work with any object.Object either as the index or as the indexed data structure.

That’s exactly how we’re going to implement it. Instead of treating the index operator in combination with a specific data structure as a special case, we’ll build a generic index operator into the compiler and VM. The first step, as so often, is to define a new opcode.

It’s called OpIndex and has no operands. Instead, for OpIndex to work, there need to be two values sitting on the top of the stack: the object to be indexed and, above that, the object serving as the index. When the VM executes OpIndex it should take both off the stack, perform the index operation, and put the result back on.

That’s generic enough to allow for arrays and hashes to be used as the indexed data structure, while also being easy to implement, due to its usage of the stack.

Here is the definition of OpIndex:

// code/code.go

const (
    // [...]

    OpIndex
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpIndex: {"OpIndex", []int{}},
}

Now we write a compiler test in which we expect OpIndex instructions:

// compiler/compiler_test.go

func TestIndexExpressions(t *testing.T) {
    tests := []compilerTestCase{
        {
            input:             "[1, 2, 3][1 + 1]",
            expectedConstants: []interface{}{1, 2, 3, 1, 1},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpArray, 3),
                code.Make(code.OpConstant, 3),
                code.Make(code.OpConstant, 4),
                code.Make(code.OpAdd),
                code.Make(code.OpIndex),
                code.Make(code.OpPop),
            },
        },
        {
            input:             "{1: 2}[2 - 1]",
            expectedConstants: []interface{}{1, 2, 2, 1},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpHash, 2),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpConstant, 3),
                code.Make(code.OpSub),
                code.Make(code.OpIndex),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

What we’re making sure of here is that we can compile both array and hash literals as part of an index-operator expression and that the index itself can be any expression.

It’s important to note that the compiler doesn’t have to care about what is being indexed, what the index is or whether or not the whole operation is valid. That’s the job of the VM and also the reason why we don’t have any test cases for empty arrays or non-existent indexes here. All we need to do in the compiler is to compile two expression and emit an OpIndex instruction:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.IndexExpression:
        err := c.Compile(node.Left)
        if err != nil {
            return err
        }

        err = c.Compile(node.Index)
        if err != nil {
            return err
        }

        c.emit(code.OpIndex)

    // [...]
    }

    // [...]
}

We first compile the object being indexed, node.Left, and then the node.Index. Both are ast.Expressions, which means that we don’t have to worry about what they are exactly – other parts of Compile already take care of that:

$ go test ./compiler
ok      monkey/compiler 0.009s

And now we can start to worry about edge cases, because we can move on to the VM and write tests there:

// vm/vm_test.go

func TestIndexExpressions(t *testing.T) {
    tests := []vmTestCase{
        {"[1, 2, 3][1]", 2},
        {"[1, 2, 3][0 + 2]", 3},
        {"[[1, 1, 1]][0][0]", 1},
        {"[][0]", Null},
        {"[1, 2, 3][99]", Null},
        {"[1][-1]", Null},
        {"{1: 1, 2: 2}[1]", 1},
        {"{1: 1, 2: 2}[2]", 2},
        {"{1: 1}[0]", Null},
        {"{}[0]", Null},
    }

    runVmTests(t, tests)
}

Here we can find all the things that didn’t make an appearance in the compiler test: valid indexes, invalid indexes, arrays within arrays, empty hashes, empty arrays – it’s all there and it all needs to work.

The essence is that with a valid index we expect the corresponding element to end up on the stack and in the cases where the index is invalid we expect vm.Null instead:

$ go test ./vm
--- FAIL: TestIndexExpressions (0.00s)
 vm_test.go:400: testIntegerObject failed: object has wrong value.\
   got=1, want=2
 vm_test.go:400: testIntegerObject failed: object has wrong value.\
   got=2, want=3
 vm_test.go:400: testIntegerObject failed: object has wrong value.\
   got=0, want=1
 vm_test.go:404: object is not Null: *object.Integer (&{Value:0})
 vm_test.go:404: object is not Null: *object.Integer (&{Value:99})
 vm_test.go:404: object is not Null: *object.Integer (&{Value:-1})
 vm_test.go:404: object is not Null: *object.Integer (&{Value:0})
 vm_test.go:404: object is not Null: *object.Integer (&{Value:0})
FAIL
FAIL    monkey/vm   0.036s

While these error messages are nice, they’re not what we’re after. What we want is for our VM to decode and execute OpIndex instructions:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpIndex:
            index := vm.pop()
            left := vm.pop()

            err := vm.executeIndexExpression(left, index)
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

The topmost element on the stack is supposed to be the index, so we pop that off first. Then we pop off the left side of the index operator, the object being indexed. Again, it’s important that the order matches the one used in the compiler – you can imagine what happens when we mix it up.

Once we have index and left and are ready to do some indexing, we delegate to executeIndexExpression:

// vm/vm.go

func (vm *VM) executeIndexExpression(left, index object.Object) error {
    switch {
    case left.Type() == object.ARRAY_OBJ && index.Type() == object.INTEGER_OBJ:
        return vm.executeArrayIndex(left, index)
    case left.Type() == object.HASH_OBJ:
        return vm.executeHashIndex(left, index)
    default:
        return fmt.Errorf("index operator not supported: %s", left.Type())
    }
}

That’s close to the executeBinaryOperation method we already have. It performs type checking of the left and index, but also delegates the actual indexing to other methods. The first of these is executeArrayIndex, which does what its name promises:

// vm/vm.go

func (vm *VM) executeArrayIndex(array, index object.Object) error {
    arrayObject := array.(*object.Array)
    i := index.(*object.Integer).Value
    max := int64(len(arrayObject.Elements) - 1)

    if i < 0 || i > max {
        return vm.push(Null)
    }

    return vm.push(arrayObject.Elements[i])
}

If it weren’t for the bounds checking, this method could be much shorter. But we do want to check that the index is within the bounds of the array being indexed – that’s what we expect in our tests. If the index does not match an element in the array, we push Null on to the stack. And if it does match, we push the element.

In executeHashIndex we do not have to do bounds checking, but we have to check whether the given index can be used as an object.HashKey:

// vm/vm.go

func (vm *VM) executeHashIndex(hash, index object.Object) error {
    hashObject := hash.(*object.Hash)

    key, ok := index.(object.Hashable)
    if !ok {
        return fmt.Errorf("unusable as hash key: %s", index.Type())
    }

    pair, ok := hashObject.Pairs[key.HashKey()]
    if !ok {
        return vm.push(Null)
    }

    return vm.push(pair.Value)
}

If the given index can be turned into an object.Hashable, we try to fetch the matching element from hashObject.Pairs. And here, too, we push the element if we were successful and if not, we push vm.Null. That also matches our test expectations.

Let’s take a look at the tests themselves now:

$ go test ./vm
ok      monkey/vm   0.036s

That means, we made it! We’ve reached our goal. We can now successfully execute what we set out to implement:

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> [1, 2, 3][1]
2
>> {"one": 1, "two": 2, "three": 3}["o" + "ne"]
1
>>

We’ve reached the end of the chapter. We can construct strings, arrays, hashes, concatenate strings and now also access elements in our compound data types – but, sadly, no more than that.

In Writing An Interpreter In Go we had additional, built-in functions to perform operations with the data structures: accessing the first and last elements, getting the number of elements, and so on. They are very useful and we’re going implement them in our new Monkey compiler and virtual machine too. But before we can add built-in functions, we need to implement functions.

Functions

This is one of the most demanding chapters in the book. At its end, we’ll have implemented functions and function calls, complete with local bindings and function-call arguments. But to get there, we have to do a lot of thinking and make many tiny changes that look innocent but have great impact on our Monkey implementation. We’ll come across more than one challenge along the way. Because, you see, the problem with implementing functions is this: it’s not just one problem.

The first one is the question of how to represent functions. The naive assumption is that functions are a series of instructions. But in Monkey functions are also first-class citizens that can be passed around and returned from other functions. How do we represent a series of instructions that can be passed around?

Once we answer that, there’s the issue of control flow. How do we get our VM to execute the instructions of a function? And, let’s say, we managed to do that, how do we get it to return back to the instructions it was previously executing? And while we’re at it: how do we get it to pass arguments to functions?

These are the big questions – followed by a myriad of smaller ones, that are hard to ignore. Rest assured, we’ll answer all of them. Just not all at once. Instead, we’re going to weave many different parts into a coherent whole by taking well-considered baby steps, which is also what makes this chapter incredible fun.

Dipping Our Toes: a Simple Function

Our goal for this first section is to “only” get this seemingly-simple piece of Monkey code compiled and executed:

let fivePlusTen = fn() { 5 + 10 };
fivePlusTen();

This function has no parameters. It doesn’t use local bindings. It’s called without arguments and doesn’t access global bindings. While I’d wager that there aren’t many highly-complex Monkey programs in existence, this one is definitely one of the simpler ones. Still, it poses multiple challenges.

Representing Functions

Before we can even think about compiling or executing this function, we run into the first challenge: how do we represent functions?

We know that a function consists of Monkey code. We also know that we compile Monkey code to Monkey bytecode. It follows that our compiler should turn functions into at least a series of Monkey bytecode instructions. The question is, then, where do we store this series of instructions and how do we hand it to the VM?

We already pass the instructions of the main program to the VM, but we can’t just mix those with the instructions of a function. If we did that, we would have to untangle them again in the VM in order to execute them one by one. It’s best to keep them separate from the start.

The answer to our question lies in the fact that Monkey functions are Monkey values. They can be bound to names, returned from other functions, passed to other functions as arguments and much more – just like any other Monkey value. And like other values, they’re also produced by expressions.

These expressions are the function literals, the literal representation of functions in Monkey code. In the example above, the function literal is this part:

fn() { 5 + 10 }

The curious thing about function literals is that the value they produce doesn’t change. Ever. It’s constant. And that’s the last hint we need.

We’ll treat function literals like the other literals that produce constant values and pass them to the VM as – here it comes – constants. We’ll compile them into sequences of instructions and add those to the compiler’s pool of constants. An OpConstant instruction then takes care of putting the compiled function on to the stack – just like any other value.

Now, the remaining question is how to exactly represent these sequences of instructions, so they can be added to the constant pool and loaded on to the stack.

In Writing An Interpreter In Go we defined object.Function, a Monkey object that represents evaluated function literals which itself can be evaluated. Now we need an updated version of that: a function object that holds bytecode instead of AST nodes.

For that, we open up our object package and introduce the new object.CompiledFunction:

// object/object.go

import (
    // [...]
    "monkey/code"
    // [...]
)

const (
    // [...]

    COMPILED_FUNCTION_OBJ = "COMPILED_FUNCTION_OBJ"
)

type CompiledFunction struct {
    Instructions code.Instructions
}

func (cf *CompiledFunction) Type() ObjectType { return COMPILED_FUNCTION_OBJ }
func (cf *CompiledFunction) Inspect() string {
    return fmt.Sprintf("CompiledFunction[%p]", cf)
}

object.CompiledFunction is everything we need: it can hold the code.Instructions we get from the compilation of a function literal and it’s an object.Object, which means we can add it as a constant to our compiler.Bytecode and load it in the VM.

First problem solved. Let’s start thinking about compilation.

Opcodes to Execute Functions

The first question we have to ask ourselves is whether we need new opcodes to achieve our goal of compiling and executing the snippet of Monkey code from above.

Let’s start with what we don’t need: an opcode for function literals. Since we decided to compile them to *object.CompiledFunctions and treat those as constants, they can be loaded on to the stack of the VM with our existing OpConstant instructions.

So, in terms of opcodes, we can cross off the first line of the snippet:

let fivePlusTen = fn() { 5 + 10 };
fivePlusTen();

Once we have compiled the function literal to an *object.CompiledFunction we already know how to bind it to the fivePlusTen name. We have global bindings in place and they work with any object.Object.

But we do need an opcode for the second line: fivePlusTen(). That’s a call expression, represented in our AST by *ast.CallExpression, and it must be compiled to an instruction that tells the VM to execute the function in question.

Since we don’t have an opcode that fits this need, we need to define a new one now. It’s called OpCall and it doesn’t have any operands:

// code/code.go

const (
    // [...]

    OpCall
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpCall: {"OpCall", []int{}},
}

Here’s how it will be used. First, we get the function we want to call on to the stack. For example, with an OpConstant instruction. Then, we issue an OpCall instruction. That tells the VM to execute the function on top of the stack and off we go.

This little instruction manual for OpCall is what’s called a calling convention. Once we add support for function call arguments it will have to change, but for now, it’s just two steps: put the function you want to call on to the stack, issue an OpCall instruction.

With OpCall defined, we are now – in theory – able to get a function on to the stack of our VM and call it. What we still need is a way to tell the VM to return from a called function.

More specifically, we need to differentiate between two cases where the VM has to return from a function. The first case is a function actually returning something, implicitly or explicitly. The second one is when the execution of a function ends without anything being returned, e.g. the function has an empty function body.

Let’s talk about the former case first, the explicit and implicit returning of values. Monkey supports both:

let explicitReturn = fn() { return 5 + 10; };
let implicitReturn = fn() { 5 + 10; };

An explicit return statement stops the execution of the rest of the function and returns the value produced by the expression following the return keyword. In the case above, that’s the infix expression 5 + 10.

Without a return statement, a function call evaluates to the last value produced inside the function. That’s what’s called implicit return.

In the evaluator we built in Writing An Interpreter In Go the implicit returning of values was the default case. Explicit return statements were an additional feature we had to build.

This time, though, the implicit return will be a slight variation of the explicit return. Or, in other words, these two will compile to the same bytecode:

fn() { 5 + 10 }
fn() { return 5 + 10 }

That means, for one, that both implicit and explicit returns are the same under the hood – always a joy to us programmers. But it also means we have to implement both mechanisms in order to get the fivePlusTen function from above compiled and running. No shortcuts, even if we only use implicit returns. But this increased effort in the compiler now will make things a lot easier in the VM later on.

Since they’re both compiled down to the same bytecode, implicit and explicit returns will also be represented by the same opcode. It’s called OpReturnValue and tells the VM to return from the function with a return value:

// code/code.go

const (
    // [...]

    OpReturnValue
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpReturnValue: {"OpReturnValue", []int{}},
}

It doesn’t have any arguments. The value to be returned has to sit on top of the stack.

It’s clear when and how to emit this opcode in the case of explicit returns. First, compile the return statement so the return value will end up on the stack, then emit an OpReturnValue. No puzzles here, just like we want it.

Implementing implicit returning of values takes slightly more effort, since it also means returning the value produced by an expression statement – if it was the last executed statement in a function’s body. But previously we made sure that an expression statement does not leave a value behind. We explicitly emit an OpPop instructions to get rid of it. If we now want to return the value, we need to find a way to combine our need for a clean stack with our desire for implicit returns. But we’ll do, you’ll see. For now, though, put this issue in the back of your mind.

Let’s talk about the second and much rarer case when returning from a function: a function returning nothing. Neither explicitly nor implicitly. Since nearly everything in Monkey is an expression that produces a value, it’s an achievement to even come up with such a function, but they do exist. Here’s one:

fn() { }

That’s a function with an empty body. Compiling it would produce a valid *object.CompiledFunction that can be called, but doesn’t have any instructions. Another example, which we’ll meet later on again, when we talk about local bindings, is this one:

fn() { let a = 1; }

Granted, a function that returns nothing is an edge case. We didn’t even handle it in the first book. But now it sits in front of us, next to an unanswered question: what should these functions produce? Since a function call is an expression and expressions produce values, to be consistent, these functions, too, should produce a value.

We could ignore the whole issue by putting it in a file called undefined_behaviour.txt and calling it a day. We could. Or we could make these functions return *object.Null. Since in Monkey an *object.Null signifies the absence of a value, it does make sense for a function that didn’t produce a value to return it.

Decision made, which means we need to tell our VM to return vm.Null from a function in case it has no OpReturnValue instruction at its end. We’ll do that by introducing another opcode.

The previously-defined OpReturnValue tells the VM to return the value sitting on top of the stack. The new opcode, which we’ll call OpReturn, will also tell the VM to return from the current function, except this time, there’s nothing on the stack, no return value, nothing. Just go back to what you were doing before calling this function.

Here is its definition:

// code/code.go

const (
    // [...]

    OpReturn
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpReturn: {"OpReturn", []int{}},
}

That makes three new opcodes – enough to get started in the compiler.

Compiling Function Literals

Before we start opening our compiler/compiler_test.go file, a little inventory check. We now have in place:

object.CompiledFunction to hold the instructions of a compiled function and to pass them from the compiler to the VM as part of the bytecode, as a constant.

code.OpCall to tell the VM to start executing the *object.CompiledFunction sitting on top of the stack.

code.OpReturnValue to tell the VM to return the value on top of the stack to the calling context and to resume execution there.

code.OpReturn, which is similar to code.OpReturnValue, except that there is no explicit value to return but an implicit vm.Null.

That’s enough for us to start compiling. But, again, baby steps. Before we can start compiling a function call, we’re going to make sure that we can compile the function being called.

That gives us a clear first task: compile function literals. We’ll take this snippet as our starting point:

fn() { return 5 + 10 }

A function without arguments, an integer arithmetic expression in the body, and an explicit return statement. The last point is important. We need to turn the function literal into an *object.CompiledFunction with these instructions in its Instructions field:

And in the main program, contained in Bytecode.Instructions, we need an OpConstant instruction that loads this function on to the stack. Followed by an OpPop, of course, since the returned value is unused.

We can do this. Let’s write the test for it.

// compiler/compiler_test.go

func TestFunctions(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `fn() { return 5 + 10 }`,
            expectedConstants: []interface{}{
                5,
                10,
                []code.Instructions{
                    code.Make(code.OpConstant, 0),
                    code.Make(code.OpConstant, 1),
                    code.Make(code.OpAdd),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 2),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

At first glance, it doesn’t look like there’s anything new in this test, but expectedConstants now also includes []code.Instructions.

These are the instructions we want to see in the Instructions field of the *object.CompiledFunction, which is passed around as the constant with the index 2. We could’ve put an *object.CompiledFunction directly into expectedConstants, but since we’re only interested in the instructions, we might as well skip the outer layer and make the tests more readable.

Nonetheless, we need to update our tooling so it can now make assertions about []code.Instructions in expectedConstants:

// compiler/compiler_test.go

func testConstants(
    t *testing.T,
    expected []interface{},
    actual []object.Object,
) error {
    // [...]

    for i, constant := range expected {
        switch constant := constant.(type) {
        // [...]

        case []code.Instructions:
            fn, ok := actual[i].(*object.CompiledFunction)
            if !ok {
                return fmt.Errorf("constant %d - not a function: %T",
                    i, actual[i])
            }

            err := testInstructions(constant, fn.Instructions)
            if err != nil {
                return fmt.Errorf("constant %d - testInstructions failed: %s",
                    i, err)
            }
        }
    }

    return nil
}

In the new case branch for []code.Instructions we use testInstructions (which we already had in place), to make sure that the *object.CompiledFunction in the constant pool contains the correct instructions.

And that’s it. Our first test for the compilation of functions. We can now run it and see it fail:

$ go test ./compiler
--- FAIL: TestFunctions (0.00s)
 compiler_test.go:296: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 2\n0003 OpPop\n"
  got ="0000 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

The test doesn’t even get to check the compiled function’s instructions, because the instruction that’s supposed to load the function on to the stack is missing in the main program. And that’s because our compiler does not compile *ast.FunctionLiterals. Time to change that.

The Body of an *ast.FunctionLiteral is an *ast.BlockStatement and contains a series of ast.Statements. Since we already know how to compile *ast.BlockStatements from compiling *ast.IfExpressions, compiling the statements in a function’s body shouldn’t be a problem.

But if we were to simply call the compiler’s Compile method with the Body of the *ast.FunctionLiteral at hand, we’d end up with a mess: the resulting instructions would end up being entangled with the instructions of the main program. The solution? Introducing our compiler to the concept of scopes.

Adding Scopes

That sounds quite elaborate, but is actually a straightforward change. In practical terms, it means that instead of using a single slice and the two separate fields lastInstruction and previousInstruction to keep track of emitted instructions, we bundle them together in a compilation scope and use a stack of compilation scopes:

// compiler/compiler.go

type CompilationScope struct {
    instructions        code.Instructions
    lastInstruction     EmittedInstruction
    previousInstruction EmittedInstruction
}

type Compiler struct {
    // [...]

    scopes     []CompilationScope
    scopeIndex int
}

Before we start compiling a function’s body, i.e., enter a new scope, we push a new CompilationScope on to the scopes stack. While compiling inside this scope, the emit method of the compiler will modify only the fields of the current CompilationScope. Once we’re done compiling the function, we leave the scope by popping it off the scopes stack and putting the instructions in a new *object.CompiledFunction.

It sounds way more complicated than it is, I promise. Here’s the test case that shows what we want:

// compiler/compiler_test.go

func TestCompilerScopes(t *testing.T) {
    compiler := New()
    if compiler.scopeIndex != 0 {
        t.Errorf("scopeIndex wrong. got=%d, want=%d", compiler.scopeIndex, 0)
    }

    compiler.emit(code.OpMul)

    compiler.enterScope()
    if compiler.scopeIndex != 1 {
        t.Errorf("scopeIndex wrong. got=%d, want=%d", compiler.scopeIndex, 1)
    }

    compiler.emit(code.OpSub)

    if len(compiler.scopes[compiler.scopeIndex].instructions) != 1 {
        t.Errorf("instructions length wrong. got=%d",
            len(compiler.scopes[compiler.scopeIndex].instructions))
    }

    last := compiler.scopes[compiler.scopeIndex].lastInstruction
    if last.Opcode != code.OpSub {
        t.Errorf("lastInstruction.Opcode wrong. got=%d, want=%d",
            last.Opcode, code.OpSub)
    }

    compiler.leaveScope()
    if compiler.scopeIndex != 0 {
        t.Errorf("scopeIndex wrong. got=%d, want=%d",
            compiler.scopeIndex, 0)
    }

    compiler.emit(code.OpAdd)

    if len(compiler.scopes[compiler.scopeIndex].instructions) != 2 {
        t.Errorf("instructions length wrong. got=%d",
            len(compiler.scopes[compiler.scopeIndex].instructions))
    }

    last = compiler.scopes[compiler.scopeIndex].lastInstruction
    if last.Opcode != code.OpAdd {
        t.Errorf("lastInstruction.Opcode wrong. got=%d, want=%d",
            last.Opcode, code.OpAdd)
    }

    previous := compiler.scopes[compiler.scopeIndex].previousInstruction
    if previous.Opcode != code.OpMul {
        t.Errorf("previousInstruction.Opcode wrong. got=%d, want=%d",
            previous.Opcode, code.OpMul)
    }
}

We test two new methods on the compiler here: enterScope and leaveScope. They’re supposed to do what their names promise and change the behaviour of emit by pushing and popping instructions CompilationScopes on the new scopes stack. The main idea behind this test is to make sure that the instructions emitted in one scope should have no effect on the instructions in another scope.

Since the methods do not exist yet, the tests blow up. I’ll spare you the output. Making them pass, though, comes naturally to us since it boils down to using a stack of something and we’re pretty good at that by now.

First, we have to remove the instructions, lastInstruction and previousInstruction fields from the compiler and replace them with a CompilationScope when initializing a new *Compiler:

// compiler/compiler.go

type Compiler struct {
    constants []object.Object

    symbolTable *SymbolTable

    scopes     []CompilationScope
    scopeIndex int
}

func New() *Compiler {
    mainScope := CompilationScope{
        instructions:        code.Instructions{},
        lastInstruction:     EmittedInstruction{},
        previousInstruction: EmittedInstruction{},
    }

    return &Compiler{
        constants:   []object.Object{},
        symbolTable: NewSymbolTable(),
        scopes:      []CompilationScope{mainScope},
        scopeIndex:  0,
    }
}

Now we need to update every reference to the removed fields and change them to use the current scope. To help with that we add a new method, called currentInstructions:

// compiler/compiler.go

func (c *Compiler) currentInstructions() code.Instructions {
    return c.scopes[c.scopeIndex].instructions
}

This can now be used in addInstruction, the method emit uses to do its work:

// compiler/compiler.go

func (c *Compiler) addInstruction(ins []byte) int {
    posNewInstruction := len(c.currentInstructions())
    updatedInstructions := append(c.currentInstructions(), ins...)

    c.scopes[c.scopeIndex].instructions = updatedInstructions

    return posNewInstruction
}

Here we first use c.currentInstructions to get the current slice of instructions and then, in order to mutate them, we replace them on the stack.

In the other helper methods of the compiler where we previously accessed the instructions, lastInstruction and previousInstruction fields directly, we also have to go through the stack now:

// compiler/compiler.go

func (c *Compiler) setLastInstruction(op code.Opcode, pos int) {
    previous := c.scopes[c.scopeIndex].lastInstruction
    last := EmittedInstruction{Opcode: op, Position: pos}

    c.scopes[c.scopeIndex].previousInstruction = previous
    c.scopes[c.scopeIndex].lastInstruction = last
}

func (c *Compiler) lastInstructionIsPop() bool {
    return c.scopes[c.scopeIndex].lastInstruction.Opcode == code.OpPop
}

func (c *Compiler) removeLastPop() {
    last := c.scopes[c.scopeIndex].lastInstruction
    previous := c.scopes[c.scopeIndex].previousInstruction

    old := c.currentInstructions()
    new := old[:last.Position]

    c.scopes[c.scopeIndex].instructions = new
    c.scopes[c.scopeIndex].lastInstruction = previous
}

func (c *Compiler) replaceInstruction(pos int, newInstruction []byte) {
    ins := c.currentInstructions()

    for i := 0; i < len(newInstruction); i++ {
        ins[pos+i] = newInstruction[i]
    }
}

func (c *Compiler) changeOperand(opPos int, operand int) {
    op := code.Opcode(c.currentInstructions()[opPos])
    newInstruction := code.Make(op, operand)

    c.replaceInstruction(opPos, newInstruction)
}

Then we need to make a few more delicate changes, in the heart of the Compile method, where we previously accessed c.instructions and now need to switch to c.currentInstructions() call:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]
    case *ast.IfExpression:
        // [...]

        afterConsequencePos := len(c.currentInstructions())
        c.changeOperand(jumpNotTruthyPos, afterConsequencePos)

        // [...]

        afterAlternativePos := len(c.currentInstructions())
        c.changeOperand(jumpPos, afterAlternativePos)

    // [...]
    }

    // [...]
}

We also need to return the current instructions when we want to return the bytecode the compiler produced:

// compiler/compiler.go

func (c *Compiler) Bytecode() *Bytecode {
    return &Bytecode{
        Instructions: c.currentInstructions(),
        Constants:    c.constants,
    }
}

Finally, we’re ready to add the new enterScope and leaveScope methods:

// compiler/compiler.go

func (c *Compiler) enterScope() {
    scope := CompilationScope{
        instructions:        code.Instructions{},
        lastInstruction:     EmittedInstruction{},
        previousInstruction: EmittedInstruction{},
    }
    c.scopes = append(c.scopes, scope)
    c.scopeIndex++
}

func (c *Compiler) leaveScope() code.Instructions {
    instructions := c.currentInstructions()

    c.scopes = c.scopes[:len(c.scopes)-1]
    c.scopeIndex--

    return instructions
}

I’ll spare you an in-depth explanation. We’ve seen this before with all of the other stacks we’ve implemented, except that now it’s whole code.Instructions that we push and pop.

The tests are happy:

$ go test -run TestCompilerScopes ./compiler
ok      monkey/compiler 0.008s

At least the TestCompilerScopes function. What’s not happy is the test that brought us here:

$ go test ./compiler
--- FAIL: TestFunctions (0.00s)
 compiler_test.go:396: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 2\n0003 OpPop\n"
  got ="0000 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

Now, though, we’re in a position to fix it.

Compiling With Scopes

Our compiler knows about scopes and we know how to use them – we can now compile *ast.FunctionLiterals:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.FunctionLiteral:
        c.enterScope()

        err := c.Compile(node.Body)
        if err != nil {
            return err
        }

        instructions := c.leaveScope()

        compiledFn := &object.CompiledFunction{Instructions: instructions}
        c.emit(code.OpConstant, c.addConstant(compiledFn))

    // [...]
    }

    // [...]
}

This snippet of code revolves around one idea: change where emitted instructions are stored when compiling a function.

So, when we come across an *ast.FunctionLiteral the first thing we do is enter a new scope by calling c.enterScope. Then we compile the node.Body, the AST nodes making up the function’s body. After that, we take the just-filled slice of instructions off the stack of CompilationScopes by calling c.leaveScope, create a new *object.CompiledFunction that holds these instructions, and add that function to the constant pool.

Done, function compiled:

$ go test ./compiler
--- FAIL: TestFunctions (0.00s)
 compiler_test.go:654: testInstructions failed: wrong instruction at 2.
  want="0000 OpConstant 2\n0003 OpPop\n"
  got ="0000 OpConstant 0\n0003 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

Oh, well. It turns out that we do know how to compile function literals, but we don’t know how to compile *ast.ReturnStatements. And since the body of the function in the test is nothing more than a single return statement, we do not compile anything of that function. We only create an *object.CompiledFunction constant with no instructions.

Our testing infrastructure is just not advanced enough to point us to the origin of the problem with a precise error message. You can trust me, though, I’ve done the digging for both of us.

So, compiling *ast.ReturnStatements it is. Since we made a plan, we already know which opcode should come out the other end: OpReturnValue.

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.ReturnStatement:
        err := c.Compile(node.ReturnValue)
        if err != nil {
            return err
        }

        c.emit(code.OpReturnValue)

    // [...]
    }

    // [...]
}

First we compile the return value itself, an expression, to instructions that leave the value on the stack and then we emit an OpReturnValue instruction.

And now, let’s try that again…

$ go test ./compiler
ok      monkey/compiler 0.009s

Alright, here we go! We’ve successfully turned the body of a function into a series of instructions!

But before we start the official celebration, there’s one last thing we need to take care of. It’s not a big deal, really, since we just implemented a variation of it, but we need to make sure that the implicit returning of a value results in the same bytecode as the explicit return statement.

Writing the test case for this is as easy as duplicating the previous one and removing the return from the Monkey code:

// compiler/compiler_test.go

func TestFunctions(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input: `fn() { 5 + 10 }`,
            expectedConstants: []interface{}{
                5,
                10,
                []code.Instructions{
                    code.Make(code.OpConstant, 0),
                    code.Make(code.OpConstant, 1),
                    code.Make(code.OpAdd),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 2),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

We already know that solving this involves OpPop instructions, because in this test case we expect the compiler to get rid of the OpPop that it would emit after the last expression statement in a function’s body. We do not want anything to take the implicit return value off the stack. In other cases, though, we still want OpPop instructions around, and before we end up with no OpPop at all, let’s make sure they stay where they are in the cases where we need them and add another test case:

// compiler/compiler_test.go

func TestFunctions(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input: `fn() { 1; 2 }`,
            expectedConstants: []interface{}{
                1,
                2,
                []code.Instructions{
                    code.Make(code.OpConstant, 0),
                    code.Make(code.OpPop),
                    code.Make(code.OpConstant, 1),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 2),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

This test case now succinctly explains what we want to do with OpPop in the future. The first expression statement, the literal 1, should be followed by an OpPop instruction. Same as it ever was. But the second expression statement, the 2, is the implicit return value and the OpPop instruction must be replaced by an OpReturnValue instruction.

Now we have two failing test cases to fix and the test output is actually pretty helpful:

$ go test ./compiler
--- FAIL: TestFunctions (0.00s)
 compiler_test.go:693: testConstants failed: constant 2 -\
   testInstructions failed: wrong instruction at 7.
  want="0000 OpConstant 0\n0003 OpConstant 1\n0006 OpAdd\n0007 OpReturnValue\n"
  got ="0000 OpConstant 0\n0003 OpConstant 1\n0006 OpAdd\n0007 OpPop\n"
FAIL
FAIL    monkey/compiler 0.009s

As expected, the last expression statement in a function is not turned into an implicit return value, but is still followed by an OpPop instruction.

The right time to fix this is after the compilation of a function’s body and before leaving the scope. At that point, we still have access to the just-emitted instructions. We can check whether the last instruction is an OpPop instruction and, if necessary, turn it into an OpReturnValue.

To make the necessary changes easier, we refactor and change our existing lastInstructionIsPop method into a more generic lastInstructionIs with an added defensive check:

// compiler/compiler.go

func (c *Compiler) lastInstructionIs(op code.Opcode) bool {
    if len(c.currentInstructions()) == 0 {
        return false
    }

    return c.scopes[c.scopeIndex].lastInstruction.Opcode == op
}

That requires changing the previous locations in which lastInstructionIsPop was called:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]
    case *ast.IfExpression:
        // [...]

        if c.lastInstructionIs(code.OpPop) {
            c.removeLastPop()
        }

        // [...]

        if node.Alternative == nil {
            // [...]
        } else {
            // [...]
            if c.lastInstructionIs(code.OpPop) {
                c.removeLastPop()
            }
            // [...]
        }

    // [...]
    }

    // [...]
}

We can now change the case *ast.FunctionLiteral branch in the Compile method to use c.lastInstructionIs:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.FunctionLiteral:
        c.enterScope()

        err := c.Compile(node.Body)
        if err != nil {
            return err
        }

        if c.lastInstructionIs(code.OpPop) {
            c.replaceLastPopWithReturn()
        }

        instructions := c.leaveScope()

        compiledFn := &object.CompiledFunction{Instructions: instructions}
        c.emit(code.OpConstant, c.addConstant(compiledFn))

    // [...]
    }

    // [...]
}

func (c *Compiler) replaceLastPopWithReturn() {
    lastPos := c.scopes[c.scopeIndex].lastInstruction.Position
    c.replaceInstruction(lastPos, code.Make(code.OpReturnValue))

    c.scopes[c.scopeIndex].lastInstruction.Opcode = code.OpReturnValue
}

Right after compiling a function’s body, we check whether the last emitted instruction was an OpPop and, if it was, we replace it with an OpReturnValue. A straightforward change and the two new test cases now pass:

$ go test ./compiler
ok      monkey/compiler 0.008s

But why did we refactor lastInstructionIsPop to lastInstructionIs and add an extra safety check if we only check for OpPop again? Well, because we’re not done yet. There is still this nagging edge case: a function without a body. I promise, though, we’re close to the finish line.

What we want from our compiler is to turn an empty function body into a single OpReturn instruction:

// compiler/compiler_test.go

func TestFunctionsWithoutReturnValue(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `fn() { }`,
            expectedConstants: []interface{}{
                []code.Instructions{
                    code.Make(code.OpReturn),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

This fails, shall I say, beautifully:

$ go test ./compiler
--- FAIL: TestFunctionsWithoutReturnValue (0.00s)
 compiler_test.go:772: testConstants failed: constant 0 -\
  testInstructions failed: wrong instructions length.
  want="0000 OpReturn\n"
  got =""
FAIL
FAIL    monkey/compiler 0.009s

We want an OpReturn instruction, but get nothing. Can’t be more specific than that, right? The fix for this is also quite beautiful, in its own succinct way:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.FunctionLiteral:
        // [...]

        if c.lastInstructionIs(code.OpPop) {
            c.replaceLastPopWithReturn()
        }
        if !c.lastInstructionIs(code.OpReturnValue) {
            c.emit(code.OpReturn)
        }
        // [...]

    // [...]
    }

    // [...]
}

First the check whether we need to replace an OpPop instruction with an OpReturnValue. We already had that in place. It should turn every last statement in a function’s body into an OpReturnValue. Either because it already was an explicit *ast.ReturnStatement or because we now changed it.

But if that wasn’t the case – and this is new – it means we either didn’t have any statements in the function’s body or only statements that we couldn’t turn into an OpReturnValue instruction. Currently, we’re focused on former, but we’ll talk about the latter soon enough. For now, we emit an OpReturn in both cases.

And now, with this edge case also fixed, we’re finally ready to celebrate:

$ go test ./compiler
ok      monkey/compiler 0.009s

Cool! We can now correctly compile function literals!

That really is a reason to celebrate: we turn function literals into *object.CompiledFunction, take care of implicit and explicit returns in the function’s body and also emit an OpConstant instruction to load the function on to the stack in the VM. Cheers to that!

We’ve reached the halfway point on the compilation side. The rest of the way is the compilation of function calls.

Compiling Function Calls

Before we open compiler_test.go and start hammering out test cases, let’s take a step back and think this through. We want to implement function calls. In other words, we need to emit instructions that represent Monkey’s bytecode calling convention, since that’s how you call a function in Monkey bytecode.

At the beginning of this chapter we decided that the start of the calling convention is putting the function you want to call on to the stack. We already know how to do that. Either by using an OpConstant instruction in case it’s a function literal that’s being called, which looks like this:

fn() { 1 + 2 }()

Or with an OpGetGlobal instruction, if the function was previously bound to a name:

let onePlusTwo = fn() { 1 + 2 };
onePlusTwo();

Both options result in the *object.CompiledFunction we want to call to sit on the stack. In order to now execute its instructions, we need to issue an OpCall instruction.

The VM then executes the function’s instructions and when it’s done, it pops the function itself off the stack and replaces it with the return value. That’s if there is a return value. If not, it only pops the function off the stack, which is fine too.

This whole part of the calling convention – what the VM does with the function once it’s done executing it – is implicit: we do not need to issue an OpPop instruction to get the function off the stack. It’s part of the convention and we’ll build it straight into the VM.

Before you start to scratch your head, please keep in mind that the convention will change once we introduce arguments to function calls. That’s why there’s no mention of them yet.

For now, though, we’re pretty sure about what we need to do. When the compiler comes across an *ast.CallExpression it should do this:

// compiler/compiler_test.go

func TestFunctionCalls(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `fn() { 24 }();`,
            expectedConstants: []interface{}{
                24,
                []code.Instructions{
                    code.Make(code.OpConstant, 0), // The literal "24"
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 1), // The compiled function
                code.Make(code.OpCall),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            let noArg = fn() { 24 };
            noArg();
            `,
            expectedConstants: []interface{}{
                24,
                []code.Instructions{
                    code.Make(code.OpConstant, 0), // The literal "24"
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 1), // The compiled function
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpCall),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

The function that’s being called in both test cases is intentionally simple, because the focus here is on the OpCall instruction and that it’s preceded by either an OpGetGlobal or an OpConstant instruction.

The test fails because our compiler knows nothing about *ast.CallExpression yet:

$ go test ./compiler
--- FAIL: TestFunctionCalls (0.00s)
 compiler_test.go:833: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 1\n0003 OpCall\n0004 OpPop\n"
  got ="0000 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

The great thing about implementing a fix for these tests is that from the compiler’s perspective it doesn’t matter whether the function to be called is bound to a name or a literal – we already know how to do both.

All we need to do is tell our compiler that when it comes across an *ast.CallExpression it should compile the function being called and then emit an OpCall instruction:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.CallExpression:
        err := c.Compile(node.Function)
        if err != nil {
            return err
        }

        c.emit(code.OpCall)

    // [...]
    }

    // [...]
}

You see, when I said that we’re halfway there and that the second half is implementing function calls, I kinda lied a little bit. We were way past the halfway point. And now, we’ve crossed the finish line in the compiler:

$ go test ./compiler
ok      monkey/compiler 0.009s

Yes, that means that we are correctly compiling function literals and function calls. We’re now really at the halfway point, because now we can head over to the VM and make sure that it knows how to handle functions, the two return instructions and OpCall.

Functions in the VM

Here’s the situation and task at hand, put into the vocabulary of our VM:

The bytecode handed over by the compiler can now contain *object.CompiledFunctions in its Constants field. When we come across an OpCall instruction we need to execute the instructions of the *object.CompiledFunction sitting on top of the stack. We do that until we encounter either an OpReturnValue or an OpReturn instruction. If it’s an OpReturnValue, we need to preserve the value on top of the stack, the return value. Then we have to remove the just executed *object.CompiledFunction from the stack and replace it with the saved return value, if we have one.

Implementing that is our goal for this section and we already know that popping off and pushing things on to the stack are not going to be the issue. We’re pros at that by now. The intriguing question is how do we execute the instructions of a function?

Right now, executing instructions means that the VM’s main loop iterates through the vm.instructions slice by incrementing its instruction pointer, ip, and using it as an index to fetch the next opcode from vm.instructions. It also reads the operands from the same slice. When it comes across a branching instruction, like OpJump, it changes the value of ip manually.

When we execute functions, we do not want to change this mechanism. The only thing we want to change is the data it uses: the instructions and the instruction pointer. If we can change those while the VM is running we can execute functions.

“Changing a slice and an integer? That’s not a challenge!” I know, but that’s not all of it. We also need to change them back. When the function returns we need to restore the old instructions and the old ip. And not just once. We also need to handle nested execution of functions. Consider this:

let one = fn() { 5 };
let two = fn() { one() };
let three = fn() { two() };
three();

When three is called the instructions and the instruction pointer need to be changed. Then two is called, so they need to be changed again. one is called in two, so again, change the instructions and the instruction pointer. And once one is executed, we need to restore the instructions and the instruction pointer as we left them in two, before the call. Then we need to do the same for three, and after three returns we need to do the same for the main program.

If you read the last paragraph and a little bell with “stack” written on it began ringing in your head: you’re on the right track.

Adding Frames

This is what we know: function calls are nested and execution-relevant data – the instructions and the instruction pointer – is accessed in a last-in-first-out (LIFO) manner. We’re masters of the stack, so this plays into our hands, but juggling two separate pieces of data is never pleasant. The solution is to tie them together and call the resulting bundle a “frame”.

Frame is short for call frame, or stack frame, and is the name for a data structure that holds execution-relevant information. In compiler or interpreter literature this is also sometimes called an activation record.

On real machines – computers – a frame is a not something separate from but a designated part of the stack. It’s where the return address, the arguments to the current function and its local variables are stored. And since it’s on a stack, a frame is easy to pop off after the function has been executed. As we saw in the first chapter, using the stack to save call frames is what turns it from a stack into the stack, and more specifically: the call stack.

In virtual-machine land we don’t have to use the stack. We’re not constrained by standardized calling conventions and other much too real things, like real memory addresses and locations. We, using Go instead of assembly language and building a virtual machine, have more options available to us than the builders and programmers of real machines. We can store frames anywhere we like. Any execution-relevant piece of data, actually.

What’s kept on the stack and what’s not differs from VM to VM. Some keep everything on the stack, others only the return address, some only the local variables, some the local variables and the arguments of the function call. There is no best nor an only choice for these decisions. The implementation depends on the language being implemented, the requirements in regards to concurrency and performance, the host language and much more.

Since we’re here to learn, we choose what’s easiest to build, to understand, to extend and what also allows us to see how it might be changed or implemented differently.

We already use our VM’s stack in parts as a call stack: we save the function to be called and its return value on it. But we’re not going to keep our frames on there. Instead they’ll get their own stack.

But before we build that, here’s what makes up a Frame in our Monkey VM:

// vm/frame.go

package vm

import (
    "monkey/code"
    "monkey/object"
)

type Frame struct {
    fn *object.CompiledFunction
    ip int
}

func NewFrame(fn *object.CompiledFunction) *Frame {
    return &Frame{fn: fn, ip: -1}
}

func (f *Frame) Instructions() code.Instructions {
    return f.fn.Instructions
}

A Frame has two fields: ip and fn. fn points to the compiled function referenced by the frame, and ip is the instruction pointer in this frame, for this function. With these two fields we have all the data used by the main loop of the VM in one place. And the frame being currently executed is the one sitting on top of the call stack.

This is so tiny that I’m fairly confident in my choice to not write tests for the NewFrame function and Instructions method.

With Frame defined, we find ourselves at a crossroads. We can either go left and decide to bend over backwards by changing our VM to only use frames when calling and executing a function. Or, we can go right and choose a much more elegant and smoother approach, which modifies the VM so that it not only uses frames for functions, but also treats the main program, the bytecode.Instructions, as if it were a function.

Yes, of course we’re going right.

And even better news than the fact that we’re going to build something smooth and elegant is that we don’t even have to write tests, since this is another prime example for the term “implementation detail”: the visible behaviour of the VM should not change one bit when we now change it to use frames. It’s an internal change only. And to make sure that our VM keeps on working the way it currently does, we already have our test suite.

So, let’s build a stack for frames:

// vm/vm.go

type VM struct {
    // [...]

    frames      []*Frame
    framesIndex int
}

func (vm *VM) currentFrame() *Frame {
    return vm.frames[vm.framesIndex-1]
}

func (vm *VM) pushFrame(f *Frame) {
    vm.frames[vm.framesIndex] = f
    vm.framesIndex++
}

func (vm *VM) popFrame() *Frame {
    vm.framesIndex--
    return vm.frames[vm.framesIndex]
}

Private and still unused changes – all the tests are still green, but now we have a stack for frames in place. Just like with our other stacks, we use a slice as the underlying data structure and an integer as index. Since it’s nice to have a little bit of performance here, we use a slightly different approach than the one used in the compiler for the scopes stack. Instead of appending and slicing off, we pre-allocate the frames slice.

Now we just need to use it. The first task is to allocate said slice and push the outermost, the “main frame”, on to it:

// vm/vm.go

const MaxFrames = 1024

func New(bytecode *compiler.Bytecode) *VM {
    mainFn := &object.CompiledFunction{Instructions: bytecode.Instructions}
    mainFrame := NewFrame(mainFn)

    frames := make([]*Frame, MaxFrames)
    frames[0] = mainFrame

    return &VM{
        constants: bytecode.Constants,

        stack: make([]object.Object, StackSize),
        sp:    0,

        globals: make([]object.Object, GlobalsSize),

        frames:      frames,
        framesIndex: 1,
    }
}

New here is the prelude before we initialize a new *VM.

As the first thing, we create a mainFn. That’s the fictional main frame that contains the bytecode.Instructions, which make up the whole Monkey program. Then we allocate the frames stack with a maximum of MaxFrames slots. The value of 1024 is arbitrary but should be enough for us as long as we don’t nest function calls too much. The first frame on this new frames stack is the mainFrame. And then, following the fields we already know, we put the frames and the framesIndex of 1 into the newly created *VM.

At the same time, we’ve also removed the initialization of the instructions field in this New function and now need to remove it from the definition of VM, too:

// vm/vm.go

type VM struct {
    constants []object.Object

    stack []object.Object
    sp    int

    globals []object.Object

    frames      []*Frame
    framesIndex int
}

With the instructions slice gone, we now need to change the way we access the instructions and the instruction pointer inside the VM and make sure that we always access them by going through the current frame.

The first change we need to make is in the VM’s main loop. Since the ip can’t be initialized in the loop anymore, but only incremented there, we need to change from an old school for loop to Go’s version of a while loop, where we have just one condition and increment the ip manually in its body:

// vm/vm.go

func (vm *VM) Run() error {
    var ip int
    var ins code.Instructions
    var op code.Opcode

    for vm.currentFrame().ip < len(vm.currentFrame().Instructions())-1 {
        vm.currentFrame().ip++

        ip = vm.currentFrame().ip
        ins = vm.currentFrame().Instructions()
        op = code.Opcode(ins[ip])

        switch op {
        // [...]
        }
    }

    return nil
}

We add the three helper variables – ip, ins and op – at the top of the Run method, so the rest of it doesn’t become too crowded with calls to currentFrame(). Especially since we now need to update every place in Run where we either read in operands or access or modify the instruction pointer:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        case code.OpConstant:
            constIndex := code.ReadUint16(ins[ip+1:])
            vm.currentFrame().ip += 2
        // [...]

        case code.OpJump:
            pos := int(code.ReadUint16(ins[ip+1:]))
            vm.currentFrame().ip = pos - 1
        // [...]

        case code.OpJumpNotTruthy:
            pos := int(code.ReadUint16(ins[ip+1:]))
            vm.currentFrame().ip += 2

            condition := vm.pop()
            if !isTruthy(condition) {
                vm.currentFrame().ip = pos - 1
            }
        // [...]

        case code.OpSetGlobal:
            globalIndex := code.ReadUint16(ins[ip+1:])
            vm.currentFrame().ip += 2
        // [...]

        case code.OpGetGlobal:
            globalIndex := code.ReadUint16(ins[ip+1:])
            vm.currentFrame().ip += 2
        // [...]

        case code.OpArray:
            numElements := int(code.ReadUint16(ins[ip+1:]))
            vm.currentFrame().ip += 2
        // [...]

        case code.OpHash:
            numElements := int(code.ReadUint16(ins[ip+1:]))
            vm.currentFrame().ip += 2
        // [...]

        }

    // [...]
}

And that was it: our VM is now fully converted to frames! And the best bit is that all the tests are still green:

$ go test ./vm
ok      monkey/vm   0.036s

Time to add function calls.

Executing Function Calls

It’s high time and we know exactly what we want:

// vm/vm_test.go

func TestCallingFunctionsWithoutArguments(t *testing.T) {
    tests := []vmTestCase{
        {
            input: `
        let fivePlusTen = fn() { 5 + 10; };
        fivePlusTen();
        `,
            expected: 15,
        },
    }

    runVmTests(t, tests)
}

That’s what we’re after! Remember? It’s the goal of this section. Question is, can we already get it to work?

$ go test ./vm
--- FAIL: TestCallingFunctionsWithoutArguments (0.00s)
 vm_test.go:443: testIntegerObject failed: object is not Integer.\
   got=*object.CompiledFunction (&{Instructions:\
  0000 OpConstant 0
  0003 OpConstant 1
  0006 OpAdd
  0007 OpReturnValue
  })
FAIL
FAIL    monkey/vm   0.036s

Well, we always do, don’t we?

Most of the things we need are in place already. We know how to handle global bindings, check. We know how to handle integer expressions, check. We know how to load constants, which compiled functions are, check. And we know how to execute frames, so check here too. What we haven’t yet implemented is the OpCall opcode.

But we already know pretty well what to do when we come across an OpCall:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpCall:
            fn, ok := vm.stack[vm.sp-1].(*object.CompiledFunction)
            if !ok {
                return fmt.Errorf("calling non-function")
            }
            frame := NewFrame(fn)
            vm.pushFrame(frame)

        // [...]
        }
    // [...]
}

We get the compiled function off the stack and check if it’s indeed an *object.CompiledFunction. If it’s not, we return an error. If it is, we create a new frame that contains a reference to this function and push it on to the frames stack. As a result, the next iteration of the VM’s main loop fetches the next instruction from the *object.CompiledFunction.

Cross your fingers and awkwardly try to type go test ./vm with them:

$ go test ./vm
--- FAIL: TestCallingFunctionsWithoutArguments (0.00s)
 vm_test.go:169: testIntegerObject failed: object has wrong value.\
   got=10, want=15
FAIL
FAIL    monkey/vm   0.034s

Huh. Okay. We got 10 when we wanted 15 to be returned. Shouldn’t 10 be popped off the stack when we come across the OpAdd instruction? Why is it stil– ahh! We always check for the “last popped element” in our tests! And the 15 hasn’t been popped off the stack yet.

Come to think of it: why did we even expect that this would work? We haven’t even told the VM yet to handle OpReturnValue instructions!

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpReturnValue:
            returnValue := vm.pop()

            vm.popFrame()
            vm.pop()

            err := vm.push(returnValue)
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

We first pop the return value off the stack and put it on the side. That’s the first part of our calling convention: in the case of an OpReturnValue instruction, the return value sits on top of the stack. Then we pop the frame we just executed off the frame stack so that the next iteration of the VM’s main loop continues executing in the caller context.

And then there’s another vm.pop() call to get the just-called *object.CompiledFunction off the stack. Remember that we said it’s the VM’s implicit task to get the executed function off the stack? This is it.

Watch this:

$ go test ./vm
ok      monkey/vm   0.035s

We just called and executed a function. Remember this moment! This is a milestone when developing a bytecode VM. Our VM is now not just humming along, it’s roaring. We can even execute multiple functions – sequentially or nested in one another:

// vm/vm_test.go

func TestCallingFunctionsWithoutArguments(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {
            input: `
        let one = fn() { 1; };
        let two = fn() { 2; };
        one() + two()
        `,
            expected: 3,
        },
        {
            input: `
        let a = fn() { 1 };
        let b = fn() { a() + 1 };
        let c = fn() { b() + 1 };
        c();
        `,
            expected: 3,
        },
    }

    runVmTests(t, tests)
}

This thing runs like clockwork:

$ go test ./vm
ok      monkey/vm   0.039s

We can even be meticulous and add a test for explicit return statements. We already know that these compile down to the same instructions we just successfully executed, but adding it will give us much better feedback should something go wrong in the future:

// vm/vm_test.go

func TestFunctionsWithReturnStatement(t *testing.T) {
    tests := []vmTestCase{
        {
            input: `
        let earlyExit = fn() { return 99; 100; };
        earlyExit();
        `,
            expected: 99,
        },
        {
            input: `
        let earlyExit = fn() { return 99; return 100; };
        earlyExit();
        `,
            expected: 99,
        },
    }

    runVmTests(t, tests)
}

Even that runs without any hiccups:

$ go test ./vm
ok      monkey/vm   0.032s

Holy opcode! We’re compiling function calls to bytecode and have our own call stack in our bytecode VM and it all works! It’s high time for a nice round of patting ourselves on the back and to sit back and take a deep breath.

But since we’re here…

It’s Not Nothing, It’s Null

Before we move on, we need to take care of the OpReturn opcode. In the compiler we already made sure that empty functions compile to a single opcode: OpReturn. We also decided that calling these functions should put vm.Null on the VM’s stack and now is the time to implement that.

Thankfully, this last paragraph is a straightforward definition of the desired behaviour and can be rewritten as a test:

// vm/vm_test.go

func TestFunctionsWithoutReturnValue(t *testing.T) {
    tests := []vmTestCase{
        {
            input: `
        let noReturn = fn() { };
        noReturn();
        `,
            expected: Null,
        },
        {
            input: `
        let noReturn = fn() { };
        let noReturnTwo = fn() { noReturn(); };
        noReturn();
        noReturnTwo();
        `,
            expected: Null,
        },
    }

    runVmTests(t, tests)
}

Clueless as our VM is about OpReturn, it doesn’t put vm.Null on the stack:

$ go test ./vm
--- FAIL: TestFunctionsWithoutReturnValue (0.00s)
 vm_test.go:546: object is not Null: <nil> (<nil>)
 vm_test.go:546: object is not Null: <nil> (<nil>)
FAIL
FAIL    monkey/vm   0.037s

What do we have to do to fix these test cases? We already know how to return from a function and we even know how to return with a value. Now we have to do less:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpReturn:
            vm.popFrame()
            vm.pop()

            err := vm.push(Null)
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

Pop the frame, pop the called function, push Null. Done:

$ go test ./vm
ok      monkey/vm   0.038s

A Little Bonus

Here’s a little treat. In this section, we did more than reach the milestone of compiling and executing the snippet we set out to get working. We also – without making it a goal or even thinking about it – managed to implement the best thing since REPLs and fast unit tests: first-class functions. Yes, the compiler and VM are already capable of compiling and executing the following piece of Monkey code:

let returnsOne = fn() { 1; };
let returnsOneReturner = fn() { returnsOne; };
returnsOneReturner()();

Don’t believe me? Well, no need, I’m willing to bet a test case on it:

// vm/vm_test.go

func TestFirstClassFunctions(t *testing.T) {
    tests := []vmTestCase{
        {
            input: `
        let returnsOne = fn() { 1; };
        let returnsOneReturner = fn() { returnsOne; };
        returnsOneReturner()();
        `,
            expected: 1,
        },
    }

    runVmTests(t, tests)
}

Here’s what we achieved without even intending to:

$ go test ./vm
ok      monkey/vm   0.038s

If it wouldn’t be us patting ourselves shamelessly on our backs, I’d say that’s a note as high as you can end a section on.

Local Bindings

Our current implementation of functions and function calls does not support local bindings. We do support bindings, but only global ones. Local bindings are different in a crucial detail, in that they are local to a function, meaning that they are only visible and accessible within the scope of a function. This detail is crucial because it ties the implementation of local bindings to the implementation of functions. And since we did a great job with the second one, we’re now ready to approach the first one.

At the end of this section we want to have this piece of Monkey code working:

let globalSeed = 50;
let minusOne = fn() {
  let num = 1;
  globalSeed - num;
}
let minusTwo = fn() {
  let num = 2;
  globalSeed - num;
}
minsOne() + minsTwo()

What we have here is a mixture of global and local bindings. globalSeed is a global binding that can be accessed in nested scopes, like the minusOne and minusTwo functions. Then we also have the local binding num, showing up in both functions. Important about num is that it’s not accessible outside these functions and that both bindings of num in each function are unique and don’t overwrite each other.

In order to get this piece of code compiled and executed, we need to do a few different things.

First of all, we need to define opcodes that tell the VM to create local binding and to retrieve them. I bet you guessed as much.

Then we need to extend the compiler so it can output these new opcodes correctly. That means, it needs to distinguish between local bindings and global bindings, and also between local bindings with the same name in different functions.

The last step is to implement these new instructions and local bindings in the VM. We already know how to store and access global bindings and that knowledge won’t be wasted, since the main mechanism behind bindings won’t change. But for local bindings we need a new store.

As always, we’ll take small steps and start at the beginning.

Opcodes for Local Bindings

We already have two opcodes for bindings in place: OpSetGlobal and OpGetGlobal. Now we need equivalents for local bindings. We don’t even need to be creative here, we’ll just create “local versions” of the global ones and call them OpSetLocal and OpGetLocal. They’ll also, just like the global ones, have one operand each, a unique index for the local binding in question.

The naming doesn’t play a huge role, as you know, because it’s just bytes underneath. The important bit is that these opcodes are distinct from the global ones. They should tell VM that the binding is local to the currently executing function and that it should have absolutely no effect on global bindings. The binding shouldn’t overwrite a global binding and it itself shouldn’t be overwritten by one.

And since defining opcodes is a rather dull task, we’ll treat ourselves to a little flourish: instead of giving these new opcodes the two-byte operand their global cousins have, we’ll use one byte, which we haven’t had before. And besides that, 256 local bindings per function should surely be enough for the average Monkey program, right?

Here are the definitions:

// code/code.go

const (
    // [...]

    OpGetLocal
    OpSetLocal
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpGetLocal: {"OpGetLocal", []int{1}},
    OpSetLocal: {"OpSetLocal", []int{1}},
}

Nothing surprising here, only the one-byte operands are new. That means we need to make sure our existing tooling can handle them:

// code/code_test.go

func TestMake(t *testing.T) {
    tests := []struct {
        op       Opcode
        operands []int
        expected []byte
    }{
        // [...]
        {OpGetLocal, []int{255}, []byte{byte(OpGetLocal), 255}},
    }

    // [...]
}

Rightfully, Make is stumped by the one byte:

$ go test ./code
--- FAIL: TestMake (0.00s)
 code_test.go:26: wrong byte at pos 1. want=255, got=0
FAIL
FAIL    monkey/code 0.007s

Getting Make to work means extending its switch statement, which I promised you to do since it’s been introduced:

// code/code.go

func Make(op Opcode, operands ...int) []byte {
    // [...]

    offset := 1
    for i, o := range operands {
        width := def.OperandWidths[i]
        switch width {
        case 2:
            binary.BigEndian.PutUint16(instruction[offset:], uint16(o))
        case 1:
            instruction[offset] = byte(o)
        }
        offset += width
    }

    return instruction
}

The added case 1 branch is enough to get it working, since there’s only one way to sort a single byte:

$ go test ./code
ok      monkey/code 0.007s

With Make working, we can now produce instructions with one-byte operands, but we can’t decode them. For that, we need to update our ReadOperands function and the String() debug method on Instructions:

// code/code_test.go

func TestReadOperands(t *testing.T) {
    tests := []struct {
        op        Opcode
        operands  []int
        bytesRead int
    }{
        // [...]
        {OpGetLocal, []int{255}, 1},
    }

    // [...]
}

func TestInstructionsString(t *testing.T) {
    instructions := []Instructions{
        Make(OpAdd),
        Make(OpGetLocal, 1),
        Make(OpConstant, 2),
        Make(OpConstant, 65535),
    }

    expected := `0000 OpAdd
0001 OpGetLocal 1
0003 OpConstant 2
0006 OpConstant 65535
`

    // [...]
}

Both test functions blow up, because they both depend on the same function underneath:

$ go test ./code
--- FAIL: TestInstructionsString (0.00s)
 code_test.go:53: instructions wrongly formatted.
  want="0000 OpAdd\n0001 OpGetLocal 1\n0003 OpConstant 2\n\
    0006 OpConstant 65535\n"
  got="0000 OpAdd\n0001 OpGetLocal 0\n0003 OpConstant 2\n\
    0006 OpConstant 65535\n"
--- FAIL: TestReadOperands (0.00s)
 code_test.go:83: operand wrong. want=255, got=0
FAIL
FAIL    monkey/code 0.006s

To fix these tests we create a ReadUint8 function and use it in ReadOperands:

// code/code.go

func ReadOperands(def *Definition, ins Instructions) ([]int, int) {
    operands := make([]int, len(def.OperandWidths))
    offset := 0

    for i, width := range def.OperandWidths {
        switch width {
        case 2:
            operands[i] = int(ReadUint16(ins[offset:]))
        case 1:
            operands[i] = int(ReadUint8(ins[offset:]))
        }

        offset += width
    }

    return operands, offset
}

func ReadUint8(ins Instructions) uint8 { return uint8(ins[0]) }

Yes, reading one byte and turning it into an uint8 means nothing more than telling the compiler that from now on it should treat it as such:

$ go test ./code
ok      monkey/code 0.008s

Alright, we now have two new opcodes, SetLocal and GetLocal, and both have a one-byte operand that’s supported by our infrastructure. Let’s move on to the compiler.

Compiling Locals

We already know where and how to emit the correct instructions for bindings, because we already did that for global bindings. The “where” and “how” won’t change now, but the “scope” will. And that’s also the main challenge when it comes to compiling local bindings: deciding whether to emit an instruction for a global or for a local binding.

From the outside, though, it’s clear what we want and easy to express in a test case:

// compiler/compiler_test.go

func TestLetStatementScopes(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `
            let num = 55;
            fn() { num }
            `,
            expectedConstants: []interface{}{
                55,
                []code.Instructions{
                    code.Make(code.OpGetGlobal, 0),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            fn() {
                let num = 55;
                num
            }
            `,
            expectedConstants: []interface{}{
                55,
                []code.Instructions{
                    code.Make(code.OpConstant, 0),
                    code.Make(code.OpSetLocal, 0),
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 1),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            fn() {
                let a = 55;
                let b = 77;
                a + b
            }
            `,
            expectedConstants: []interface{}{
                55,
                77,
                []code.Instructions{
                    code.Make(code.OpConstant, 0),
                    code.Make(code.OpSetLocal, 0),
                    code.Make(code.OpConstant, 1),
                    code.Make(code.OpSetLocal, 1),
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpGetLocal, 1),
                    code.Make(code.OpAdd),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 2),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Don’t be put off by the line count, this is mostly just busywork around the three use cases we test here. In the first test case, we assert that accessing a global binding from a function results in a OpGetGlobal instruction. In the second one, we expect that creating and accessing a local binding results in the new OpSetLocal and OpGetLocal opcodes being emitted. And in the third one we want to make sure that multiple local bindings in the same scope also work.

As expected, the test fails:

$ go test ./compiler
--- FAIL: TestLetStatementScopes (0.00s)
 compiler_test.go:935: testConstants failed:\
   constant 1 - testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetLocal 0\n0005 OpGetLocal 0\n\
    0007 OpReturnValue\n"
  got ="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpGetGlobal 0\n\
    0009 OpReturnValue\n"
FAIL
FAIL    monkey/compiler 0.009s

As you can see, the compiler treats every binding created with a let statement as a global binding. In order to fix that, we have to extend the SymbolTable.

Extending the Symbol Table

Currently, our symbol table only knows about one scope, the global one. We now need to extend it so it can not only tell different scopes apart but also in which scope a given symbol was defined.

More specifically, what we want is to just tell the symbol table when we enter or leave a scope in our compiler and it should keep track for us in which scope we’re in and attach that to every symbol we define in that scope. And then, when we ask it to resolve a symbol, it should tell us which unique Index a previously-defined symbol has and in which scope it was defined.

It doesn’t take a lot of code to implement that – once me make our SymbolTable recursive. But before we do that, here’s the list of requirements, translated into a test:

// compiler/symbol_table_test.go

func TestResolveLocal(t *testing.T) {
    global := NewSymbolTable()
    global.Define("a")
    global.Define("b")

    local := NewEnclosedSymbolTable(global)
    local.Define("c")
    local.Define("d")

    expected := []Symbol{
        Symbol{Name: "a", Scope: GlobalScope, Index: 0},
        Symbol{Name: "b", Scope: GlobalScope, Index: 1},
        Symbol{Name: "c", Scope: LocalScope, Index: 0},
        Symbol{Name: "d", Scope: LocalScope, Index: 1},
    }

    for _, sym := range expected {
        result, ok := local.Resolve(sym.Name)
        if !ok {
            t.Errorf("name %s not resolvable", sym.Name)
            continue
        }
        if result != sym {
            t.Errorf("expected %s to resolve to %+v, got=%+v",
                sym.Name, sym, result)
        }
    }
}

In the first line of TestResolveLocal we create a new symbol table, global, just like we previously did by calling NewSymbolTable. Then we define two symbols in this global symbol table: a and b. After that, we use a new function, called NewEnclosedSymbolTable, to create another symbol table, called local, that’s enclosed in global. In local we then define two new symbols: c and d.

That’s the setup. The expectation is that when we then try to resolve all four symbols by calling Resolve on local, the symbols with the correct Scope and Index fields are returned.

And that’s not all of it. We also want to make sure that the SymbolTable can handle arbitrarily nested and enclosed symbol tables:

// compiler/symbol_table_test.go

func TestResolveNestedLocal(t *testing.T) {
    global := NewSymbolTable()
    global.Define("a")
    global.Define("b")

    firstLocal := NewEnclosedSymbolTable(global)
    firstLocal.Define("c")
    firstLocal.Define("d")

    secondLocal := NewEnclosedSymbolTable(firstLocal)
    secondLocal.Define("e")
    secondLocal.Define("f")

    tests := []struct {
        table           *SymbolTable
        expectedSymbols []Symbol
    }{
        {
            firstLocal,
            []Symbol{
                Symbol{Name: "a", Scope: GlobalScope, Index: 0},
                Symbol{Name: "b", Scope: GlobalScope, Index: 1},
                Symbol{Name: "c", Scope: LocalScope, Index: 0},
                Symbol{Name: "d", Scope: LocalScope, Index: 1},
            },
        },
        {
            secondLocal,
            []Symbol{
                Symbol{Name: "a", Scope: GlobalScope, Index: 0},
                Symbol{Name: "b", Scope: GlobalScope, Index: 1},
                Symbol{Name: "e", Scope: LocalScope, Index: 0},
                Symbol{Name: "f", Scope: LocalScope, Index: 1},
            },
        },
    }

    for _, tt := range tests {
        for _, sym := range tt.expectedSymbols {
            result, ok := tt.table.Resolve(sym.Name)
            if !ok {
                t.Errorf("name %s not resolvable", sym.Name)
                continue
            }
            if result != sym {
                t.Errorf("expected %s to resolve to %+v, got=%+v",
                    sym.Name, sym, result)
            }
        }
    }
}

Here we go one step further and create a third symbol table, secondLocal, that’s enclosed in firstLocal, which in turn is enclosed in global. In global we again define a and b. In both enclosed symbol tables we also define two symbols each, c and d in firstLocal and e and f in secondLocal.

The expectation is that defining symbols in one local table does not interfere with the definitions in another one, and that resolving global symbols in a nested local table still resolves to the correct symbols. Finally, we also want to make sure that the Index values of the symbols defined in secondLocal again start at zero, so we can use them as operands in OpSetLocal and OpGetLocal without being tied to other scopes.

Since the nesting of symbol tables must also have an effect on the Define method of SymbolTable, we need to update the existing TestDefine function:

// compiler/symbol_table_test.go

func TestDefine(t *testing.T) {
    expected := map[string]Symbol{
        "a": Symbol{Name: "a", Scope: GlobalScope, Index: 0},
        "b": Symbol{Name: "b", Scope: GlobalScope, Index: 1},
        "c": Symbol{Name: "c", Scope: LocalScope, Index: 0},
        "d": Symbol{Name: "d", Scope: LocalScope, Index: 1},
        "e": Symbol{Name: "e", Scope: LocalScope, Index: 0},
        "f": Symbol{Name: "f", Scope: LocalScope, Index: 1},
    }

    global := NewSymbolTable()

    a := global.Define("a")
    if a != expected["a"] {
        t.Errorf("expected a=%+v, got=%+v", expected["a"], a)
    }

    b := global.Define("b")
    if b != expected["b"] {
        t.Errorf("expected b=%+v, got=%+v", expected["b"], b)
    }

    firstLocal := NewEnclosedSymbolTable(global)

    c := firstLocal.Define("c")
    if c != expected["c"] {
        t.Errorf("expected c=%+v, got=%+v", expected["c"], c)
    }

    d := firstLocal.Define("d")
    if d != expected["d"] {
        t.Errorf("expected d=%+v, got=%+v", expected["d"], d)
    }

    secondLocal := NewEnclosedSymbolTable(firstLocal)

    e := secondLocal.Define("e")
    if e != expected["e"] {
        t.Errorf("expected e=%+v, got=%+v", expected["e"], e)
    }

    f := secondLocal.Define("f")
    if f != expected["f"] {
        t.Errorf("expected f=%+v, got=%+v", expected["f"], f)
    }
}

Okay, we know what we have to do. We need to make Define and Resolve work with enclosed symbol tables. The good thing is that they are two sides of the same implementation: a recursive definition of SymbolTable that allows us to enclose symbol tables within other symbol tables.

Our tests can’t give us feedback yet, because they won’t compile due to NewEnclosedSymbolTable and LocalScope being undefined. So, let’s get them running and start by giving SymbolTable an Outer field:

// compiler/symbol_table.go

type SymbolTable struct {
    Outer *SymbolTable

    store          map[string]Symbol
    numDefinitions int
}

That allows us to implement the NewEnclosedSymbolTable function that creates a *SymbolTable with an Outer symbol table:

// compiler/symbol_table.go

func NewEnclosedSymbolTable(outer *SymbolTable) *SymbolTable {
    s := NewSymbolTable()
    s.Outer = outer
    return s
}

We just got rid of one of the undefined errors when trying to compile the tests. In order to make the other one disappear, we have to define the LocalScope constant, right next to the existing GlobalScope:

// compiler/symbol_table.go

const (
    LocalScope  SymbolScope = "LOCAL"
    GlobalScope SymbolScope = "GLOBAL"
)

Now we can finally get feedback from our three failing tests in symbol_table_test.go:

$ go test ./compiler
--- FAIL: TestLetStatementScopes (0.00s)
 compiler_test.go:935: testConstants failed:\
   constant 1 - testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetLocal 0\n0005 OpGetLocal 0\n\
    0007 OpReturnValue\n"
  got ="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpGetGlobal 0\n\
    0009 OpReturnValue\n"

--- FAIL: TestDefine (0.00s)
 symbol_table_test.go:31: expected c={Name:c Scope:LOCAL Index:0},\
   got={Name:c Scope:GLOBAL Index:0}
 symbol_table_test.go:36: expected d={Name:d Scope:LOCAL Index:1},\
   got={Name:d Scope:GLOBAL Index:1}
 symbol_table_test.go:43: expected e={Name:e Scope:LOCAL Index:0},\
   got={Name:e Scope:GLOBAL Index:0}
 symbol_table_test.go:48: expected f={Name:f Scope:LOCAL Index:1},\
   got={Name:f Scope:GLOBAL Index:1}

--- FAIL: TestResolveLocal (0.00s)
 symbol_table_test.go:94: name a not resolvable
 symbol_table_test.go:94: name b not resolvable
 symbol_table_test.go:98: expected c to resolve to\
   {Name:c Scope:LOCAL Index:0}, got={Name:c Scope:GLOBAL Index:0}
 symbol_table_test.go:98: expected d to resolve to\
   {Name:d Scope:LOCAL Index:1}, got={Name:d Scope:GLOBAL Index:1}

--- FAIL: TestResolveNestedLocal (0.00s)
 symbol_table_test.go:145: name a not resolvable
 symbol_table_test.go:145: name b not resolvable
 symbol_table_test.go:149: expected c to resolve to\
   {Name:c Scope:LOCAL Index:0}, got={Name:c Scope:GLOBAL Index:0}
 symbol_table_test.go:149: expected d to resolve to\
   {Name:d Scope:LOCAL Index:1}, got={Name:d Scope:GLOBAL Index:1}
 symbol_table_test.go:145: name a not resolvable
 symbol_table_test.go:145: name b not resolvable
 symbol_table_test.go:149: expected e to resolve to\
   {Name:e Scope:LOCAL Index:0}, got={Name:e Scope:GLOBAL Index:0}
 symbol_table_test.go:149: expected f to resolve to\
   {Name:f Scope:LOCAL Index:1}, got={Name:f Scope:GLOBAL Index:1}
FAIL
FAIL    monkey/compiler 0.008s

Besides the three test functions concerning themselves with SymbolTable, there’s also TestLetStatementScopes failing and reminding us that we need to go back to our compiler once we’re done with extending SymbolTable. That won’t take too long – we can make all of the other tests pass with a tiny number of changes.

Now that we have the Outer field on SymbolTable, the Resolve and Define methods need to make use of it. We’ll start with Define. Here’s what it needs to do: if the SymbolTable being called is not enclosed in another SymbolTable, i.e. its Outer field is not set, then its scope is global. If it is enclosed, the scope is local. Every symbol defined in the symbol table should then have the correct scope. Translated into code the changes are barely worth mentioning:

// compiler/symbol_table.go

func (s *SymbolTable) Define(name string) Symbol {
    symbol := Symbol{Name: name, Index: s.numDefinitions}
    if s.Outer == nil {
        symbol.Scope = GlobalScope
    } else {
        symbol.Scope = LocalScope
    }

    s.store[name] = symbol
    s.numDefinitions++
    return symbol
}

New is only the conditional which checks whether s.Outer is nil. If it is, we set the Scope on the symbol to GlobalScope and if it’s not, we set it to LocalScope.

That not only makes TestDefine pass, but a lot of the other test errors also disappear:

$ go test ./compiler
--- FAIL: TestLetStatementScopes (0.00s)
 compiler_test.go:935: testConstants failed:\
   constant 1 - testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetLocal 0\n0005 OpGetLocal 0\n\
    0007 OpReturnValue\n"
  got ="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpGetGlobal 0\n\
    0009 OpReturnValue\n"
--- FAIL: TestResolveLocal (0.00s)
 symbol_table_test.go:94: name a not resolvable
 symbol_table_test.go:94: name b not resolvable
--- FAIL: TestResolveNestedLocal (0.00s)
 symbol_table_test.go:145: name a not resolvable
 symbol_table_test.go:145: name b not resolvable
 symbol_table_test.go:145: name a not resolvable
 symbol_table_test.go:145: name b not resolvable
FAIL
FAIL    monkey/compiler 0.011s

This tells us that we can now Define global and local bindings by enclosing a symbol table in another one. Perfect! But it’s also clear that we do not resolve symbols correctly yet.

The task of Resolve is now to either find symbols in the SymbolTable on which it’s called or – if it exists – in the Outer symbol table. And since symbol tables can be nested arbitrarily deep, Resolve can’t just access the outer symbol table’s store directly but needs to use that table’s Resolve method instead. That one, then, checks its own store and if it can’t find anything there, it needs to use its own outer table’s Resolve method, which again checks its store and i… You get the drift. Recursion.

We need to make Resolve recursive so that it climbs up the Outer symbol table until it either finds a symbol defined somewhere up the chain or tells the caller that it’s not defined:

// compiler/symbol_table.go

func (s *SymbolTable) Resolve(name string) (Symbol, bool) {
    obj, ok := s.store[name]
    if !ok && s.Outer != nil {
        obj, ok = s.Outer.Resolve(name)
        return obj, ok
    }
    return obj, ok
}

Three new lines that check whether the given symbol name can be recursively resolved in any of the Outer symbol tables. Three lines!

$ go test ./compiler
--- FAIL: TestLetStatementScopes (0.00s)
 compiler_test.go:935: testConstants failed:
   constant 1 - testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetLocal 0\n0005 OpGetLocal 0\n\
    0007 OpReturnValue\n"
  got ="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpGetGlobal 0\n\
    0009 OpReturnValue\n"
FAIL
FAIL    monkey/compiler 0.010s

All that’s left is the failing compiler test, which means we successfully fixed all the tests for SymbolTable! Yes! We can now define and resolve symbols in the global and multiple nested local scopes!

But while that’s cause for celebration, I also know that you’re thinking ahead and probably wondering: “but if you define a symbol in a local scope and then resolve it in a deeper scope, the symbol has a local scope, even though it’s – from the perspective of the deepest scope – defined in an outer scope?” You’re on to something. We’ll get to that once we implement closures.

Right now, we still have a failing test to fix.

Compiling With Scopes

Our compiler already knows about scopes. Its enterScope and leaveScope methods are called when compiling a function literal and make sure that emitted instructions end up where they need to. We now need to extend them both so they also enclose and “un-enclose” symbol tables.

The existing TestCompilerScopes test function is the perfect place to test that:

// compiler/compiler_test.go

func TestCompilerScopes(t *testing.T) {
    compiler := New()
    if compiler.scopeIndex != 0 {
        t.Errorf("scopeIndex wrong. got=%d, want=%d", compiler.scopeIndex, 0)
    }
    globalSymbolTable := compiler.symbolTable

    compiler.emit(code.OpMul)

    compiler.enterScope()
    if compiler.scopeIndex != 1 {
        t.Errorf("scopeIndex wrong. got=%d, want=%d", compiler.scopeIndex, 1)
    }

    compiler.emit(code.OpSub)

    if len(compiler.scopes[compiler.scopeIndex].instructions) != 1 {
        t.Errorf("instructions length wrong. got=%d",
            len(compiler.scopes[compiler.scopeIndex].instructions))
    }

    last := compiler.scopes[compiler.scopeIndex].lastInstruction
    if last.Opcode != code.OpSub {
        t.Errorf("lastInstruction.Opcode wrong. got=%d, want=%d",
            last.Opcode, code.OpSub)
    }

    if compiler.symbolTable.Outer != globalSymbolTable {
        t.Errorf("compiler did not enclose symbolTable")
    }

    compiler.leaveScope()
    if compiler.scopeIndex != 0 {
        t.Errorf("scopeIndex wrong. got=%d, want=%d",
            compiler.scopeIndex, 0)
    }

    if compiler.symbolTable != globalSymbolTable {
        t.Errorf("compiler did not restore global symbol table")
    }
    if compiler.symbolTable.Outer != nil {
        t.Errorf("compiler modified global symbol table incorrectly")
    }

    compiler.emit(code.OpAdd)

    if len(compiler.scopes[compiler.scopeIndex].instructions) != 2 {
        t.Errorf("instructions length wrong. got=%d",
            len(compiler.scopes[compiler.scopeIndex].instructions))
    }

    last = compiler.scopes[compiler.scopeIndex].lastInstruction
    if last.Opcode != code.OpAdd {
        t.Errorf("lastInstruction.Opcode wrong. got=%d, want=%d",
            last.Opcode, code.OpAdd)
    }

    previous := compiler.scopes[compiler.scopeIndex].previousInstruction
    if previous.Opcode != code.OpMul {
        t.Errorf("previousInstruction.Opcode wrong. got=%d, want=%d",
            previous.Opcode, code.OpMul)
    }
}

Scattered among the existing assertions regarding the compiler’s scopes stack we now have new code that makes sure enterScope and leaveScope enclose and “un-enclose” the compiler’s symbolTable respectively. Testing that is as easy as checking whether the Outer field of the symbolTable is nil or not. And if it’s not, it should point to the globalSymbolTable.

$ go test -run TestCompilerScopes ./compiler
--- FAIL: TestCompilerScopes (0.00s)
 compiler_test.go:41: compiler did not enclose symbolTable
FAIL
FAIL    monkey/compiler 0.008s

To make this test green, we need to enclose a symbol table in the global one every time we enter a scope:

// compiler/compiler.go

func (c *Compiler) enterScope() {
    // [...]

    c.symbolTable = NewEnclosedSymbolTable(c.symbolTable)
}

That makes the compiler use a fresh, enclosed symbol table when it compiles a function’s body. Exactly what we want, but we also need to undo it once the function is fully compiled:

// compiler/compiler.go

func (c *Compiler) leaveScope() code.Instructions {
    // [...]

    c.symbolTable = c.symbolTable.Outer

    return instructions
}

Again, it’s only one new line, but it’s enough to fix this test:

$ go test -run TestCompilerScopes ./compiler
ok      monkey/compiler 0.006s

However, the test that’s been haunting us for a while now is still failing:

$ go test ./compiler
--- FAIL: TestLetStatementScopes (0.00s)
 compiler_test.go:947: testConstants failed:\
   constant 1 - testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetLocal 0\n0005 OpGetLocal 0\n\
    0007 OpReturnValue\n"
  got ="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpGetGlobal 0\n\
    0009 OpReturnValue\n"
FAIL
FAIL    monkey/compiler 0.009s

But we’re finally ready to fix it. We have all the necessary parts in place and now we just need to use them and to finally listen to what our symbol table really has to say.

Up until now, we always emitted OpSetGlobal and OpGetGlobal instructions – no matter what the symbol table might say about the scope of a symbol. Granted, “might” is the important word here. Because even if we would have listened, the symbol table would’ve always replied with GlobalScope. That’s changed and we can now use a Symbol’s scope to emit the correct instructions.

The first place to do that is the case branch for *ast.LetStatements:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.LetStatement:
        err := c.Compile(node.Value)
        if err != nil {
            return err
        }

        symbol := c.symbolTable.Define(node.Name.Value)
        if symbol.Scope == GlobalScope {
            c.emit(code.OpSetGlobal, symbol.Index)
        } else {
            c.emit(code.OpSetLocal, symbol.Index)
        }

    // [...]
    }

    // [...]
}

New is the check for the symbol.Scope and, depending on its outcome, the emitting of an OpSetGlobal or OpSetLocal instruction. As you can see, most of the work is done by the SymbolTable and we just listen to what it tells us:

$ go test ./compiler
--- FAIL: TestLetStatementScopes (0.00s)
 compiler_test.go:947: testConstants failed:\
   constant 1 - testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetLocal 0\n0005 OpGetLocal 0\n\
    0007 OpReturnValue\n"
  got ="0000 OpConstant 0\n0003 OpSetLocal 0\n0005 OpGetGlobal 0\n\
    0008 OpReturnValue\n"
FAIL
FAIL    monkey/compiler 0.007s

Finally, the OpSetLocal instruction is there. The creation of local bindings is now being properly compiled. Now we need to do the same for the other side, the resolving of a name:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.Identifier:
        symbol, ok := c.symbolTable.Resolve(node.Value)
        if !ok {
            return fmt.Errorf("undefined variable %s", node.Value)
        }

        if symbol.Scope == GlobalScope {
            c.emit(code.OpGetGlobal, symbol.Index)
        } else {
            c.emit(code.OpGetLocal, symbol.Index)
        }

    // [...]
    }

    // [...]
}

The only difference to the previous change is that here the opcodes are OpGetGlobal and OpGetLocal. And with that, the tests are passing – all of them:

$ go test ./compiler
ok      monkey/compiler 0.008s

It’s time to move on over to the VM.

Implementing Local Bindings in the VM

Now that the bytecode is able to represent the creation and resolution of local bindings with OpSetLocal and OpGetLocal instructions and the compiler knows how to emit them, the task at hand is clear: we need to implement local bindings in the VM.

That means we need to, first, create bindings when we execute OpSetLocal instructions and then, second, resolve those bindings when we execute OpGetLocal instructions. That’s similar to the implementation of global bindings, except that the storage must now be different – it must be local.

But while the storage of the local bindings is more than a mere implementation detail and can play a crucial role in the performance of a VM, it shouldn’t concern the user of the VM where and how they’re stored. The most important thing is that they work as expected, which is what this test describes:

// vm/vm_test.go

func TestCallingFunctionsWithBindings(t *testing.T) {
    tests := []vmTestCase{
        {
            input: `
        let one = fn() { let one = 1; one };
        one();
        `,
            expected: 1,
        },
        {
            input: `
        let oneAndTwo = fn() { let one = 1; let two = 2; one + two; };
        oneAndTwo();
        `,
            expected: 3,
        },
        {
            input: `
        let oneAndTwo = fn() { let one = 1; let two = 2; one + two; };
        let threeAndFour = fn() { let three = 3; let four = 4; three + four; };
        oneAndTwo() + threeAndFour();
        `,
            expected: 10,
        },
        {
            input: `
        let firstFoobar = fn() { let foobar = 50; foobar; };
        let secondFoobar = fn() { let foobar = 100; foobar; };
        firstFoobar() + secondFoobar();
        `,
            expected: 150,
        },
        {
            input: `
        let globalSeed = 50;
        let minusOne = fn() {
            let num = 1;
            globalSeed - num;
        }
        let minusTwo = fn() {
            let num = 2;
            globalSeed - num;
        }
        minusOne() + minusTwo();
        `,
            expected: 97,
        },
    }

    runVmTests(t, tests)
}

All of these test cases assert that local bindings work, each one concentrating on a different aspect of the feature.

The first test case makes sure that local bindings work at all. The second one tests multiple local bindings in the same function. The third one tests multiple local bindings in different functions, while the fourth one does a slight variation of that by making sure that local bindings with the same name in different functions do not cause problems.

Take a look at the last test case, the one with globalSeed and minusOne – remember that? That’s our main goal for this section! That’s what we set out to compile and to execute. But, alas, the test output confirms that we’ve done the compilation part but not much execution:

$ go test ./vm
--- FAIL: TestCallingFunctionsWithBindings (0.00s)
panic: runtime error: index out of range [recovered]
 panic: runtime error: index out of range

goroutine 37 [running]:
testing.tRunner.func1(0xc4204e60f0)
 /usr/local/go/src/testing/testing.go:742 +0x29d
panic(0x11211a0, 0x11fffe0)
 /usr/local/go/src/runtime/panic.go:502 +0x229
monkey/vm.(*VM).Run(0xc420527e58, 0x10000, 0x10000)
 /Users/mrnugget/code/07/src/monkey/vm/vm.go:78 +0xb54
monkey/vm.runVmTests(0xc4204e60f0, 0xc420527ef8, 0x5, 0x5)
 /Users/mrnugget/code/07/src/monkey/vm/vm_test.go:266 +0x5d6
monkey/vm.TestCallingFunctionsWithBindings(0xc4204e60f0)
 /Users/mrnugget/code/07/src/monkey/vm/vm_test.go:326 +0xe3
testing.tRunner(0xc4204e60f0, 0x1153b68)
 /usr/local/go/src/testing/testing.go:777 +0xd0
created by testing.(*T).Run
 /usr/local/go/src/testing/testing.go:824 +0x2e0
FAIL    monkey/vm   0.041s

Let’s think this through. How do we implement local bindings? We know that local bindings come with a unique index, just like their global counterparts. So, here too, we can use the operand of an OpSetLocal instruction, the unique index, as an index into a data structure to store and retrieve the value being bound to a name.

The question is: index into which data structure? And where is this data structure located? We can’t just use the globals slice stored on the VM, since that would defy having local bindings in the first place. We need something different.

There are two main options. The first one is to dynamically allocate the local bindings and store them in their own data structure. That could be a slice, for example. Whenever a function is called an empty slice would then be allocated and used to store and retrieve locals. Then there’s the second option: reusing what we already have. Because we do have a place in memory where we store data that’s relevant to the current function being called. It’s called the stack.

Now, storing locals on the stack is the elaborate choice, but lots of fun to implement. It can also teach us a great deal and not just about our VM and compiler, but about computers and low-level programming in general, where using the stack like this is common practice. That’s why we’re choosing this, even though we normally opt for the easiest option, because this time, the increased effort is worth it.

Here’s how it works. When we come across an OpCall instruction in the VM and are about to execute the function on the stack, we take the current value of the stack pointer and put it aside – for later use. We then increase the stack pointer by the number of locals used by the function we’re about to execute. The result is a “hole” on the stack: we’ve increased the stack pointer without pushing any values, creating a region on the stack without any values. Below the hole: all the values previously pushed on to the stack, before the function call. And above the hole is the function’s workspace, where it will push and pop the values it needs to do its work.

The hole itself is where we’re going to store local bindings. We won’t use the unique index of a local binding as a key for another data structure, but instead as an index into the hole on the stack.

We already have the necessary parts to pull this off: the value of the stack pointer before executing the function, giving us the lower boundary of the hole, and an index that increases with every local. We can use both to calculate a stack slot index for each local binding by adding them together. Every index calculated this way serves as an offset into the hole and points to the slot where we’ll store the local binding.

The beauty of this approach is what happens when we’re done executing a function. Since we put the previous value of the stack pointer aside, we can now simply restore it and thus “reset” the stack. That removes not only everything the function call may have left on the stack, but also the local bindings saved in the hole – everything is squeaky-clean again!

“That’s all fine and good”, you say, “but how do we know how many locals a function is going to use?” Good catch; you got me. It’s true, we don’t know. At least not in the VM. In the compiler, on the other hand, we do and it’s rather trivial for us to pass this information on to the VM.

What we need to do first is to extend our object.CompiledFunction by one field:

// object/object.go

type CompiledFunction struct {
    Instructions code.Instructions
    NumLocals    int
}

NumLocals will later on tell us how many local bindings this function is going to create. In the compiler we can now ask the symbol table how many symbols were defined while compiling a function and put that number into NumLocals:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.FunctionLiteral:
        // [...]

        numLocals := c.symbolTable.numDefinitions
        instructions := c.leaveScope()

        compiledFn := &object.CompiledFunction{
            Instructions: instructions,
            NumLocals:    numLocals,
        }
        c.emit(code.OpConstant, c.addConstant(compiledFn))

    // [...]
    }

    // [...]
}

Right before we call c.leaveScope, we take the current symbol table’s numDefinitions, put it aside and, after leaving the scope, save it to the *object.CompiledFunction. That gives us the number of local bindings a function is going to create and use in the VM. First mini-challenge completed! Sweet!

Now, according to our plan the other thing we need to do is to keep track of the stack pointer’s value before we execute a function and then restore it to this value after executing. So in other words, we need a temporary storage that lives as long as a function call. Guess what? We already have that and call it Frame. We only need to add one more field to it, the so called basePointer:

// vm/frame.go

type Frame struct {
    fn          *object.CompiledFunction
    ip          int
    basePointer int
}

func NewFrame(fn *object.CompiledFunction, basePointer int) *Frame {
    f := &Frame{
        fn:          fn,
        ip:          -1,
        basePointer: basePointer,
    }

    return f
}

The name “base pointer” is not something I made up. On the contrary, it’s common practice to give this name to the pointer that points to the bottom of the stack of the current call frame. It’s the base for a lot of references while executing a function. Sometimes it’s also called “frame pointer”. In the upcoming sections of this book we’ll use it even more. Right now, we just need to initialize it before we push a new frame:

// vm/vm.go

func New(bytecode *compiler.Bytecode) *VM {
    // [...]

    mainFrame := NewFrame(mainFn, 0)

    // [...]
}

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpCall:
            fn, ok := vm.stack[vm.sp-1].(*object.CompiledFunction)
            if !ok {
                return fmt.Errorf("calling non-function")
            }
            frame := NewFrame(fn, vm.sp)
            vm.pushFrame(frame)

        // [...]
        }
    // [...]
}

In the vm.New function we pass in 0 as the current value of the stack pointer so we can make our mainFrame work properly, even though this particular frame should never be popped off the stack and doesn’t have local bindings. The setup of the new frame in the case code.OpCall branch is what we’re really after. New is the second argument in the call to NewFrame, the current value of vm.sp, which will serve as the basePointer for the new frame.

Alright! We now have a basePointer in place and we know how many locals a function is going to use. That leaves us with two tasks: Allocate space for the local bindings on the stack before executing a function. Meaning: creating the “hole”. And we also need to implement OpSetLocal and OpGetLocal instructions in the VM to use it.

“Allocating space on the stack” sounds fancy, but comes down to increasing the value of vm.sp without pushing something. And since we already save its value to the side before executing a function, we already have a perfect place, where we can do that:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpCall:
            fn, ok := vm.stack[vm.sp-1].(*object.CompiledFunction)
            if !ok {
                return fmt.Errorf("calling non-function")
            }
            frame := NewFrame(fn, vm.sp)
            vm.pushFrame(frame)
            vm.sp = frame.basePointer + fn.NumLocals

        // [...]
        }
    // [...]
}

We set vm.sp to frame.basePointer + fn.NumLocals to make clear that the starting point is basePointer and that we reserve fn.NumLocals slots on the stack. These slots might contain no or old values and in either case, we don’t care. We can now use this region of the stack for local bindings and the normal usage of the stack – the pushing and popping of temporary values – won’t affect it.

Next up: implement OpSetLocal and OpGetLocal instructions in our VM. We’ll start with OpSetLocal.

What we have to do is very similar to what we did for global bindings: read in the operand, pop the value that should be bound off the stack and store it.

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpSetLocal:
            localIndex := code.ReadUint8(ins[ip+1:])
            vm.currentFrame().ip += 1

            frame := vm.currentFrame()

            vm.stack[frame.basePointer+int(localIndex)] = vm.pop()

        // [...]
        }
    // [...]
}

After decoding the operand and getting the current frame, we take the basePointer of the frame and add the index of the binding in question as an offset. The result is the index of the location on the stack to which we can save the binding. We then pop the value off the stack and save it to the computed location. Done. Local binding created.

Implementing OpGetLocal means doing the opposite. Instead of assigning a value, we retrieve it. The rest is exactly the same:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpGetLocal:
            localIndex := code.ReadUint8(ins[ip+1:])
            vm.currentFrame().ip += 1

            frame := vm.currentFrame()

            err := vm.push(vm.stack[frame.basePointer+int(localIndex)])
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

Done! Let’s see what our tests have to say:

$ go test ./vm
--- FAIL: TestCallingFunctionsWithBindings (0.00s)
  vm_test.go:444: vm error: unsupported types for binary operation:\
    COMPILED_FUNCTION_OBJ INTEGER
FAIL
FAIL    monkey/vm       0.031s

What? In none of our test cases do we try to add a function to an integer. That would only happen if we leave functions lying around on the sta- Aha! We forgot to clean up the stack! We have the basePointer in place but we don’t use it to reset our vm.sp after we’re done executing a function.

We know where to do that, though: when we come across an OpReturnValue or an OpReturn instruction. Currently, we only take the return value and the just executed function off the stack. Now we need to get rid of the local bindings, too. The easiest way to do that is to set the stack pointer to the basePointer of the frame that holds the just-executed function:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpReturnValue:
            returnValue := vm.pop()

            frame := vm.popFrame()
            vm.sp = frame.basePointer - 1

            err := vm.push(returnValue)
            if err != nil {
                return err
            }

        case code.OpReturn:
            frame := vm.popFrame()
            vm.sp = frame.basePointer - 1

            err := vm.push(Null)
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

When we return from a function we first pop the frame off the frame stack. Previously we also did that, but didn’t save the popped frame. Now we also set vm.sp to frame.basePointer - 1. Where does the additional -1 come from? It’s an optimization: setting vm.sp to frame.basePointer would get rid of the local bindings, but it would still leave the just-executed function on the stack. So instead of keeping around the vm.pop() we previously had in place there, we replace it by decrementing vm.sp even further.

And with that, we’re done. Yes, really. We’re at the end of a journey that began with the definition of the OpSetLocal and OpGetLocal opcodes, led us from the compiler tests through the symbol table back to the compiler and finally, with a little detour back to object.CompiledFunction, landed us in the VM. Local bindings work:

$ go test ./vm
ok      monkey/vm   0.039s

We can now compile and execute this piece of Monkey code:

let globalSeed = 50;
let minusOne = fn() {
  let num = 1;
  globalSeed - num;
}
let minusTwo = fn() {
  let num = 2;
  globalSeed - num;
}
minusOne() + minusOne()

And there’s more. We got an upgrade to our first-class functions without, again, explicitly setting out to do so. We can now take functions and assign them to names – in other functions:

// vm/vm_test.go

func TestFirstClassFunctions(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {
            input: `
        let returnsOneReturner = fn() {
            let returnsOne = fn() { 1; };
            returnsOne;
        };
        returnsOneReturner()();
        `,
            expected: 1,
        },
    }

    runVmTests(t, tests)
}

Yep, that passes:

$ go test ./vm
ok      monkey/vm   0.037s

Now that we’ve reached our goal, where do we go next? Arguments to function calls – they are much closer to where we are than you might think.

Arguments

Let’s start this section with a little recap. In Monkey we can define functions to have parameters, like this:

let addThree = fn(a, b, c) {
  a + b + c;
}

This function has three parameters: a, b, and c. When we call it we can use arguments in the call expression:

addThree(1, 2, 3);

This binds the values passed in as arguments to the parameter names while the function executes. Now, the “bind” should ring a bell but I don’t want to beat around the bush, so let me come straight out with it: arguments to function calls are a special case of local bindings.

They have the same lifespan, they have the same scope, they resolve in the same way. The only difference is their creation. Local bindings are created explicitly by the user with a let statement and result in OpSetLocal instructions being emitted by the compiler. Arguments, on the other hand, are implicitly bound to names, which is done behind the scenes by the compiler and the VM. And that leads us to our list of tasks for this section.

Our goal in this section is to fully implement function parameters and arguments to function calls. At the end, we want to compile and execute this snippet of Monkey code:

let globalNum = 10;

let sum = fn(a, b) {
  let c = a + b;
  c + globalNum;
};

let outer = fn() {
  sum(1, 2) + sum(3, 4) + globalNum;
};

outer() + globalNum;

At first glance, this looks quite chaotic. That’s intentional. It’s a mixture of everything we’ve already implemented and the things we’re about to build: global and local bindings, functions with and without parameters, function calls with and without arguments.

So what’s our plan? First, we need to rethink our calling convention. In its current form it doesn’t accommodate for arguments. Then, as the second and already final step, we need to implement this updated calling convention. But let’s start at the beginning.

Compiling Calls With Arguments

The condensed version of our current calling convention is this: push the function you want to call on to the stack, emit OpCall and off you go. The question we’re now facing is where to put the arguments to the function call – not only “where” in the sense of a memory location, but also where in the calling convention.

We don’t have to search for a memory location for too long, because we already have a place where we store data that’s relevant to the current function call: the stack. And just like we use the stack to store the function that’s to be called, we can use it to store the arguments to the call.

But how do we get them on there? The easiest way is to simply push them on the stack right after the function has been pushed. And, surprisingly enough, there’s nothing that speaks against this pragmatic solution. It’s actually quite elegant, as we’ll later see.

So, if we adopt this approach, it changes our calling convention to this: push the function you want to call on to the stack, then push all the arguments to the call on to the stack, emit OpCall and off you go. The stack would then look like this, right before executing OpCall:

As things stand, though, that solution poses a slight problem to our VM, because it wouldn’t know how many arguments are on top of the stack.

Think of our implementation of OpCall in the VM. Before we push a new frame, we take the function to be called right off the top of the stack. With this new calling convention, there could be zero or multiple arguments on the stack – on top of the function. How do we reach the function on the stack so we can execute it?

Since functions are ordinary Monkey object.Objects we can’t even choose the hacky way and traverse the stack to find the first object.CompiledFunction; that might just be an argument to the function call.

Thankfully, we don’t have to resort to hacky and ugh-this-feels-dirty fixes. There’s a simple and beautiful solution available: we give the OpCall opcode an operand that holds the number of arguments of the call. One byte is enough for that (or do you want to call functions with more than 256 arguments?) and allows us, by doing a little calculation, to find the function below the arguments.

So, let’s add an operand to OpCall:

// code/code.go

var definitions = map[Opcode]*Definition{
    // [...]

    OpCall:        {"OpCall", []int{1}},

    // [...]
}

With this change some tests are breaking due to panics and index errors, because we defined something neither the compiler nor the VM know about. That’s not a problem per se, but the definition of the new operand causes our code.Make function to create an empty byte in its place – even if we don’t pass in an operand. We end up in this sort of limbo, where different parts in our system act on different assumptions and nobody knows what’s really happened. We need to restore order again.

We’ll start by updating our existing compiler tests and making sure that we do pass in an operand when creating OpCall instructions:

// compiler/compiler_test.go

func TestFunctionCalls(t *testing.T) {
    tests := []compilerTestCase{
        {
            // [...]
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 1), // The compiled function
                code.Make(code.OpCall, 0),
                code.Make(code.OpPop),
            },
        },
        {
            // [...]
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 1), // The compiled function
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpCall, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

That makes the compiler tests correct and the compiler itself is fine for now, because it also uses code.Make to emit instructions, which, again, adds an empty byte for the new operand, even if none was passed in as argument.

The VM, though, stumbles and trips over the new operand, empty or not. The solution for now, at least until we’ve written the tests to tell us what we actually want, is to simply skip it:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpCall:
            vm.currentFrame().ip += 1
            // [...]

        // [...]
        }
    // [...]
}

Order is restored:

$ go test ./...
?       monkey  [no test files]
ok      monkey/ast  0.014s
ok      monkey/code 0.014s
ok      monkey/compiler 0.011s
ok      monkey/evaluator    0.014s
ok      monkey/lexer    0.011s
ok      monkey/object   0.014s
ok      monkey/parser   0.009s
?       monkey/repl [no test files]
?       monkey/token    [no test files]
ok      monkey/vm   0.037s

We’re back on track and can now write a test to make sure the compiler conforms to the updated calling convention by emitting instructions that push the arguments on to the stack. Since we already have TestFunctionCalls in place, we can extend it with new test cases instead of having to add a new test function:

// compiler/compiler_test.go

func TestFunctionCalls(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input: `
            let oneArg = fn(a) { };
            oneArg(24);
            `,
            expectedConstants: []interface{}{
                []code.Instructions{
                    code.Make(code.OpReturn),
                },
                24,
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpCall, 1),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            let manyArg = fn(a, b, c) { };
            manyArg(24, 25, 26);
            `,
            expectedConstants: []interface{}{
                []code.Instructions{
                    code.Make(code.OpReturn),
                },
                24,
                25,
                26,
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpConstant, 3),
                code.Make(code.OpCall, 3),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

It’s worth noting that the functions used in these new test cases have an empty body and don’t make use of their parameters. That’s by design. We first want to make sure that we can compile function calls and once we have that in place, we’ll reference the parameters in the same tests and update our expectations.

As you can see in the expectedInstructions of these test cases, the first argument to the function call should end up lowest on the stack. From our current point of view, it doesn’t really matter, but soon we’ll see how much nicer that makes things in the VM once we start to reference parameters.

The output of these new tests is quite instructive:

$ go test ./compiler
--- FAIL: TestFunctionCalls (0.00s)
 compiler_test.go:889: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpGetGlobal 0\n\
    0009 OpConstant 1\n0012 OpCall 1\n0014 OpPop\n"
  got ="0000 OpConstant 0\n0003 OpSetGlobal 0\n0006 OpGetGlobal 0\n\
    0009 OpCall 0\n0011 OpPop\n"
FAIL
FAIL    monkey/compiler 0.008s

The missing OpConstant instructions tell us that we need to compile the arguments of the function call and the wrong operand of OpCall tells us that it’s still unused.

We can do both by updating our case branch in the compiler for *ast.CallExpressions to this:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.CallExpression:
        err := c.Compile(node.Function)
        if err != nil {
            return err
        }

        for _, a := range node.Arguments {
            err := c.Compile(a)
            if err != nil {
                return err
            }
        }

        c.emit(code.OpCall, len(node.Arguments))

    // [...]
    }

    // [...]
}

What hasn’t changed here is the compilation of the node.Function. But now, with the new calling convention, that’s only the first step. We also need to push the arguments to the function call on to the stack.

We do that by compiling the arguments in sequence, using a loop. Since each argument is an *ast.Expression it’s compiled to one or more instructions that push a value on to the stack. The result is that the arguments end up on the stack above the function we want to call, exactly where the calling convention needs them to be. And to tell our VM how many arguments are now sitting above the function, we use len(node.Arguments) as the operand to OpCall.

Done. The tests are green:

$ go test ./compiler
ok      monkey/compiler 0.008s

We can now compile call expressions with arguments. Now we can start to think about using those arguments in the function’s body.

Resolving References to Arguments

Before we update our test cases and replace those empty function bodies, let’s be sure about what we expect from the compiler. At the time of a function call, the arguments will now sit on the stack. How do we access them while the function is executing?

Should we add a new opcode, something like OpGetArgument, that tells the VM to push the argument on to the stack? For that we would need to give the arguments their own scope and index in the symbol table. Otherwise we wouldn’t know which opcode to emit when we come across a reference to an argument.

That’s a viable solution and if our goal was to explicitly treat arguments different from local bindings, then we should choose it, because it offers much more flexibility in that direction. But we don’t. In Monkey there is no difference between arguments passed in to a function and a local binding created in the same function. The better option for us is to embrace that and treat them the same.

Once you look at the stack at the time of a function call, it also becomes the obvious choice. The arguments sit right above the function that’s being called. And you know what’s normally stored in this region of the stack? Exactly! Local bindings! So if we treat arguments as locals, they would already be exactly where they need to be. The only thing we would then have to do is to treat them as locals in the compiler.

In practical terms that means emitting OpGetLocal instructions for every reference to a function’s parameter. In order to test that, we update our last two test cases in TestFunctionCalls:

// compiler/compiler_test.go

func TestFunctionCalls(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input: `
            let oneArg = fn(a) { a };
            oneArg(24);
            `,
            expectedConstants: []interface{}{
                []code.Instructions{
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpReturnValue),
                },
                24,
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpCall, 1),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            let manyArg = fn(a, b, c) { a; b; c };
            manyArg(24, 25, 26);
            `,
            expectedConstants: []interface{}{
                []code.Instructions{
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpPop),
                    code.Make(code.OpGetLocal, 1),
                    code.Make(code.OpPop),
                    code.Make(code.OpGetLocal, 2),
                    code.Make(code.OpReturnValue),
                },
                24,
                25,
                26,
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpConstant, 3),
                code.Make(code.OpCall, 3),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Instead of empty function bodies, we now have references to the parameters of the functions. And the updated expectations tell the compiler that these references should be turned into OpGetLocal instructions that load the arguments on to the stack. The indexes to these OpGetLocal instructions start at 0 for the first argument and then increment with each next one. Just like other local bindings.

If we run the tests we can see that the compiler can’t resolve these references yet:

$ go test ./compiler
--- FAIL: TestFunctionCalls (0.00s)
 compiler_test.go:541: compiler error: undefined variable a
FAIL
FAIL    monkey/compiler 0.009s

And here’s where we step into “oh, nice” territory. All it takes for us to fix this is to define the parameters of a function as a local binding. And “define” is meant to be taken literally here. It’s just one method call:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.FunctionLiteral:
        c.enterScope()

        for _, p := range node.Parameters {
            c.symbolTable.Define(p.Value)
        }

        err := c.Compile(node.Body)
        if err != nil {
            return err
        }
        // [...]

    // [...]
    }

    // [...]
}

After entering a new scope and right before compiling the function’s body we define each parameter in the scope of the function. That allows the symbol table (and in turn the compiler) to resolve the new references and treat them as locals when compiling the function’s body. Look:

$ go test ./compiler
ok      monkey/compiler 0.009s

Isn’t that neat?

Arguments in the VM

Remember that our goal is to compile and get this piece of Monkey code running in our VM:

let globalNum = 10;

let sum = fn(a, b) {
  let c = a + b;
  c + globalNum;
};

let outer = fn() {
  sum(1, 2) + sum(3, 4) + globalNum;
};

outer() + globalNum;

We’re nearly there. We can already extract bits of this snippet and turn them into a test for the VM:

// vm/vm_test.go

func TestCallingFunctionsWithArgumentsAndBindings(t *testing.T) {
    tests := []vmTestCase{
        {
            input: `
        let identity = fn(a) { a; };
        identity(4);
        `,
            expected: 4,
        },
        {
            input: `
        let sum = fn(a, b) { a + b; };
        sum(1, 2);
        `,
            expected: 3,
        },
    }

    runVmTests(t, tests)
}

That shows what we’re after in its most basic form. In the first test case we pass one argument to a function that only references its single argument and returns it. The second test case is the sanity check that makes sure we’re not hard-coding edge cases into our VM and can also handle multiple arguments. Both fail:

$ go test ./vm
--- FAIL: TestCallingFunctionsWithArgumentsAndBindings (0.00s)
 vm_test.go:709: vm error: calling non-function
FAIL
FAIL    monkey/vm   0.039s

This is interesting. The test doesn’t fail because the VM can’t find the arguments on the stack. It fails because it can’t find the function. And that’s because it’s looking in the wrong place.

The VM still expects the function to sit on top of the stack – correct behaviour according to the old calling convention. But since we updated the compiler, the emitted instructions not only put the function on the stack, but also the arguments. That’s why the VM says it can’t call a non-function: it trips over the arguments.

The fix is to use the operand of the OpCall instruction as it was designed to be used: to reach further down the stack to get to the function.

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpCall:
            numArgs := code.ReadUint8(ins[ip+1:])
            vm.currentFrame().ip += 1

            fn, ok := vm.stack[vm.sp-1-int(numArgs)].(*object.CompiledFunction)
            if !ok {
                return fmt.Errorf("calling non-function")
            }
            frame := NewFrame(fn, vm.sp)
            vm.pushFrame(frame)
            vm.sp = frame.basePointer + fn.NumLocals

        // [...]
        }
    // [...]
}

Instead of simply grabbing the function off the top of the stack, we calculate its position by decoding the operand, numArgs, and subtracting it from vm.sp. The additional -1 is there because vm.sp doesn’t point to the topmost element on the stack, but the slot where the next element will be pushed.

That gets us a little bit further, but not by much:

$ go test ./vm
--- FAIL: TestCallingFunctionsWithArgumentsAndBindings (0.00s)
 vm_test.go:357: testIntegerObject failed:\
   object is not Integer. got=<nil> (<nil>)
panic: runtime error: \
  invalid memory address or nil pointer dereference [recovered]
 panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x20 pc=0x10f7841]

goroutine 13 [running]:
testing.tRunner.func1(0xc4200a80f0)
 /usr/local/go/src/testing/testing.go:742 +0x29d
panic(0x11215e0, 0x11fffa0)
 /usr/local/go/src/runtime/panic.go:502 +0x229
monkey/vm.(*VM).executeBinaryOperation(0xc4204b3eb8, 0x1, 0x0, 0x0)
 /Users/mrnugget/code/07/src/monkey/vm/vm.go:270 +0xa1
monkey/vm.(*VM).Run(0xc4204b3eb8, 0x10000, 0x10000)
 /Users/mrnugget/code/07/src/monkey/vm/vm.go:87 +0x155
monkey/vm.runVmTests(0xc4200a80f0, 0xc4204b3f58, 0x2, 0x2)
 /Users/mrnugget/code/07/src/monkey/vm/vm_test.go:276 +0x5de
monkey/vm.TestCallingFunctionsWithArgumentsAndBindings(0xc4200a80f0)
 /Users/mrnugget/code/07/src/monkey/vm/vm_test.go:357 +0x93
testing.tRunner(0xc4200a80f0, 0x11540e8)
 /usr/local/go/src/testing/testing.go:777 +0xd0
created by testing.(*T).Run
 /usr/local/go/src/testing/testing.go:824 +0x2e0
FAIL    monkey/vm   0.049s

The first test case tells us that the value that was last popped off the stack is not the expected 4, but nil. Alright. Apparently the VM can’t find the arguments on the stack.

The second test case doesn’t tell us anything but blows up. Why it does that is not immediately visible and requires some walking up of the stack trace. And once we reach vm.go we find the reason for the panic: the VM tries to call the object.Object.Type method on two nil pointers, which it popped off the stack in order to add them together.

Both failures come down to the same thing: the VM tries to find the arguments on the stack but gets nils instead.

That at least something doesn’t work is kinda what we expected. But then again, not really. The arguments sit on top of the stack, right above the function being called. That’s where local bindings are supposed to be stored. And since we treat arguments as locals and want to retrieve them with OpGetLocal instructions, that’s exactly where they should be. That’s the beauty behind the whole idea of treating arguments as locals. So why can’t the VM find them?

Short answer: because our stack pointer is too high. The way we initialize it together with basePointer when setting up a new frame is outdated.

Remember that the basePointer of Frame has two purposes. First, it serves as a reset button we can push to get rid of a just-executed function and everything the function left on the stack by setting vm.sp to the basePointer - 1.

The second one is to serve as a reference for local bindings. This is where the bug hides. Right before we execute a function we set basePointer to the current value of vm.sp. Then we increase vm.sp by the number of locals the function’s going to use, which gives us what we called “the hole”: N slots on the stack which we can use to store and retrieve local bindings.

What makes our tests fail is that before we execute the function, we already have things on the stack we want to use as locals: the arguments of the call. And we want to access them with the same formula we use for other local bindings: basePointer plus individual local-binding index. The problem is that when we now initialize a new frame, the stack looks like this:

I bet you can see the problem. We set basePointer to the current value of vm.sp after we pushed the arguments on the stack. That leads to basePointer plus the index of the local binding pointing to empty stack slots. And the result of that is that the VM gets nils instead of the arguments it wants.

We need to adjust the basePointer. We can’t just clone vm.sp anymore. But the new and correct formula for basePointer is not much harder to understand: basePointer = vm.sp - numArguments. That results in this stack layout at the start of a function call:

That would work. With this, if we’d compute basePointer plus local binding index of the argument, we’d get the correct slot. And on top of that (pun intended!) the vm.sp would still point to the next empty slot on the stack. Perfect!

Here is this idea’s translation into code:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpCall:
            numArgs := code.ReadUint8(ins[ip+1:])
            vm.currentFrame().ip += 1

            err := vm.callFunction(int(numArgs))
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

func (vm *VM) callFunction(numArgs int) error {
    fn, ok := vm.stack[vm.sp-1-numArgs].(*object.CompiledFunction)
    if !ok {
        return fmt.Errorf("calling non-function")
    }

    frame := NewFrame(fn, vm.sp-numArgs)
    vm.pushFrame(frame)

    vm.sp = frame.basePointer + fn.NumLocals

    return nil
}

Before it’s too late, we move the main part of the OpCall implementation to a new method, called callFunction. Don’t be fooled, though, barely anything has changed in the implementation itself. The only difference is the second argument in the call to NewFrame. Instead of passing in vm.sp as the future basePointer for the frame, we first subtract numArgs. That gives us the basePointer as pictured in the diagram earlier.

Now look at that:

$ go test ./vm
ok      monkey/vm   0.047s

All of our tests are passing! Let’s roll the dice, go even further and throw some more tests at our VM:

// vm/vm_test.go

func TestCallingFunctionsWithArgumentsAndBindings(t *testing.T) {
    tests := []vmTestCase {
        // [...]
        {
            input: `
        let sum = fn(a, b) {
            let c = a + b;
            c;
        };
        sum(1, 2);
        `,
            expected: 3,
        },
        {
            input: `
        let sum = fn(a, b) {
            let c = a + b;
            c;
        };
        sum(1, 2) + sum(3, 4);`,
            expected: 10,
        },
        {
            input: `
        let sum = fn(a, b) {
            let c = a + b;
            c;
        };
        let outer = fn() {
            sum(1, 2) + sum(3, 4);
        };
        outer();
        `,
            expected: 10,
        },
    }

    runVmTests(t, tests)
}

These test cases make sure that we can mix manually created local bindings with arguments: in one function, or in the same function that’s called multiple times or in one function that’s called multiple times in another function. They all pass:

$ go test ./vm
ok      monkey/vm   0.041s

Now, let’s see whether we’ve reached our goal:

// vm/vm_test.go

func TestCallingFunctionsWithArgumentsAndBindings(t *testing.T) {
    tests := []vmTestCase {
        // [...]
        {
            input: `
        let globalNum = 10;

        let sum = fn(a, b) {
            let c = a + b;
            c + globalNum;
        };

        let outer = fn() {
            sum(1, 2) + sum(3, 4) + globalNum;
        };

        outer() + globalNum;
        `,
            expected: 50,
        },
    }

    runVmTests(t, tests)
}

Running this test will tell us:

$ go test ./vm
ok      monkey/vm   0.035s

Yes, we did! We’ve successfully added function call arguments to our compiler and our VM!

Now we just need to make sure that the stack doesn’t come tumbling down when we call a function with the wrong number of arguments, since a lot of our implementation hinges on that number:

// vm/vm_test.go

func TestCallingFunctionsWithWrongArguments(t *testing.T) {
    tests := []vmTestCase{
        {
            input:    `fn() { 1; }(1);`,
            expected: `wrong number of arguments: want=0, got=1`,
        },
        {
            input:    `fn(a) { a; }();`,
            expected: `wrong number of arguments: want=1, got=0`,
        },
        {
            input:    `fn(a, b) { a + b; }(1);`,
            expected: `wrong number of arguments: want=2, got=1`,
        },
    }

    for _, tt := range tests {
        program := parse(tt.input)

        comp := compiler.New()
        err := comp.Compile(program)
        if err != nil {
            t.Fatalf("compiler error: %s", err)
        }

        vm := New(comp.Bytecode())
        err = vm.Run()
        if err == nil {
            t.Fatalf("expected VM error but resulted in none.")
        }

        if err.Error() != tt.expected {
            t.Fatalf("wrong VM error: want=%q, got=%q", tt.expected, err)
        }
    }
}

We want to make sure that we get a VM error when we call a function with the wrong number of arguments. So, yes, this time we want an error, but get none:

$ go test ./vm
--- FAIL: TestCallingFunctionsWithWrongArguments (0.00s)
 vm_test.go:801: expected VM error but resulted in none.
FAIL
FAIL    monkey/vm   0.053s

To fix that we need to make quick trip to the object package and add a new field to the definition of object.CompiledFunction:

// object/object.go

type CompiledFunction struct {
    Instructions  code.Instructions
    NumLocals     int
    NumParameters int
}

We’ll now fill out this new NumParameters field in the compiler, where we have the number of parameters of a function literal at hand:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.FunctionLiteral:
        // [...]

        compiledFn := &object.CompiledFunction{
            Instructions:  instructions,
            NumLocals:     numLocals,
            NumParameters: len(node.Parameters),
        }
        c.emit(code.OpConstant, c.addConstant(compiledFn))

    // [...]
    }

    // [...]
}

In the VM we can use that field to make sure that we have the right number of arguments sitting on the stack:

// vm/vm.go

func (vm *VM) callFunction(numArgs int) error {
    fn, ok := vm.stack[vm.sp-1-numArgs].(*object.CompiledFunction)
    if !ok {
        return fmt.Errorf("calling non-function")
    }

    if numArgs != fn.NumParameters {
        return fmt.Errorf("wrong number of arguments: want=%d, got=%d",
            fn.NumParameters, numArgs)
    }

    // [...]
}

With that, we’re in safe territory:

$ go test ./vm
ok      monkey/vm       0.035s

The stack will hold, even if we call a function with the wrong number of arguments.

Now we can enjoy the fact that we’ve implement functions and function calls in a bytecode compiler and VM, including arguments and local bindings. That’s certainly no small feat and puts us, again, in another league:

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> let one = fn() { 1; };
CompiledFunction[0xc42008a8d0]
>> let two = fn() { let result = one(); return result + result; };
CompiledFunction[0xc42008aba0]
>> let three = fn(two) { two() + 1; };
CompiledFunction[0xc42008ae40]
>> three(two);
3

Time to add another type of function.

Built-in Functions

In Writing An Interpreter In Go we did not only add the ability to define functions to our evaluator, but we also built functions right into it. These functions here:

len([1, 2, 3]);       // => 3
first([1, 2, 3]);     // => 1
last([1, 2, 3]);      // => 3
rest([1, 2, 3]);      // => [2, 3]
push([1, 2, 3], 4);   // => [1, 2, 3, 4]
puts("Hello World!"); // prints "Hello World!"

Our goal for this chapter is to do the same for our new bytecode compiler and virtual machine and build these functions into them. That’s not as easy as one might think.

While these are Go functions and thus should be as portable as any other function we wrote, they took roots in the evaluator package. They’re defined as private, they use internal references and make use of private helper functions – not the best circumstances for using them in the compiler and the vm packages.

So, before we can start to think about executing these built-in functions in the VM, or even mention them in the compiler, we need to refactor some of our code from the previous book to make it easier for our new code to use it.

The obvious, first option is to make the function definitions public. Uppercase their names, done. That would work, yes, but it would also clash with something delicate – my taste. I don’t want the compiler nor the VM to depend on the evaluator, which is what this course of action would lead to. Instead, I want all three packages – compiler, vm and evaluator – to have equal access to the built-in functions.

That leads us to the second option: duplicate the definitions, keep one copy for the evaluator and create one for the vm and compiler packages. But then again, we’re programmers, we do not like duplication. In all seriousness, though: duplicating these built-in functions would be a bad idea. Encoded in them is a non-trivial amount of Monkey behaviour, which we don’t want to accidentally fork and diverge.

Instead, we’re going to move these built-in functions to the object package. That takes slightly more effort, but it’s also the most elegant choice, since it makes incorporating the built-in functions into the compiler and the VM much easier later on.

Making the Change Easy

So, here’s the first task: move the built-in functions out of the evaluator package while keeping the evaluator working. Attached to that is a little sidequest: while moving them, we need to define the built-in functions so that we can iterate through them in a stable way. The builtins we currently have in evaluator is a map[string]*object.Builtin, which doesn’t give us the guarantee of stable iteration.

Instead of a map we’re going to use a slice of structs in which we can pair an *object.Builtin with its name. That gives us stable iteration and, with the help of a small function, allows us to fetch a single function by name.

Doing this instead of simply cutting and pasting the existing evaluator.builtins definition, also gives us a chance to refreshen our memory by taking a look at each built-in function again.

Let’s start with len. It returns the length of an array or a string. We create a new file, object/builtins.go, and copy the definition of len from evaluator/builtins.go to the new file. Like this:

// object/builtins.go

package object

import "fmt"

var Builtins = []struct {
    Name    string
    Builtin *Builtin
}{
    {
        "len",
        &Builtin{Fn: func(args ...Object) Object {
            if len(args) != 1 {
                return newError("wrong number of arguments. got=%d, want=1",
                    len(args))
            }

            switch arg := args[0].(type) {
            case *Array:
                return &Integer{Value: int64(len(arg.Elements))}
            case *String:
                return &Integer{Value: int64(len(arg.Value))}
            default:
                return newError("argument to `len` not supported, got %s",
                    args[0].Type())
            }
        },
        },
    },
}

func newError(format string, a ...interface{}) *Error {
    return &Error{Message: fmt.Sprintf(format, a...)}
}

Builtins is a slice of structs, where each struct contains the name and the *Builtin function itself.

While we did copy the *Builtin with the name len, please note that this is not mindless copy and pasting: in the *Builtin itself we had to remove references to the object package. They’re redundant now that we’re in object.

The newError function we also had to copy over since it’s heavily used by most of the built-in functions.

With Builtins defined and containing its first definition, we can now add a function called GetBuiltinByName:

// object/builtins.go

func GetBuiltinByName(name string) *Builtin {
    for _, def := range Builtins {
        if def.Name == name {
            return def.Builtin
        }
    }
    return nil
}

There’s not much to explain here. It’s a function that allows us to fetch a built-in function by name. But with this in place, we can get rid of the duplication in evaluator/builtins.go and replace the old definition of len with this:

// evaluator/builtins.go

var builtins = map[string]*object.Builtin{
    "len": object.GetBuiltinByName("len"),
    // [...]
}

That’s our first built-in function moved. Congratulations! And, look at that, the tests of the evaluator package are still working:

$ go test ./evaluator
ok      monkey/evaluator    0.009s

Great! Now we can do the same for each function in evaluator.builtins. Next up is puts, which prints its arguments:

// object/builtins.go

var Builtins = []struct {
    Name    string
    Builtin *Builtin
}{
    // [...]
    {
        "puts",
        &Builtin{Fn: func(args ...Object) Object {
            for _, arg := range args {
                fmt.Println(arg.Inspect())
            }

            return nil
        },
        },
    },
}

Even though it doesn’t look like much, this new definition of puts contains one crucial change.

In its definition in the evaluator package, puts returns evaluator.NULL. That’s the evaluator’s counterpart to the VM’s vm.Null. But since keeping the reference to evaluator.NULL would mean juggling around two instances of *object.Null in the VM, we change puts to instead return nil.

That’s easy to replace with vm.Null once we’re in the VM. But since we want to use the new definition of puts in the evaluator too, we need to change the existing code to now check for nil and turn it into NULL if necessary:

// evaluator/evaluator.go

func applyFunction(fn object.Object, args []object.Object) object.Object {
    switch fn := fn.(type) {

    // [...]

    case *object.Builtin:
        if result := fn.Fn(args...); result != nil {
            return result
        }
        return NULL

    // [...]
    }
}

The next function to move is first, which returns the first element of an array. It has to undergo the same treatment as puts: copy it from evaluator/builtins.go to object/builtins.go, remove references to the object package and return nil where it previously returned evaluator.NULL:

// object/builtins.go

var Builtins = []struct {
    Name    string
    Builtin *Builtin
}{
    // [...]
    {
        "first",
        &Builtin{Fn: func(args ...Object) Object {
            if len(args) != 1 {
                return newError("wrong number of arguments. got=%d, want=1",
                    len(args))
            }
            if args[0].Type() != ARRAY_OBJ {
                return newError("argument to `first` must be ARRAY, got %s",
                    args[0].Type())
            }

            arr := args[0].(*Array)
            if len(arr.Elements) > 0 {
                return arr.Elements[0]
            }

            return nil
        },
        },
    },
}

Of course, we also defined a last function, for which we have to follow the same recipe:

// object/builtins.go

var Builtins = []struct {
    Name    string
    Builtin *Builtin
}{
    // [...]
    {
        "last",
        &Builtin{Fn: func(args ...Object) Object {
            if len(args) != 1 {
                return newError("wrong number of arguments. got=%d, want=1",
                    len(args))
            }
            if args[0].Type() != ARRAY_OBJ {
                return newError("argument to `last` must be ARRAY, got %s",
                    args[0].Type())
            }

            arr := args[0].(*Array)
            length := len(arr.Elements)
            if length > 0 {
                return arr.Elements[length-1]
            }

            return nil
        },
        },
    },
}

Besides getting the first and last elements of an array, it’s sometimes really useful to get every element except the first one, which is why we have rest:

// object/builtins.go

var Builtins = []struct {
    Name    string
    Builtin *Builtin
}{
    // [...]
    {
        "rest",
        &Builtin{Fn: func(args ...Object) Object {
            if len(args) != 1 {
                return newError("wrong number of arguments. got=%d, want=1",
                    len(args))
            }
            if args[0].Type() != ARRAY_OBJ {
                return newError("argument to `rest` must be ARRAY, got %s",
                    args[0].Type())
            }

            arr := args[0].(*Array)
            length := len(arr.Elements)
            if length > 0 {
                newElements := make([]Object, length-1, length-1)
                copy(newElements, arr.Elements[1:length])
                return &Array{Elements: newElements}
            }

            return nil
        },
        },
    },
}

And then we define push, which adds an element to an array. It doesn’t mutate the array, but instead leaves it untouched and allocates a new one, containing the elements of the original array and the addition:

// object/builtins.go

var Builtins = []struct {
    Name    string
    Builtin *Builtin
}{
    // [...]
    {
        "push",
        &Builtin{Fn: func(args ...Object) Object {
            if len(args) != 2 {
                return newError("wrong number of arguments. got=%d, want=2",
                    len(args))
            }
            if args[0].Type() != ARRAY_OBJ {
                return newError("argument to `push` must be ARRAY, got %s",
                    args[0].Type())
            }

            arr := args[0].(*Array)
            length := len(arr.Elements)

            newElements := make([]Object, length+1, length+1)
            copy(newElements, arr.Elements)
            newElements[length] = args[1]

            return &Array{Elements: newElements}
        },
        },
    },
}

And that was the last of the built-in functions we set out to implement. All of them are now defined in object.Builtins, stripped free of redundant references to the object package and making no mention of evaluator.NULL.

Now we can go back to evaluator/builtins.go and replace all of the currently-duplicated definitions with calls to object.GetBuiltinByName:

// evaluator/builtins.go

import (
    "monkey/object"
)

var builtins = map[string]*object.Builtin{
    "len":   object.GetBuiltinByName("len"),
    "puts":  object.GetBuiltinByName("puts"),
    "first": object.GetBuiltinByName("first"),
    "last":  object.GetBuiltinByName("last"),
    "rest":  object.GetBuiltinByName("rest"),
    "push":  object.GetBuiltinByName("push"),
}

Isn’t that neat? That’s the whole file! Now comes the sanity check to make sure that everything still works:

$ go test ./evaluator
ok      monkey/evaluator    0.009s

Great! With that, built-in functions are now available to every package that imports the object package. They do not depend on evaluator.NULL anymore and follow a bring-your-own-null approach instead. The evaluator still works as it did at the end of Writing An Interpreter In Go and all tests pass.

Beautiful. That’s what I call a refactoring. It makes everything we now have to do easier.

Making the Change: the Plan

You know what I like? Getting rid of edge cases and having as few of them as possible.

That’s why I want to keep our existing calling convention as it is, even for built-in functions. That means, in order to call a built-in function, you’d do the same as for any other function: push the built-in function on to the stack, push the arguments of the call and then call the function with an OpCall instruction.

How the built-in function is going to be executed, that’s an implementation detail of the VM which we’ll worry about later.

From the compiler’s perspective, the only thing that should be different when compiling a call expression involving a built-in function is how the function ends up on the stack. For that, we really need to introduce another case, but not an edge case.

Built-in functions are neither defined in the global nor in a local scope. They live in their own scope. And we need to introduce that scope to the compiler and its symbol table, so they can correctly resolve references to built-in functions.

We’re going to call this scope the BuiltinScope and in it we’re going to define all the built-in functions we have just moved over to the object.Builtins slice of definitions – in exactly that order. That’s an important detail, because it’s our sidequest.

When the compiler (with the help of the symbol table) then detects a reference to a built-in function it will emit an OpGetBuiltin instruction. The operand in this instruction will be the index of the referenced function in object.Builtins.

Since object.Builtins is also accessible by the VM it can use the operand of the instruction to fetch the correct function from object.Builtins and push it on to the stack, where it can then be called.

Again, we can worry about how that happens later, once we’ve written our first VM test. But as our next step, we need to make sure that the compiler knows how to resolve references to built-ins. For that, we need a new opcode and a new scope.

A New Scope for Built-in Functions

First things first and as we know by now, that’s often a new opcode. This time it’s called OpGetBuiltin:

// code/code.go

const (
    // [...]

    OpGetBuiltin
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpGetBuiltin: {"OpGetBuiltin", []int{1}},
}

The opcode comes with one operand that’s one byte wide. That means we can define up to 256 built-in functions. Sounds low? Let’s just say that once we’ve reached that limit, we can always make it two bytes.

You know the drill: opcodes first and compiler tests next. Now that we have OpGetBuiltin, we can write a test that expects our compiler to turn references to built-in functions into OpGetBuiltin instructions.

// compiler/compiler_test.go

func TestBuiltins(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `
            len([]);
            push([], 1);
            `,
            expectedConstants: []interface{}{1},
            expectedInstructions: []code.Instructions{
                code.Make(code.OpGetBuiltin, 0),
                code.Make(code.OpArray, 0),
                code.Make(code.OpCall, 1),
                code.Make(code.OpPop),
                code.Make(code.OpGetBuiltin, 5),
                code.Make(code.OpArray, 0),
                code.Make(code.OpConstant, 0),
                code.Make(code.OpCall, 2),
                code.Make(code.OpPop),
            },
        },
        {
            input: `fn() { len([]) }`,
            expectedConstants: []interface{}{
                []code.Instructions{
                    code.Make(code.OpGetBuiltin, 0),
                    code.Make(code.OpArray, 0),
                    code.Make(code.OpCall, 1),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

The first of these two test cases makes sure of two things. First, calling a built-in function follows our established calling convention and, second, the operand of the OpGetBuiltin instruction is the index of the referenced function in object.Builtins.

The second test case then makes sure that references to built-in functions are correctly resolved, independent of the scope in which they occur, which is different from the existing behaviour of local and global scopes.

If we run the tests, we get a compiler error:

$ go test ./compiler
--- FAIL: TestBuiltins (0.00s)
 compiler_test.go:1049: compiler error: undefined variable len
FAIL
FAIL    monkey/compiler 0.008s

Since the fix for this failing test includes our compiler correctly resolving references, our next stop is the place where the compiler goes to for its resolving needs: the symbol table.

Here, too, we need to write a test to make sure that built-in functions always resolve to a symbol in the BuiltinScope, regardless of how many times the symbol table has been enclosed in another one:

// compiler/symbol_table_test.go

func TestDefineResolveBuiltins(t *testing.T) {
    global := NewSymbolTable()
    firstLocal := NewEnclosedSymbolTable(global)
    secondLocal := NewEnclosedSymbolTable(firstLocal)

    expected := []Symbol{
        Symbol{Name: "a", Scope: BuiltinScope, Index: 0},
        Symbol{Name: "c", Scope: BuiltinScope, Index: 1},
        Symbol{Name: "e", Scope: BuiltinScope, Index: 2},
        Symbol{Name: "f", Scope: BuiltinScope, Index: 3},
    }

    for i, v := range expected {
        global.DefineBuiltin(i, v.Name)
    }

    for _, table := range []*SymbolTable{global, firstLocal, secondLocal} {
        for _, sym := range expected {
            result, ok := table.Resolve(sym.Name)
            if !ok {
                t.Errorf("name %s not resolvable", sym.Name)
                continue
            }
            if result != sym {
                t.Errorf("expected %s to resolve to %+v, got=%+v",
                    sym.Name, sym, result)
            }
        }
    }
}

In this test we define three scopes, nested within each other, and expect every symbol that’s been defined in the global scope with DefineBuiltin to resolve to the new BuiltinScope.

Since DefineBuiltin and BuiltinScope do not exist yet, there’s no need to run the tests yet, but it also doesn’t hurt to make sure that they blow up as expected:

$ go test -run TestDefineResolveBuiltins ./compiler
# monkey/compiler
compiler/symbol_table_test.go:162:28: undefined: BuiltinScope
compiler/symbol_table_test.go:163:28: undefined: BuiltinScope
compiler/symbol_table_test.go:164:28: undefined: BuiltinScope
compiler/symbol_table_test.go:165:28: undefined: BuiltinScope
compiler/symbol_table_test.go:169:9: global.DefineBuiltin undefined\
  (type *SymbolTable has no field or method DefineBuiltin)
FAIL    monkey/compiler [build failed]

As expected. Defining BuiltinScope is the easier of the two necessary steps, so we do that first:

// compiler/symbol_table.go

const (
    // [...]
    BuiltinScope SymbolScope = "BUILTIN"
)

But it’s not that much harder to write the DefineBuiltin method:

// compiler/symbol_table.go

func (s *SymbolTable) DefineBuiltin(index int, name string) Symbol {
    symbol := Symbol{Name: name, Index: index, Scope: BuiltinScope}
    s.store[name] = symbol
    return symbol
}

Compared to the existing Define method, this one here is much simpler. Define the given name with the given index in the BuiltinScope, ignore whether you’re enclosed in another symbol table or not, and done:

$ go test -run TestDefineResolveBuiltins ./compiler
ok      monkey/compiler 0.007s

Now we can go back and use DefineBuiltin method in the compiler:

// compiler/compiler.go

func New() *Compiler {
    // [...]

    symbolTable := NewSymbolTable()

    for i, v := range object.Builtins {
        symbolTable.DefineBuiltin(i, v.Name)
    }

    return &Compiler{
        // [...]
        symbolTable:       symbolTable,
        // [...]
    }
}

When initializing a new *Compiler we iterate through all of the functions in object.Builtins and define them in the BuiltinScope by using the DefineBuiltin method on the global symbol table.

That should fix our compiler test, because the compiler can now resolve the references to the built-in functions:

$ go test ./compiler
--- FAIL: TestBuiltins (0.00s)
 compiler_test.go:1056: testInstructions failed: wrong instruction at 0.
  want="0000 OpGetBuiltin 0\n0002 OpArray 0\n0005 OpCall 1\n0007 OpPop\n\
    0008 OpGetBuiltin 5\n0010 OpArray 0\n0013 OpConstant 0\n\
    0016 OpCall 2\n0018 OpPop\n"
  got ="0000 OpGetLocal 0\n0002 OpArray 0\n0005 OpCall 1\n0007 OpPop\n\
    0008 OpGetLocal 5\n0010 OpArray 0\n0013 OpConstant 0\n\
    0016 OpCall 2\n0018 OpPop\n"
FAIL
FAIL    monkey/compiler 0.009s

Except, it doesn’t and that’s because our compiler ignores half of what the symbol table is saying. In its current state, after using the symbol table to resolve a name, the compiler only checks whether a symbol’s scope is GlobalScope or not. But we can’t get away with an if-else check anymore.

We have a third scope now and have to actually listen to what the symbol table has to say. And we best do that in a separate method:

// compiler/compiler.go

func (c *Compiler) loadSymbol(s Symbol) {
    switch s.Scope {
    case GlobalScope:
        c.emit(code.OpGetGlobal, s.Index)
    case LocalScope:
        c.emit(code.OpGetLocal, s.Index)
    case BuiltinScope:
        c.emit(code.OpGetBuiltin, s.Index)
    }
}

When we now use loadSymbol to compile an *ast.Identifier, we emit the correct instruction for each symbol we resolve:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {

    // [...]

    case *ast.Identifier:
        symbol, ok := c.symbolTable.Resolve(node.Value)
        if !ok {
            return fmt.Errorf("undefined variable %s", node.Value)
        }

        c.loadSymbol(symbol)

    // [...]
    }

    // [...]
}

Yep, that did it:

$ go test ./compiler
ok      monkey/compiler 0.008s

That means, the compiler now compiles references to built-in functions. And the best bit is that it also upholds our existing calling convention – without us having to do anything. Sweet!

Time to start worrying about the implementation detail that is the execution of built-in functions.

Executing built-in functions

“Implementation detail” always sounds like it’s about of the size of the change, when it’s really about visibility, abstraction. The user of a feature shouldn’t have to worry about how it’s implemented – the detail – but only about using it.

A Monkey user shouldn’t have to worry about how to execute a built-in function. Neither should the compiler. That should solely be the concern of the VM. And that gives us a lot of freedom: freedom of implementation and also freedom of tests. We can simply write down what we want the VM to do and only then worry about the how:

// vm/vm_test.go

func TestBuiltinFunctions(t *testing.T) {
    tests := []vmTestCase{
        {`len("")`, 0},
        {`len("four")`, 4},
        {`len("hello world")`, 11},
        {
            `len(1)`,
            &object.Error{
                Message: "argument to `len` not supported, got INTEGER",
            },
        },
        {`len("one", "two")`,
            &object.Error{
                Message: "wrong number of arguments. got=2, want=1",
            },
        },
        {`len([1, 2, 3])`, 3},
        {`len([])`, 0},
        {`puts("hello", "world!")`, Null},
        {`first([1, 2, 3])`, 1},
        {`first([])`, Null},
        {`first(1)`,
            &object.Error{
                Message: "argument to `first` must be ARRAY, got INTEGER",
            },
        },
        {`last([1, 2, 3])`, 3},
        {`last([])`, Null},
        {`last(1)`,
            &object.Error{
                Message: "argument to `last` must be ARRAY, got INTEGER",
            },
        },
        {`rest([1, 2, 3])`, []int{2, 3}},
        {`rest([])`, Null},
        {`push([], 1)`, []int{1}},
        {`push(1, 1)`,
            &object.Error{
                Message: "argument to `push` must be ARRAY, got INTEGER",
            },
        },
    }

    runVmTests(t, tests)
}

func testExpectedObject(
    t *testing.T,
    expected interface{},
    actual object.Object,
) {
    t.Helper()

    switch expected := expected.(type) {
    // [...]

    case *object.Error:
        errObj, ok := actual.(*object.Error)
        if !ok {
            t.Errorf("object is not Error: %T (%+v)", actual, actual)
            return
        }
        if errObj.Message != expected.Message {
            t.Errorf("wrong error message. expected=%q, got=%q",
                expected.Message, errObj.Message)
        }
    }
}

This test is an updated version of the TestBuiltinFunctions test in the evaluator package. The references to evaluator.NULL have been changed to vm.Null and the testing of the result has been updated to use our new test helpers. Other than that, it does the same thing as its precursor: make sure that all built-in functions work as expected, including error handling.

None of the functions work yet, of course. Instead, we get a panic when we try to run the tests. I won’t show it to you – to save half a book page and to spare you the headache of looking at it. Rest assured, though, that the main reason for the panic is that the VM doesn’t decode and execute the OpGetBuiltin instructions yet. That’s our first task:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpGetBuiltin:
            builtinIndex := code.ReadUint8(ins[ip+1:])
            vm.currentFrame().ip += 1

            definition := object.Builtins[builtinIndex]

            err := vm.push(definition.Builtin)
            if err != nil {
                return err
            }

        // [...]
        }

    // [...]
}

We decode the operand, use it as an index into object.Builtins, get the definition of the built-in function and then push the *object.Builtin on to the stack. That’s the first part of our calling convention, the part in which you get the function you want to call on to the stack.

When we now run the tests, the panic is gone, replaced with something much more helpful:

$ go test ./vm
--- FAIL: TestBuiltinFunctions (0.00s)
 vm_test.go:847: vm error: calling non-function
FAIL
FAIL    monkey/vm   0.036s

The VM tells us that it can only execute user-defined functions. To fix that, we have to change how we execute OpCall instructions. Instead of directly calling the callFunction method, as we currently do, we first need to check what it is that we’re supposed to call and then dispatch the appropriate method. For that, we introduce an executeCall method:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpCall:
            numArgs := code.ReadUint8(ins[ip+1:])
            vm.currentFrame().ip += 1

            err := vm.executeCall(int(numArgs))
            if err != nil {
                return err
            }

        // [...]
        }

    // [...]
}

func (vm *VM) executeCall(numArgs int) error {
    callee := vm.stack[vm.sp-1-numArgs]
    switch callee := callee.(type) {
    case *object.CompiledFunction:
        return vm.callFunction(callee, numArgs)
    case *object.Builtin:
        return vm.callBuiltin(callee, numArgs)
    default:
        return fmt.Errorf("calling non-function and non-built-in")
    }
}

func (vm *VM) callFunction(fn *object.CompiledFunction, numArgs int) error {
    if numArgs != fn.NumParameters {
        return fmt.Errorf("wrong number of arguments: want=%d, got=%d",
            fn.NumParameters, numArgs)
    }

    frame := NewFrame(fn, vm.sp-numArgs)
    vm.pushFrame(frame)

    vm.sp = frame.basePointer + fn.NumLocals

    return nil
}

executeCall now does some of the things that were previously done by callFunction, namely the type checking and error generation. That in turn makes callFunction smaller and requires a different interface, where we pass in the function that’s to be called and the number of arguments of the call.

But that’s mainly code being moved around. What’s new is the addition of the case *object.Builtin branch and the callBuiltin method, which takes care of executing built-in functions:

// vm/vm.go

func (vm *VM) callBuiltin(builtin *object.Builtin, numArgs int) error {
    args := vm.stack[vm.sp-numArgs : vm.sp]

    result := builtin.Fn(args...)
    vm.sp = vm.sp - numArgs - 1

    if result != nil {
        vm.push(result)
    } else {
        vm.push(Null)
    }

    return nil
}

Here’s finally the how of executing built-in functions.

We take the arguments from the stack (without removing them yet) and pass them to the object.BuiltinFunction that’s contained in the *object.Builtin’s Fn field. That’s the central part, the execution of the built-in function itself.

After that, we decrease the vm.sp to take the arguments and the function we just executed off the stack. As per our calling convention, doing that is the duty of the VM.

Once the stack is cleaned up, we check whether the result of the call is nil or not. If it’s not nil, we push the result on to the stack; but if it is, we push vm.Null. That’s the bring-your-on-null strategy at work again.

And now, to the sound of us whispering an impressed nice under our breath, we can see that every built-in function works as expected – in our compiler and our VM:

$ go test ./vm
ok      monkey/vm   0.045s

But while that euphoric "ok" screams for celebration, as a last step, we also have to take care of the REPL. Although we define every built-in function on the compiler’s symbol table in the compiler.New function, that doesn’t have an effect on the REPL and it won’t find those built-in functions.

That’s because we’re not using compiler.New but compiler.NewWithState in the REPL. NewWithState allows us to reuse one symbol table across REPL prompts by overwriting the symbol table that’s been initialized by New with a global one. And since no built-in functions have been defined in this global table, that’s what we have to change:

// repl/repl.go

func Start(in io.Reader, out io.Writer) {
    // [...]

    symbolTable := compiler.NewSymbolTable()
    for i, v := range object.Builtins {
        symbolTable.DefineBuiltin(i, v.Name)
    }

    for {
        // [...]
    }
}

With that, we can use built-in functions even in our REPL:

$ go build -o monkey . && ./monkey
Hello mrnugget! This is the Monkey programming language!
Feel free to type in commands
>> let array = [1, 2, 3];
[1, 2, 3]
>> len(array)
3
>> push(array, 1)
[1, 2, 3, 1]
>> rest(array)
[2, 3]
>> first(array)
1
>> last(array)
3
>> first(rest(push(array, 4)))
2

Perfect! That’s a far better output to end a chapter on than the measly ok of our tests.

Now, onwards, to the final frontier of function implementation: closures.

Closures

It’s time to complete our new implementation of Monkey and add the last missing piece – closures. This is by far the most precious and one of those category-defining features in the realm of bytecode compilers and virtual machines. There aren’t that many that support it and soon enough, you’ll see why that is.

First, a little refresher of what closures are and how they work. Here’s the prime example:

let newAdder = fn(a) {
  let adder = fn(b) { a + b; };
  return adder;
};

let addTwo = newAdder(2);
addTwo(3); // => 5

The newAdder function returns a closure called adder. It’s a closure because it not only makes use of its own parameter, b, but also accesses a, the parameter defined in newAdder. After adder is returned from newAdder it still has access to both of them. That’s what makes adder a closure and why addTwo returns 5 when called with 3 – it’s a version of the adder function that can still access the previous value of a, which was 2.

That’s “what’s a closure?” in six lines of code.

Our interpreter in Writing An Interpreter In Go also had support for closures and while that implementation is markedly different from what we’re going to build in this chapter, a little recap helps to set the stage, so here’s a rough sketch of our path to closures in Writing An Interpreter In Go.

The first thing we did was to add an Env field to object.Function to hold an *object.Environment, which is what we used to store global and local bindings. When we evaluated an *ast.FunctionLiteral, which turns it into an *object.Function, we put a pointer to the current environment in the Env field of the new function.

When the function was called, we evaluated its body in this environment, the one we put in the Env field. The practical effect of all this was that functions always had access to the bindings of the environment in which they were defined, even much later and in any place. This ability is what makes closures closures and separates them from normal functions.

The reason I wanted to go over the old implementation again is because of how closely it maps to the way we think about closures: they’re functions that “close over” their environment at the time of their definition, wrap around it and carry it with them, just like the pointer to the *object.Environment in the Env field. That’s the most important thing to understand about closures.

Now we need to implement closures again, only this time we don’t have a tree-walking interpreter. We have a compiler and a VM and that poses a fundamental problem.

The Problem

It’s not that we don’t evaluate function literals anymore; the problem is not the evaluation per se. In our current implementation we still turn *ast.FunctionLiterals into object.Objects; meaning that we turn them into something that can be passed around and, most importantly, something that can be called and executed. In that sense, the semantics haven’t changed.

What’s changed are the time and place when closures are created.

In our old interpreter the conversion of a function literal into an object.Function and the closing over the environment, which sets the Env field on said object.Function, happened at exactly the same time and even in the same code block.

In our new Monkey implementation this does not only happen at different times, but also in two different packages: we compile function literals in our compiler and we build up an environment in our VM. The consequence is that we can’t close over an environment when we compile functions because, well, there is no environment yet.

Let’s try to make this more tangible by mentally following the snippet from above as it moves through our current implementation.

The first thing that happens is that we compile it. Both functions – newAdder and adder – are turned into a series of instructions and added to the constant pool. After that, we emit OpConstant instructions to instruct the VM to load the functions on to the stack. At that point, compilation is done and nobody knows yet which value a is going to have.

In the VM, however, the value is known as soon as we execute newAdder. By that time, though, adder has already been compiled and its instructions will simply be loaded on to the stack, contained in an *object.CompiledFunction, and returned from newAdder – without any chance to “close over” a.

You can see where the challenge lies. In the VM, we need to get the value of a into an already-compiled adder function before it’s returned from newAdder, and we need to do it in such a way that an adder later on can access it.

Yes, that means the compiler must have previously emitted the instructions that get a on to the stack whenever an adder references it. Quite the feat, considering that a is neither a local nor a global binding and its “location” changes between the time we execute newAdder and, later on, call the returned adder function. First it’s in scope and then it… well, then it has to be somewhere where adder can still access it.

In other words: we need to give compiled functions the ability to hold bindings that are only created at run time and their instructions must already reference said bindings. And then, at run time, we need to instruct the VM to make these bindings available to the function at the right time.

Quite the tall order, isn’t it? On top of that comes the fact that we don’t have a single environment anymore. What was the environment in our tree-walking interpreter is now scattered among the globals store and different regions of the stack, all of which can be wiped out with a return from a function.

If you just let out a little “whew”, here’s another one: we’re also still facing the problem of nested local bindings. That’s fine, though, because the solution to this problem is closely entwined with our future implementation of closures. You can, of course, implement nested local bindings without thinking about closures for one second, but we’re going to get two features for one implementation.

Let’s get to work and make a plan.

The Plan

There is not one true way to implement closures. On the contrary, there are quite a few, all of them peculiar in their own way. Not all of them are publicly documented in prose, most only in code, and that is often optimized to save the last byte of memory and gain precious milliseconds in performance, which – generally speaking – doesn’t help its accessibility. And if you narrow the search down to bytecode compilers and virtual machines, a willingness to dig into the code becomes a hard requirement.

Our implementation will be based on the resources and codebases I found most accessible and transferable to Monkey. Leading here as the main influence is GNU Guile, a Scheme implementation with amazing debugging tools. It’s followed by multiple implementations of Lua and the beautiful codebase of Wren, which has previously inspired Writing An Interpreter In Go. Matt Might’s writing on the topic of compiling closures was also invaluable and comes highly recommended, in case you want to dive even deeper into the topic.

Before we get down to the details and formulate a plan for our implementation, we need to expand our vocabulary and introduce a new term, which can be found at the center of all of the previously-mentioned implementations and resources. It’s this one: “free variable”. Take another look at this part of the code snippet:

let newAdder = fn(a) {
  let adder = fn(b) { a + b; };
  return adder;
};

From adder’s point of view a is a free variable. I have to admit that this was never an intuitive name to me, but free variables are those which are neither defined in the current local scope nor are they parameters of the current function. Since they’re not bound to the current scope, they are free. Another definition explains that free variables are those that are used locally, but defined in an enclosing scope.

Implementing closures with a compiler and a VM revolves around free variables. The compiler needs to detect references to them and emit instructions that will load them on to the stack, even later on, when they’re already out of scope. In the object system, compiled functions must be able to carry free variables with them. And the VM must not only resolve references to free variables correctly, but also store them on compiled functions.

Here’s how we’re going to pull this off: we’re going to turn every function into a closure. Yes, not every function is a closure, but we’ll treat them as such anyway. That’s a common way to keep the architectures of the compiler and the VM simple and also helps us by reducing some of the cognitive load. (If you’re after performance, you’ll find a ton of possible optimizations created through this decision.)

Let’s translate this into practical terms. First, we’ll define a new object in our object package, called Closure. It will have a pointer to an *object.CompiledFunction and a place to store the free variables it references and carries around.

The compilation of functions itself, though, won’t change. We’ll still compile an *ast.FunctionLiteral into an *object.CompiledFunction and add it to the constant pool.

But while compiling the function’s body we’ll inspect each symbol we resolve to find out whether it’s a reference to a free variable. If it is, we won’t emit an OpGetLocal or a OpGetGlobal instruction, but instead a new opcode that loads the value from the “store for the free variables” part of the object.Closure. We’ll have to extend our SymbolTable so it can take care of this part for us.

After the function’s body is compiled and we left its scope in the compiler, we’ll check whether it did reference any free variables. Our upgraded SymbolTable should then tell us how many were referenced and in which scope they were originally defined. This last attribute is especially important, since the next step is to transfer these free variables to the compiled function – at run time. For that, we’ll first have to emit instructions that get the referenced free variables on to the stack and in order to do that we have to know in which scope the bindings were created. Otherwise we won’t know which instructions to emit.

After that we’ll emit another new opcode to tell the VM to fetch the specified function from the constant pool, take the just-pushed free variables off the stack and transfer them to the compiled function. This is what turns the *object.CompiledFunction into an *object.Closure and pushes it on to the stack. While on the stack it can be called just like an *object.CompiledFunctions before, except that it now has access to the free variables its instructions reference. It’s been turned into a closure.

In summary: detect references to free variables while compiling a function, get the referenced values on to the stack, merge the values and the compiled function into a closure and leave it on the stack where it can then be called. Let’s go.

Everything’s a closure

As always, we are working towards our goal by taking baby steps. In order to make that possible and avoid having to take risky strides later on, our first step is to start treating every function as a closure. Again, not every function is a closure, but it can nonetheless be treated as one and that makes adding “real” closures later on incredibly smooth. You’ll see.

In order to treat functions as closures, we need to represent them as such, so here’s our new Monkey object, the Closure:

// object/object.go

const (
    // [...]
    CLOSURE_OBJ = "CLOSURE"
)

type Closure struct {
    Fn   *CompiledFunction
    Free []Object
}

func (c *Closure) Type() ObjectType { return CLOSURE_OBJ }
func (c *Closure) Inspect() string {
    return fmt.Sprintf("Closure[%p]", c)
}

It has a pointer to the function it wraps, Fn, and a place to keep the free variables it carries around, Free. Semantically speaking, the latter is the equivalent to the Env field we added to the *object.Function in Writing An Interpreter in Go.

Since closures are created at run time, we can’t use object.Closure in the compiler. What we need to do instead is send a message into the future. This message, a new opcode called OpClosure, is sent by the compiler to the VM and tells it to wrap the specified *object.CompiledFunction in an *object.Closure:

// code/code.go

const (
    // [...]

    OpClosure
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpClosure: {"OpClosure", []int{2, 1}},
}

Now, this is interesting. OpClosure has two operands! We haven’t had that before. Allow me to explain.

The first operand, two bytes wide, is the constant index. It specifies where in the constant pool we can find the *object.CompiledFunction that’s to be converted into a closure. It’s two bytes wide, because the operand of OpConstant is also two bytes wide. By keeping this consistent we ensure that we never run into the case where we can load a function from the constant pool and put it on the stack, but can’t convert it into a closure, because it’s index is too high.

The second operand, one byte wide, specifies how many free variables sit on the stack and need to be transferred to the about-to-be-created closure. Why one byte? Well, 256 free variables should be plenty. If a Monkey function needs more, I’m happy to say that this VM will refuse to execute it.

We don’t have to worry too much about the second parameter, since right now we’re only concerned about treating functions as closures, not about implementing free variables. That comes later.

What we need to take care of, though, is that our tooling can support an opcode with two operands. At the moment, it kinda does, but not fully and without any tests. Let’s change that by adding them:

// code/code_test.go

func TestMake(t *testing.T) {
    tests := []struct {
        op       Opcode
        operands []int
        expected []byte
    }{
        // [...]
        {OpClosure, []int{65534, 255}, []byte{byte(OpClosure), 255, 254, 255}},
    }

    // [...]
}

func TestInstructionsString(t *testing.T) {
    instructions := []Instructions{
        Make(OpAdd),
        Make(OpGetLocal, 1),
        Make(OpConstant, 2),
        Make(OpConstant, 65535),
        Make(OpClosure, 65535, 255),
    }

    expected := `0000 OpAdd
0001 OpGetLocal 1
0003 OpConstant 2
0006 OpConstant 65535
0009 OpClosure 65535 255
`

    // [...]
}

func TestReadOperands(t *testing.T) {
    tests := []struct {
        op        Opcode
        operands  []int
        bytesRead int
    }{
        // [...]
        {OpClosure, []int{65535, 255}, 3},
    }

    // [...]
}

When we now run the tests of the code package, we see this:

$ go test ./code
--- FAIL: TestInstructionsString (0.00s)
 code_test.go:56: instructions wrongly formatted.
  want="0000 OpAdd\n0001 OpGetLocal 1\n0003 OpConstant 2\n\
    0006 OpConstant 65535\n0009 OpClosure 65535 255\n"
  got="0000 OpAdd\n0001 OpGetLocal 1\n0003 OpConstant 2\n\
    0006 OpConstant 65535\n\
    0009 ERROR: unhandled operandCount for OpClosure\n\n"
FAIL
FAIL    monkey/code 0.007s

Looks like we only need to fix the fmtInstruction method on Instructions:

// code/code.go

func (ins Instructions) fmtInstruction(def *Definition, operands []int) string {
    // [...]

    switch operandCount {
    case 0:
        return def.Name
    case 1:
        return fmt.Sprintf("%s %d", def.Name, operands[0])
    case 2:
        return fmt.Sprintf("%s %d %d", def.Name, operands[0], operands[1])
    }

    // [...]
}

Another case branch and we’re back in business, because code.Make and code.ReadOperands can already handle two operands per opcode:

$ go test ./code
ok      monkey/code 0.008s

We’ve paved the way and can start to treat functions as closures.

In compiler terms, that means we will now emit OpClosure instructions instead of OpConstant ones to get functions on the stack. Everything else will stay the same for now. We’ll compile functions to *object.CompiledFunctions and we’ll add them to the constant pool. But instead of taking the index for the constant pool and using it as an operand to OpConstant, we’ll give it to an OpClosure instruction instead. As the second operand to OpClosure, the number of free variables sitting on the stack, we’ll use 0 for now.

If we were to jump straight into compiler.go now and replace the OpConstant instructions with OpClosure ones, we’d end up with a whole lot of failing compiler tests. Unintended failing tests are always a bad thing, so let’s get ahead of the issue and adjust our tests first. All we need to do is change the OpConstant into an OpClosure wherever we expected functions to be loaded on to the stack:

// compiler/compiler_test.go

func TestFunctions(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `fn() { return 5 + 10 }`,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 2, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input: `fn() { 5 + 10 }`,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 2, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input: `fn() { 1; 2 }`,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 2, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

This looks like more than it is, but that’s only because I want to give you some context to these changes. In the expectedInstructions of each test case we change the previous OpConstant to OpClosure and add the second operand, 0. That’s it. Now we need to do the same in the other tests where we load functions:

// compiler/compiler_test.go

func TestFunctionsWithoutReturnValue(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `fn() { }`,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 0, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

func TestFunctionCalls(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `fn() { 24 }();`,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 1, 0),
                code.Make(code.OpCall, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            let noArg = fn() { 24 };
            noArg();
            `,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 1, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpCall, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            let oneArg = fn(a) { a };
            oneArg(1);
            `,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 0, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpCall, 1),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            let manyArg = fn(a, b, c) { a; b; c };
            manyArg(1, 2, 3);
            `,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 0, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpGetGlobal, 0),
                code.Make(code.OpConstant, 1),
                code.Make(code.OpConstant, 2),
                code.Make(code.OpConstant, 3),
                code.Make(code.OpCall, 3),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

func TestLetStatementScopes(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `
            let num = 55;
            fn() { num }`,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpClosure, 1, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            fn() {
                let num = 55;
                num
            }
            `,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 1, 0),
                code.Make(code.OpPop),
            },
        },
        {
            input: `
            fn() {
                let a = 55;
                let b = 77;
                a + b
            }
            `,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 2, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

func TestBuiltins(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input: `fn() { len([]) }`,
            expectedConstants: []interface{}{
                // [...]
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 0, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

With updated expectations but an old compiler, we now have failing tests:

$ go test ./compiler
--- FAIL: TestFunctions (0.00s)
 compiler_test.go:688: testInstructions failed: wrong instructions length.
  want="0000 OpClosure 2 0\n0004 OpPop\n"
  got ="0000 OpConstant 2\n0003 OpPop\n"
--- FAIL: TestFunctionsWithoutReturnValue (0.00s)
 compiler_test.go:779: testInstructions failed: wrong instructions length.
  want="0000 OpClosure 0 0\n0004 OpPop\n"
  got ="0000 OpConstant 0\n0003 OpPop\n"
--- FAIL: TestFunctionCalls (0.00s)
 compiler_test.go:895: testInstructions failed: wrong instructions length.
  want="0000 OpClosure 1 0\n0004 OpCall 0\n0006 OpPop\n"
  got ="0000 OpConstant 1\n0003 OpCall 0\n0005 OpPop\n"
--- FAIL: TestLetStatementScopes (0.00s)
 compiler_test.go:992: testInstructions failed: wrong instructions length.
  want="0000 OpConstant 0\n0003 OpSetGlobal 0\n\
    0006 OpClosure 1 0\n0010 OpPop\n"
  got ="0000 OpConstant 0\n0003 OpSetGlobal 0\n\
    0006 OpConstant 1\n0009 OpPop\n"
--- FAIL: TestBuiltins (0.00s)
 compiler_test.go:1056: testInstructions failed: wrong instructions length.
  want="0000 OpClosure 0 0\n0004 OpPop\n"
  got ="0000 OpConstant 0\n0003 OpPop\n"
FAIL
FAIL    monkey/compiler 0.010s

As expected: we want an OpClosure instead of an OpConstant. Perfect. Now we can change the compiler and what a change it is:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.FunctionLiteral:
        // [...]

        fnIndex := c.addConstant(compiledFn)
        c.emit(code.OpClosure, fnIndex, 0)

    // [...]
    }

    // [...]
}

These are the new last two lines of the case branch for *ast.FunctionLiteral. Instead of emitting OpConstant, we emit an OpClosure instruction. That’s all that needs to be changed and it’s enough to get the tests working again:

$ go test ./compiler
ok      monkey/compiler 0.008s

The frontend of our Monkey implementation now treats every function as a closure. The VM, however, isn’t on the same page yet:

$ go test ./vm
--- FAIL: TestCallingFunctionsWithoutArguments (0.00s)
panic: runtime error: index out of range [recovered]
 panic: runtime error: index out of range

[...]
FAIL    monkey/vm   0.038s

The upside is that we don’t have to change any VM tests, we just have to get them to pass again. First step: wrap the mainFn we’re executing in a closure and update the initialization code for the VM.

// vm/vm.go

func New(bytecode *compiler.Bytecode) *VM {
    mainFn := &object.CompiledFunction{Instructions: bytecode.Instructions}
    mainClosure := &object.Closure{Fn: mainFn}
    mainFrame := NewFrame(mainClosure, 0)

    // [...]
}

That doesn’t get us too far, because NewFrame and the underlying Frames do not know how to work with closures yet. What we need to do is make Frame keep a reference to a *object.Closure:

// vm/frame.go

type Frame struct {
    cl          *object.Closure
    ip          int
    basePointer int
}

func NewFrame(cl *object.Closure, basePointer int) *Frame {
    f := &Frame{
        cl:          cl,
        ip:          -1,
        basePointer: basePointer,
    }

    return f
}

func (f *Frame) Instructions() code.Instructions {
    return f.cl.Fn.Instructions
}

What these changes come down to is another level of indirection. Instead of the fn that holds an *object.CompiledFunction, a Frame now has a cl field, pointing to an object.Closure. To get to the Instructions we now have to go through the cl field first and then through the Fn the closure is wrapping.

And now that our frames assume they only have to work with closures, we actually need to give them closures when we initialize and push them on to our frame stack. The initialization previously happened in the callFunction method of VM. Now is the time to rename it to callClosure and initialize frames with closures:

// vm/vm.go

func (vm *VM) executeCall(numArgs int) error {
    callee := vm.stack[vm.sp-1-numArgs]
    switch callee := callee.(type) {
    case *object.Closure:
        return vm.callClosure(callee, numArgs)
    case *object.Builtin:
        return vm.callBuiltin(callee, numArgs)
    default:
        return fmt.Errorf("calling non-closure and non-builtin")
    }
}

func (vm *VM) callClosure(cl *object.Closure, numArgs int) error {
    if numArgs != cl.Fn.NumParameters {
        return fmt.Errorf("wrong number of arguments: want=%d, got=%d",
            cl.Fn.NumParameters, numArgs)
    }

    frame := NewFrame(cl, vm.sp-numArgs)
    vm.pushFrame(frame)

    vm.sp = frame.basePointer + cl.Fn.NumLocals

    return nil
}

Make no mistake: callClosure is just a revamped callFunction. The name has been changed and the local variable has been renamed from fn to cl, because it’s now an *object.Closure that’s being called. That brings with it that we also have to ask cl.Fn for the NumParameters and NumLocals. What the method does, though, is the same.

The same renaming was necessary in executeCall, of course, where we now expect an *object.Closure to sit on the stack instead of an *object.CompiledFunction.

All that’s left to do now is to actually handle the OpClosure instructions. That means getting functions from the constant pool, wrapping them in a closure and pushing that on to the stack, where it can be called:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpClosure:
            constIndex := code.ReadUint16(ins[ip+1:])
            _ = code.ReadUint8(ins[ip+3:])
            vm.currentFrame().ip += 3

            err := vm.pushClosure(int(constIndex))
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

func (vm *VM) pushClosure(constIndex int) error {
    constant := vm.constants[constIndex]
    function, ok := constant.(*object.CompiledFunction)
    if !ok {
        return fmt.Errorf("not a function: %+v", constant)
    }

    closure := &object.Closure{Fn: function}
    return vm.push(closure)
}

Since OpClosure instructions have two operands, we need to either decode or skip both of them, even though we only need one. If we fail do that, the rest of the VM will trip over the unused operand. And while a manual increment of ip is enough to advance it past both operands, we still put a symbolic and absolutely useless ReadUint8 in place, to show us where we will later decode the second operand. The _ is a little reminder that we still have work to do.

We then pass the first operand, constIndex, to the new pushClosure method, which in turn takes care of finding the specified function in the constants, turns it into an *object.Closure and puts it on the stack. There it can be passed around or called, just like *object.CompiledFunctions before, which is to say that it did the trick:

$ go test ./vm
ok      monkey/vm   0.051s

Now, everything’s a closure. Time to add closures.

Compiling and resolving free variables

As I said before, compiling closures revolves around free variables and how to tame them. On that front, we’re doing well. With the Free field on object.Closure we have a place where we can store free variables, and with the OpClosure opcode we can tell the VM to store them there.

But what we also need is an opcode to retrieve the values in the Free field and put them on to the stack. Since our other opcodes to retrieve values are called OpGetLocal, OpGetGlobal and OpGetBuiltin it only makes sense to call this one OpGetFree:

// code/code.go

const (
    // [...]

    OpGetFree
)

var definitions = map[Opcode]*Definition{
    // [...]

    OpGetFree: {"OpGetFree", []int{1}},
}

Now that we have it, we can write a first compiler test in which we use OpGetFree to retrieve the free variables referenced in a real closure:

// compiler/compiler_test.go

func TestClosures(t *testing.T) {
    tests := []compilerTestCase{
        {
            input: `
            fn(a) {
                fn(b) {
                    a + b
                }
            }
            `,
            expectedConstants: []interface{}{
                []code.Instructions{
                    code.Make(code.OpGetFree, 0),
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpAdd),
                    code.Make(code.OpReturnValue),
                },
                []code.Instructions{
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpClosure, 0, 1),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 1, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

This test succinctly shows how our implementation of closures is supposed to work.

The innermost function in the test input, the one with the b parameter, is a real closure: it references not only the local b but also a, which was defined in an enclosing scope. From this function’s perspective a is a free variable and we expect the compiler to emit an OpGetFree instructions to get it on to the stack. The b will be pushed on to the stack with an ordinary OpGetLocal.

In the outer function, a is supposed to be loaded on to the stack with OpGetLocal – despite the function itself never referencing it. But since it’s referenced by the inner function it has to be put on the stack before the VM executes the next instruction: OpClosure.

The second operand of OpClosure is now in use and has the value 1, because there’s one free variable sitting on the stack, a, waiting to be saved into the Free field of an object.Closure.

In the expectedInstructions of the main program another OpClosure takes care of creating a closure, but this time it’s the old use case we already know, without any free variables.

That’s how we’re going to implement closures, expressed as expectations in a compiler test. That’s not all, though. We also want to support deeply-nested closures:

// compiler/compiler_test.go

func TestClosures(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input: `
            fn(a) {
                fn(b) {
                    fn(c) {
                        a + b + c
                    }
                }
            };
            `,
            expectedConstants: []interface{}{
                []code.Instructions{
                    code.Make(code.OpGetFree, 0),
                    code.Make(code.OpGetFree, 1),
                    code.Make(code.OpAdd),
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpAdd),
                    code.Make(code.OpReturnValue),
                },
                []code.Instructions{
                    code.Make(code.OpGetFree, 0),
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpClosure, 0, 2),
                    code.Make(code.OpReturnValue),
                },
                []code.Instructions{
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpClosure, 1, 1),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpClosure, 2, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Here we have three nested functions. The innermost function, the one with the c parameter, references two free variables: a and b. b is defined in the immediate enclosing scope, but a is defined in the outermost function, two scopes removed.

The middle function is expected to contain an OpClosure instruction that turns the innermost function into a closure. Since the second operand is 2, there are supposed to be two free variables sitting on the stack when the VM executes it. What’s curious is how these values are being put on to the stack: an OpGetLocal instruction for the b and – this is the interesting bit – an OpGetFree instruction for the outer a.

Why OpGetFree? Because from the perspective of the middle function, a is also a free variable: neither defined in scope nor as a parameter. And since it needs to get a on to the stack, so it can be transferred to the innermost function’s Free field, we expect an OpGetFree instruction.

That’s how a function will be able to access local bindings from an outer scope; it’s how we implement nested local bindings by implementing closures. We treat every non-local, non-global, non-built-in binding as a free variable.

Let’s add a test that makes this goal clearer:

// compiler/compiler_test.go

func TestClosures(t *testing.T) {
    tests := []compilerTestCase{
        // [...]
        {
            input: `
            let global = 55;

            fn() {
                let a = 66;

                fn() {
                    let b = 77;

                    fn() {
                        let c = 88;

                        global + a + b + c;
                    }
                }
            }
            `,
            expectedConstants: []interface{}{
                55,
                66,
                77,
                88,
                []code.Instructions{
                    code.Make(code.OpConstant, 3),
                    code.Make(code.OpSetLocal, 0),
                    code.Make(code.OpGetGlobal, 0),
                    code.Make(code.OpGetFree, 0),
                    code.Make(code.OpAdd),
                    code.Make(code.OpGetFree, 1),
                    code.Make(code.OpAdd),
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpAdd),
                    code.Make(code.OpReturnValue),
                },
                []code.Instructions{
                    code.Make(code.OpConstant, 2),
                    code.Make(code.OpSetLocal, 0),
                    code.Make(code.OpGetFree, 0),
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpClosure, 4, 2),
                    code.Make(code.OpReturnValue),
                },
                []code.Instructions{
                    code.Make(code.OpConstant, 1),
                    code.Make(code.OpSetLocal, 0),
                    code.Make(code.OpGetLocal, 0),
                    code.Make(code.OpClosure, 5, 1),
                    code.Make(code.OpReturnValue),
                },
            },
            expectedInstructions: []code.Instructions{
                code.Make(code.OpConstant, 0),
                code.Make(code.OpSetGlobal, 0),
                code.Make(code.OpClosure, 6, 0),
                code.Make(code.OpPop),
            },
        },
    }

    runCompilerTests(t, tests)
}

Don’t be put off by the number of instructions here and concentrate on the ones that make up the innermost function. That’s the first []code.Instructions slice. It references all available bindings and makes use of three different opcodes to get values on to the stack: OpGetLocal, OpGetFree and now also OpGetGlobal.

References to global bindings won’t be turned into OpGetFree instructions, because global bindings are just that: global. They’re visible and reachable from every scope. There’s no need to treat them as free variables too, even though they technically are.

The rest of the test case makes sure that a reference to a local binding created with a let statement in an outer scope results in the same instructions as a reference to a parameter of an outer function.

Since we implemented parameters as local bindings, this is more of a sanity check than anything else, because it should work without any additional changes once we have the first test case passing. And it makes our intent of treating local bindings of outer scopes as free variables much clearer.

Now we have multiple test cases and the first one already tells us that our compiler knows nothing about free variables yet:

$ go test ./compiler
--- FAIL: TestClosures (0.00s)
 compiler_test.go:1212: testConstants failed: constant 0 -\
   testInstructions failed: wrong instruction at 0.
  want="0000 OpGetFree 0\n0002 OpGetLocal 0\n0004 OpAdd\n0005 OpReturnValue\n"
  got ="0000 OpGetLocal 0\n0002 OpGetLocal 0\n0004 OpAdd\n0005 OpReturnValue\n"
FAIL
FAIL    monkey/compiler 0.008s

Instead of the expected OpGetFree we get an OpGetLocal instruction. Not surprising, really, since the compiler currently treats every non-global binding as local. That’s wrong. Instead, the compiler must detect free variables when it resolves references and emit an OpGetFree instruction.

Detecting and resolving free variables sounds daunting, but once it’s sliced it into tiny problems, you’ll see that we can solve them one by one. It gets even easier if we ask our symbol table for help, since it was built for tasks like these.

So, let’s start with the easiest possible change and introduce a new scope:

// compiler/symbol_table.go

const (
    // [...]
    FreeScope    SymbolScope = "FREE"
)

With that, we can now write a test for the symbol table to make sure that it can handle free variables. Specifically, we want it to correctly resolve every symbol in this snippet of Monkey code:

let a = 1;
let b = 2;

let firstLocal = fn() {
  let c = 3;
  let d = 4;
  a + b + c + d;

  let secondLocal = fn() {
    let e = 5;
    let f = 6;
    a + b + c + d + e + f;
  };
};

We can take this Monkey code and turn it into a test by looking at it from the symbol table’s perspective:

// compiler/symbol_table_test.go

func TestResolveFree(t *testing.T) {
    global := NewSymbolTable()
    global.Define("a")
    global.Define("b")

    firstLocal := NewEnclosedSymbolTable(global)
    firstLocal.Define("c")
    firstLocal.Define("d")

    secondLocal := NewEnclosedSymbolTable(firstLocal)
    secondLocal.Define("e")
    secondLocal.Define("f")

    tests := []struct {
        table               *SymbolTable
        expectedSymbols     []Symbol
        expectedFreeSymbols []Symbol
    }{
        {
            firstLocal,
            []Symbol{
                Symbol{Name: "a", Scope: GlobalScope, Index: 0},
                Symbol{Name: "b", Scope: GlobalScope, Index: 1},
                Symbol{Name: "c", Scope: LocalScope, Index: 0},
                Symbol{Name: "d", Scope: LocalScope, Index: 1},
            },
            []Symbol{},
        },
        {
            secondLocal,
            []Symbol{
                Symbol{Name: "a", Scope: GlobalScope, Index: 0},
                Symbol{Name: "b", Scope: GlobalScope, Index: 1},
                Symbol{Name: "c", Scope: FreeScope, Index: 0},
                Symbol{Name: "d", Scope: FreeScope, Index: 1},
                Symbol{Name: "e", Scope: LocalScope, Index: 0},
                Symbol{Name: "f", Scope: LocalScope, Index: 1},
            },
            []Symbol{
                Symbol{Name: "c", Scope: LocalScope, Index: 0},
                Symbol{Name: "d", Scope: LocalScope, Index: 1},
            },
        },
    }

    for _, tt := range tests {
        for _, sym := range tt.expectedSymbols {
            result, ok := tt.table.Resolve(sym.Name)
            if !ok {
                t.Errorf("name %s not resolvable", sym.Name)
                continue
            }
            if result != sym {
                t.Errorf("expected %s to resolve to %+v, got=%+v",
                    sym.Name, sym, result)
            }
        }

        if len(tt.table.FreeSymbols) != len(tt.expectedFreeSymbols) {
            t.Errorf("wrong number of free symbols. got=%d, want=%d",
                len(tt.table.FreeSymbols), len(tt.expectedFreeSymbols))
            continue
        }

        for i, sym := range tt.expectedFreeSymbols {
            result := tt.table.FreeSymbols[i]
            if result != sym {
                t.Errorf("wrong free symbol. got=%+v, want=%+v",
                    result, sym)
            }
        }
    }
}

Just like in the Monkey snippet, we define three scopes: the global scope, a firstLocal scope and a secondLocal scope, all nested within each other, with secondLocal being the innermost one. In the setup part of the test, we define two symbols per scope, which matches the let statements in the snippet.

The first part of the test then expects that all the identifiers used in the arithmetic expressions can be resolved correctly. It does so by going through each scope and asking the symbol table to resolve every previously-defined symbol.

It can already do some of that, but now it should also recognize free variables as such and set their scope to FreeScope. And not only that. It also needs to keep track of which symbols were resolved as free variables. That’s what the second part of the test is about.

We iterate through the expectedFreeSymbols and make sure they match the symbol table’s FreeSymbols. The field doesn’t exist yet, but when it does, FreeSymbols should contain the original symbols of the enclosing scope. For example, when we ask the symbol table to resolve c and d while we’re in secondLocal, we want to get back symbols with FreeScope. But at the same time, the original symbols, which were created when the names were defined, should be added to FreeSymbols.

We need to do that because “free variable” is a relative term. A free variable in the current scope could be a local binding in the enclosing scope. And since we want to put free variables on to the stack after a function has been compiled, which is when we emit the OpClosure instruction and have left the scope of the function, we need to know how to reach these symbols while inside of the enclosing scope.

The input in this test is pretty close to our compiler test, isn’t it? That means we’re on the right track, but we still have something to do. We have to make sure that the symbol table doesn’t automatically mark every symbol as a free variable if it can’t resolve it:

// compiler/symbol_table_test.go

func TestResolveUnresolvableFree(t *testing.T) {
    global := NewSymbolTable()
    global.Define("a")

    firstLocal := NewEnclosedSymbolTable(global)
    firstLocal.Define("c")

    secondLocal := NewEnclosedSymbolTable(firstLocal)
    secondLocal.Define("e")
    secondLocal.Define("f")

    expected := []Symbol{
        Symbol{Name: "a", Scope: GlobalScope, Index: 0},
        Symbol{Name: "c", Scope: FreeScope, Index: 0},
        Symbol{Name: "e", Scope: LocalScope, Index: 0},
        Symbol{Name: "f", Scope: LocalScope, Index: 1},
    }

    for _, sym := range expected {
        result, ok := secondLocal.Resolve(sym.Name)
        if !ok {
            t.Errorf("name %s not resolvable", sym.Name)
            continue
        }
        if result != sym {
            t.Errorf("expected %s to resolve to %+v, got=%+v",
                sym.Name, sym, result)
        }
    }

    expectedUnresolvable := []string{
        "b",
        "d",
    }

    for _, name := range expectedUnresolvable {
        _, ok := secondLocal.Resolve(name)
        if ok {
            t.Errorf("name %s resolved, but was expected not to", name)
        }
    }
}

Before we can get feedback from the tests, we need to define the FreeSymbols field on the SymbolTable. Otherwise they won’t compile:

// compiler/symbol_table.go

type SymbolTable struct {
    // [...]

    FreeSymbols []Symbol
}

func NewSymbolTable() *SymbolTable {
    s := make(map[string]Symbol)
    free := []Symbol{}
    return &SymbolTable{store: s, FreeSymbols: free}
}

Now we can run our new tests and see that they do fail as expected:

$ go test -run 'TestResolve*' ./compiler
--- FAIL: TestResolveFree (0.00s)
 symbol_table_test.go:240: expected c to resolve to\
   {Name:c Scope:FREE Index:0}, got={Name:c Scope:LOCAL Index:0}
 symbol_table_test.go:240: expected d to resolve to\
   {Name:d Scope:FREE Index:1}, got={Name:d Scope:LOCAL Index:1}
 symbol_table_test.go:246: wrong number of free symbols. got=0, want=2
--- FAIL: TestResolveUnresolvableFree (0.00s)
 symbol_table_test.go:286: expected c to resolve to\
   {Name:c Scope:FREE Index:0}, got={Name:c Scope:LOCAL Index:0}
FAIL
FAIL    monkey/compiler 0.008s

We expect FREE, but get LOCAL instead. Perfect. Let’s go.

The first thing we do is add a helper method that adds a Symbol to FreeSymbols and returns a FreeScope version of it:

// compiler/symbol_table.go

func (s *SymbolTable) defineFree(original Symbol) Symbol {
    s.FreeSymbols = append(s.FreeSymbols, original)

    symbol := Symbol{Name: original.Name, Index: len(s.FreeSymbols) - 1}
    symbol.Scope = FreeScope

    s.store[original.Name] = symbol
    return symbol
}

Now we can take this method and make both tests for the symbol table pass by using it in the Resolve method.

What Resolve needs to do comes down to a few checks. Has the name been defined in this scope, this symbol table? No? Well, is it a global binding, or a built-in function? No again? That means it was defined as a local in an enclosing scope. In that case, from this scope’s point of view, it’s a free variable and should be resolved as such.

The last point means using the defineFree method returning a symbol with Scope set to FreeScope.

It’s a lot easier to express in code actually:

// compiler/symbol_table.go

func (s *SymbolTable) Resolve(name string) (Symbol, bool) {
    obj, ok := s.store[name]
    if !ok && s.Outer != nil {
        obj, ok = s.Outer.Resolve(name)
        if !ok {
            return obj, ok
        }

        if obj.Scope == GlobalScope || obj.Scope == BuiltinScope {
            return obj, ok
        }

        free := s.defineFree(obj)
        return free, true
    }
    return obj, ok
}

What’s new is the check whether the Symbol’s Scope is GlobalScope or BuiltinScope and the call to the new helper method defineFree. The rest is the recursive walk up the enclosing symbol tables we already had in place.

But that’s enough. We’ve reached the first destination on our way to closures: a fully-functioning symbol table that knows about free variables!

$ go test -run 'TestResolve*' ./compiler
ok      monkey/compiler 0.010s

We can head back to our failing compiler test:

$ go test ./compiler
--- FAIL: TestClosures (0.00s)
 compiler_test.go:927: testConstants failed: constant 0 -\
   testInstructions failed: wrong instructions length.
  want="0000 OpGetFree 0\n0002 OpGetLocal 0\n0004 OpAdd\n0005 OpReturnValue\n"
  got ="0000 OpGetLocal 0\n0002 OpAdd\n0003 OpReturnValue\n"
FAIL
FAIL    monkey/compiler 0.008s

Now that the symbol table knows about free variables, we only need to add two lines to the compilers loadSymbol method to fix this particular test:

// compiler/compiler.go

func (c *Compiler) loadSymbol(s Symbol) {
    switch s.Scope {
    case GlobalScope:
        c.emit(code.OpGetGlobal, s.Index)
    case LocalScope:
        c.emit(code.OpGetLocal, s.Index)
    case BuiltinScope:
        c.emit(code.OpGetBuiltin, s.Index)
    case FreeScope:
        c.emit(code.OpGetFree, s.Index)
    }
}

That gives us the correct OpGetFree instructions inside a closure. But outside, things still don’t work as expected:

$ go test ./compiler
--- FAIL: TestClosures (0.00s)
 compiler_test.go:900: testConstants failed: constant 1 -\
   testInstructions failed: wrong instructions length.
  want="0000 OpGetLocal 0\n0002 OpClosure 0 1\n0006 OpReturnValue\n"
  got ="0000 OpClosure 0 0\n0004 OpReturnValue\n"
FAIL
FAIL    monkey/compiler 0.009s

This tells us that we’re not loading the free variables on to the stack after we compiled a function and that the second operand for the OpClosure instruction is still the hardcoded 0.

What we have to do, right after we compiled a function’s body, is iterate through the FreeSymbols of the SymbolTable we just “left” and loadSymbol them. That should result in instructions in the enclosing scope that put the free variables on to the stack.

Here, too, the code explains things much more concisely than I can in prose:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.FunctionLiteral:
        // [...]
        if !c.lastInstructionIs(code.OpReturnValue) {
            c.emit(code.OpReturn)
        }

        freeSymbols := c.symbolTable.FreeSymbols
        numLocals := c.symbolTable.numDefinitions
        instructions := c.leaveScope()

        for _, s := range freeSymbols {
            c.loadSymbol(s)
        }

        compiledFn := &object.CompiledFunction{
            Instructions:  instructions,
            NumLocals:     numLocals,
            NumParameters: len(node.Parameters),
        }

        fnIndex := c.addConstant(compiledFn)
        c.emit(code.OpClosure, fnIndex, len(freeSymbols))

    // [...]
    }

    // [...]
}

A lot of this is just presented here to give you context for the changes, which are only five lines of code.

The first new line is the assignment of freeSymbols. It’s important that this happens before we call c.leaveScope(). Then, after we left the scope, we iterate through the freeSymbols in a loop and c.loadSymbol each.

The len(freeSymbols) is then used as the second operand to the OpClosure instruction. After the c.loadSymbol calls, the free variables sit on the stack waiting to be merged with an *object.CompiledFunction into an *object.Closure.

Five lines that give us a lot:

$ go test ./compiler
ok      monkey/compiler 0.008s

Would you look at that! We are successfully compiling closures! Compile time, check. Now we need to take care of the run time, which is when the magic of closures emerges.

Creating real closures at run time

Our VM is already running on closures. It doesn’t execute *object.CompiledFunctions anymore, but wraps them in *object.Closures when it executes an OpClosure instruction and then calls and executes those.

What’s missing is the part that creates “real” closures: the transfer of free variables to these closures and executing the OpGetFree instructions that load them on to the stack. Since we were so diligent about the preparation we can reach this goal with ease, taking tiny, easy to understand steps.

We start with a test that expects the VM to handle the simplest possible version of a real closure:

// vm/vm_test.go

func TestClosures(t *testing.T) {
    tests := []vmTestCase{
        {
            input: `
        let newClosure = fn(a) {
            fn() { a; };
        };
        let closure = newClosure(99);
        closure();
        `,
            expected: 99,
        },
    }

    runVmTests(t, tests)
}

In the test input newClosure returns a closure that closes over one free variable, the a parameter of newClosure. When the returned closure is called it should return this a. One closure, one free variable, one enclosing scope. We can do this.

The first thing we have to do is make use of the OpClosure’s second operand, which tells the VM how many free variables should be transferred to the specified closure. We’re already decoding but ignoring it, because we didn’t have free variables in place. Now we do and we have to use it to get them to work:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpClosure:
            constIndex := code.ReadUint16(ins[ip+1:])
            numFree := code.ReadUint8(ins[ip+3:])
            vm.currentFrame().ip += 3

            err := vm.pushClosure(int(constIndex), int(numFree))
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

We now pass two arguments to pushClosure: the index of the compiled function in the constant pool and the number of free variables waiting on the stack. Here it is:

// vm/vm.go

func (vm *VM) pushClosure(constIndex, numFree int) error {
    constant := vm.constants[constIndex]
    function, ok := constant.(*object.CompiledFunction)
    if !ok {
        return fmt.Errorf("not a function: %+v", constant)
    }

    free := make([]object.Object, numFree)
    for i := 0; i < numFree; i++ {
        free[i] = vm.stack[vm.sp-numFree+i]
    }
    vm.sp = vm.sp - numFree

    closure := &object.Closure{Fn: function, Free: free}
    return vm.push(closure)
}

New is the middle part. Here we take the second parameter, numFree, to construct a slice, free. Then, starting with the one that’s lowest on the stack, we take each free variable and copy it to free. Afterwards we clean up the stack by decrementing vm.sp manually.

The order of the copying is important, because that’s the same order in which the free variables were referenced inside the closure’s body and with which we put them on to the stack. If we were to reverse the order, the operands of the GetFree instructions would be wrong. That brings us to our next point: our VM doesn’t know about OpGetFree yet.

Implementing OpGetFree is not markedly different from implementing the other OpGet* instructions, except for the place from which the values are retrieved. This time it’s the Free slice of the *object.Closure the VM is currently executing:

// vm/vm.go

func (vm *VM) Run() error {
    // [...]
        switch op {
        // [...]

        case code.OpGetFree:
            freeIndex := code.ReadUint8(ins[ip+1:])
            vm.currentFrame().ip += 1

            currentClosure := vm.currentFrame().cl
            err := vm.push(currentClosure.Free[freeIndex])
            if err != nil {
                return err
            }

        // [...]
        }
    // [...]
}

As I said, only the place has changed. We decode the operand and use it as an index into the Free slice to retrieve the value and push it on to the stack. That’s all there is to it.

Now, in case you have a standing desk, you might want to sit down for this one. Take a look:

$ go test ./vm
ok      monkey/vm   0.036s

Yes, really. We implemented real closures! Fully! We’re done! Don’t believe me? Let’s throw some more tests at our VM and see what it does:

// vm/vm_test.go

func TestClosures(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {
            input: `
        let newAdder = fn(a, b) {
            fn(c) { a + b + c };
        };
        let adder = newAdder(1, 2);
        adder(8);
        `,
            expected: 11,
        },
        {
            input: `
        let newAdder = fn(a, b) {
            let c = a + b;
            fn(d) { c + d };
        };
        let adder = newAdder(1, 2);
        adder(8);
        `,
            expected: 11,
        },
    }

    runVmTests(t, tests)
}

Here we have closures that reference multiple free variables, some defined as parameters in the enclosing function, some as local variables. Cross your fingers:

$ go test ./vm
ok      monkey/vm   0.035s

Sweet! Let’s take it up a notch:

// vm/vm_test.go

func TestClosures(t *testing.T) {
    tests := []vmTestCase{
        // [...]
        {
            input: `
        let newAdderOuter = fn(a, b) {
            let c = a + b;
            fn(d) {
                let e = d + c;
                fn(f) { e + f; };
            };
        };
        let newAdderInner = newAdderOuter(1, 2)
        let adder = newAdderInner(3);
        adder(8);
        `,
            expected: 14,
        },
        {
            input: `
        let a = 1;
        let newAdderOuter = fn(b) {
            fn(c) {
                fn(d) { a + b + c + d };
            };
        };
        let newAdderInner = newAdderOuter(2)
        let adder = newAdderInner(3);
        adder(8);
        `,
            expected: 14,
        },
        {
            input: `
        let newClosure = fn(a, b) {
            let one = fn() { a; };
            let two = fn() { b; };
            fn() { one() + two(); };
        };
        let closure = newClosure(9, 90);
        closure();
        `,
            expected: 99,
        },
    }

  runVmTests(t, tests)
}

Now we have closures that return other closures, global bindings, local bindings, multiple closures being called in other closures, all thrown together and this thing still runs:

$ go test ./vm
ok      monkey/vm   0.039s

This is as close as you can get to “certified working”. With great confidence we can now say: we’ve successfully implemented closures in a bytecode compiler and a bytecode VM! We’ve added the crown jewel to our shiniest Monkey implementation. Time to celebrate.

Taking Time

We’re at the end of our journey. We did it. We successfully built a bytecode compiler and a virtual machine.

We’ve implemented binary and prefix operators, conditionals with jump instructions, global and local bindings, strings, arrays, hashes, first-class functions, higher-order functions, built-in functions and now even closures, the most prestigious of all the features.

It’s time we give ourselves a little pat on the back. With great contentment, with the fulfillment that comes after having put in the work, we can now watch as our compiler compiles and our VM executes the following piece of Monkey code.

This is the go-to example to showcase a programming language. Yes, it might be a cliché, but nevertheless, it’s a milestone and always brings a smile to my face. I’m talking about the recursive function for computing a Fibonacci number:

// vm/vm_test.go

func TestRecursiveFibonacci(t *testing.T) {
    tests := []vmTestCase{
        {
            input: `
        let fibonacci = fn(x) {
            if (x == 0) {
                return 0;
            } else {
                if (x == 1) {
                    return 1;
                } else {
                    fibonacci(x - 1) + fibonacci(x - 2);
                }
            }
        };
        fibonacci(15);
        `,
            expected: 610,
        },
    }

    runVmTests(t, tests)
}

Ah, recursion! Beautiful, isn’t it? Here we go, cross your fingers, knock on wood:

$ go test ./vm
--- FAIL: TestRecursiveFibonacci (0.00s)
 vm_test.go:725: compiler error: undefined variable fibonacci
FAIL
FAIL    monkey/vm   0.037s

Wait, what? It looks like the fibonacci can’t call itself.

Okay, I admit, I planned this, because I wanted to give you the pleasure of seeing how tiny the change is to make recursive functions work. All we have to do is take this part:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.LetStatement:
        err := c.Compile(node.Value)
        if err != nil {
            return err
        }

        symbol := c.symbolTable.Define(node.Name.Value)
        if symbol.Scope == GlobalScope {
            c.emit(code.OpSetGlobal, symbol.Index)
        } else {
            c.emit(code.OpSetLocal, symbol.Index)
        }

    // [...]
    }

    // [...]
}

And move one line, the symbol := ..., further up:

// compiler/compiler.go

func (c *Compiler) Compile(node ast.Node) error {
    switch node := node.(type) {
    // [...]

    case *ast.LetStatement:
        symbol := c.symbolTable.Define(node.Name.Value)
        err := c.Compile(node.Value)
        if err != nil {
            return err
        }

        if symbol.Scope == GlobalScope {
            c.emit(code.OpSetGlobal, symbol.Index)
        } else {
            c.emit(code.OpSetLocal, symbol.Index)
        }

    // [...]
    }

    // [...]
}

What this now does is to define the name to which a function will be bound right before the body is compiled, allowing the function’s body to reference the name of the function. That’s a one-line change that gives us this:

$ go test ./vm
ok      monkey/vm   0.034s

Beautiful! Now, using a recursive Fibonacci function to showcase a language’s ability is not exactly what created this aura of cliché – using it as a benchmark for a language’s performance is.

Knowing how fast a language can execute such a function tells us nothing about how it performs in a production setting, with real code and a real workload. But we also know that Monkey was never built for that anyway and that benchmarks and numbers are fun. And you also might remember that, in the first chapter, I promised that this new implementation of Monkey will be three times as fast as the old one. It’s time for me to deliver on that promise.

Let’s create a little utility that allows us to compare our evaluator from the first book against our new bytecode interpreter and see how fast they can calculate a Fibonacci number.

In a new folder, benchmark, we create a new main.go file:

// benchmark/main.go

package main

import (
    "flag"
    "fmt"
    "time"

    "monkey/compiler"
    "monkey/evaluator"
    "monkey/lexer"
    "monkey/object"
    "monkey/parser"
    "monkey/vm"
)

var engine = flag.String("engine", "vm", "use 'vm' or 'eval'")

var input = `
let fibonacci = fn(x) {
  if (x == 0) {
    0
  } else {
    if (x == 1) {
      return 1;
    } else {
      fibonacci(x - 1) + fibonacci(x - 2);
    }
  }
};
fibonacci(35);
`

func main() {
    flag.Parse()

    var duration time.Duration
    var result object.Object

    l := lexer.New(input)
    p := parser.New(l)
    program := p.ParseProgram()

    if *engine == "vm" {
        comp := compiler.New()
        err := comp.Compile(program)
        if err != nil {
            fmt.Printf("compiler error: %s", err)
            return
        }

        machine := vm.New(comp.Bytecode())

        start := time.Now()

        err = machine.Run()
        if err != nil {
            fmt.Printf("vm error: %s", err)
            return
        }

        duration = time.Since(start)
        result = machine.LastPoppedStackElem()
    } else {
        env := object.NewEnvironment()
        start := time.Now()
        result = evaluator.Eval(program, env)
        duration = time.Since(start)
    }

    fmt.Printf(
        "engine=%s, result=%s, duration=%s\n",
        *engine,
        result.Inspect(),
        duration)
}

There’s nothing here we haven’t seen before. The input is the same fibonacci function we already know we can compile and execute, except that this time, the input is 35, which gives our interpreters something to chew on.

In the main function we parse the command-line flag engine and, depending on its value, either execute the fibonacci snippet in the evaluator from the first book or compile it for and execute it in our new, shiny VM. Either way, we measure the time it takes to execute it and then print a summary of the benchmark.

Running it will tell us how much performance we gained by switching from a tree-walking interpreter to a compiler and a virtual machine – without focusing on performance at all and a lot of optimization opportunities left unused.

We build it into its own executable:

$ go build -o fibonacci ./benchmark

And now, welcome, first on the stage, the evaluator:

$ ./fibonacci -engine=eval
engine=eval, result=9227465, duration=27.204277379s

27 seconds. Time for our final pat on the back:

$ ./fibonacci -engine=vm
engine=vm, result=9227465, duration=8.876222455s

8 seconds. 3.3 times faster.

Resources

Books

Abelson, Harold and Sussman, Gerald Jay with Sussman, Julie. 1996. Structure and Interpretation of Computer Programs, Second Edition. MIT Press.

Appel, Andrew W.. 2004. Modern Compiler Implementation in C. Cambridge University Press.

Appel, Andrew W.. 2004. Modern Compiler Implementation in ML. Cambridge University Press.

Cooper, Keith D. and Torczon Linda. 2011. Engineering a Compiler, Second Edition. Morgan Kaufmann.

Grune, Dick and Jacobs, Ceriel. 1990. Parsing Techniques. A Practical Guide.. Ellis Horwood Limited.

Grune, Dick and van Reeuwijk, Kees and Bal Henri E. and Jacobs, Ceriel J.H. Jacobs and Langendoen, Koen. 2012. Modern Compiler Design, Second Edition. Springer

Nisan, Noam and Schocken, Shimon. 2008. The Elements Of Computing Systems. MIT Press.

Parr, Terrence. 2010. Language Implementation Patterns: Create Your Own Domain-Specific and General Programming Languages. Pragmatic Programmers.

Queinnec, Christian. 2003. Lisp in Small Pieces. Cambridge University Press.

Papers

Ayock, John. 2003. A Brief History of Just-In-Time. In ACM Computing Surveys, Vol. 35, No. 2, June 2003

Dybvig, R. Kent. 2006. The Development of Chez Scheme. In ACM ICFP ’06

Dybvig, R. Kent. 1987. Three Implementation Models for Scheme. Dissertation, University of North Carolina at Chapel Hill

Ertl, M. Anton and Gregg, David. 2003. The Structure and Performance of Efficient Interpreters. In Journal Of Instruction-Level Parallelism 5 (2003)

Ghuloum, Abdulaziz. 2006. An Incremental Approach To Compiler Construction. In Proceedings of the 2006 Scheme and Functional Programming Workshop.

Ierusalimschy, Robert and de Figueiredo, Luiz Henrique and Celes Waldemar. The Implementation of Lua 5.0. https://www.lua.org/doc/jucs05.pdf

Pratt, Vaughan R. 1973. Top Down Operator Precedence. Massachusetts Institute of Technology.

Romer, Theodore H. and Lee, Dennis and Voelker, Geoffrey M. and Wolman, Alec and Wong, Wayne A. and Baer, Jean-Loup and Bershad, Brian N. and Levy, Henry M.. 1996. The Structure and Performance of Interpreters. In ASPLOS VII Proceedings of the seventh international conference on Architectural support for programming languages and operating systems.

Fang, Ruijie and Liu. A Performance Survey on Stack-based and Register-based Virtual Machines.

Web

Aaron Patterson - Reducing Memory Usage In Ruby: https://tenderlovemaking.com/2018/01/23/reducing-memory-usage-in-ruby.html

Allison Kaptur - A Python Interpreter Written in Python: http://aosabook.org/en/500L/a-python-interpreter-written-in-python.html

Andy Wingo - a lambda is not (necessarily) a closure: https://wingolog.org/archives/2016/02/08/a-lambda-is-not-necessarily-a-closure

Andy Wingo - a register vm for guile: https://wingolog.org/archives/2013/11/26/a-register-vm-for-guile

Andy Wingo - the half strap: self-hosting and guile: https://wingolog.org/archives/2016/01/11/the-half-strap-self-hosting-and-guile

Eli Bendersky - Adventures in JIT compilation: Part 2 - an x64 JIT: https://eli.thegreenplace.net/2017/adventures-in-jit-compilation-part-2-an-x64-jit/

GNU Guile Documentation - About Closures - https://www.gnu.org/software/guile/manual/guile.html#About-Closure

Jack W. Crenshaw - Let’s Build a Compiler! - http://compilers.iecc.com/crenshaw/tutorfinal.pdf

Kein-Hong Man - A No-Frills Introduction to Lua 5.1 VM Instructions: http://luaforge.net/docman/83/98/ANoFrillsIntroToLua51VMInstructions.pdf

Lua 5.3 Bytecode Reference: http://the-ravi-programming-language.readthedocs.io/en/latest/lua_bytecode_reference.html

LuaJIT 2.0 Bytecode Instructions: http://wiki.luajit.org/Bytecode-2.0

Mathew Zaleski - Dispatch Techniques: http://www.cs.toronto.edu/~matz/dissertation/matzDissertation-latex2html/node6.html

Matt Might - Closure Conversion - “Flat Closures”: http://matt.might.net/articles/closure-conversion/

Matt Might - Compiling Scheme to C with closure conversion: http://matt.might.net/articles/compiling-scheme-to-c/

Mozilla SpiderMonkey Internals: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/Internals

Stack Overflow - Implementation of closures in Lua?: https://stackoverflow.com/questions/7781432/implementation-of-closures-in-lua

The Cliffs of Inanity - Emacs JIT Calling Convention: http://tromey.com/blog/?p=999

Vyacheslav Egorov - Explaining JavaScript VMs in JavaScript - Inline Caches: https://mrale.ph/blog/2012/06/03/explaining-js-vms-in-js-inline-caches.html

Peter Michaux - Scheme from Scratch - Introduction: http://peter.michaux.ca/articles/scheme-from-scratch-introduction

Source Code

8cc - A Small C Compiler - https://github.com/rui314/8cc

GNU Guile 2.2 - https://www.gnu.org/software/guile/download/

MoarVM - A modern VM built for Rakudo Perl 6 - https://github.com/MoarVM/MoarVM

The Lua Programming Language (1.1, 3.1, 5.3.2) - https://www.lua.org/versions.html

The Ruby Programming Language - https://github.com/ruby/ruby

The Wren Programming Language - https://github.com/munificent/wren

c4 - C in four functions - https://github.com/rswier/c4

tcc - Tiny C Compiler - https://github.com/LuaDist/tcc

Feedback

If you spot a typo, find something wrong with the code, have a suggestion to make or just a question, feel free to send me an email:

me@thorstenball.com

Changelog

31 July 2018 - 1.0

Initial Release