This is the repo used for the in-progress book "Crafting Interpreters". Itcontains the Markdown text of the book, full implementations of bothinterpreters, as well as the build system to weave the two together into thefinal site.
If you find an error or have a suggestion, please do file an issue here. Thankyou!
Contributing
One of the absolute best things about writing a book online and putting it outthere before it's done is that people like you have been kind enough to give mefeedback, point out typos, and find other errors or unclear text.
If you'd like to do that, great! You can just file bugs here on the repo, orsend a pull request if you're so inclined. If you want to send a pull request,but don't want to get the build system set up to regenerate the HTML too, don'tworry about it. I'll do that when I pull it in.
Ports and implementations
Another way to get involved is by sharing your own implementation of Lox. Portsto other languages are particularly useful since not every reader likes Java andC. Feel free to add your Lox port or implementation to the wiki:
Building Stuff
I am a terribly forgetful, error-prone mammal, so I automated as much as Icould.
Prerequisites
I develop on an OS X machine, but any POSIX system should work too. With alittle extra effort, you should be able to get this working on Windows as well,though I can't help you out much.
Most of the work is orchestrated by make. The build scripts, test runner, andother utilities are all written in Dart. Instructions to install Dart arehere. Once you have Dart installed and on your path, run:
$ make get
This downloads all of the packages used by the build and test scripts.
In order to compile the two interpreters, you also need a C compiler on yourpath as well as javac.
Building
Once you've got that setup, try:
$ make
If everything is working, that will generate the site for the book as well ascompiling the two interpreters clox and jlox. You can run either interpreterright from the root of the repo:
$ ./clox
$ ./jlox
Hacking on the book
The Markdown and snippets of source code are woven together into the final HTMLusing a hand-written static site generator that started out as a single tinyPython script for my first book and somehow grew into somethingapproximating a real program.
The generated HTML is committed in the repo under site/. It is built from acombination of Markdown for prose, which lives in book/, and snippets of codethat are weaved in from the Java and C implementations in java/ and c/. (Allof those funny looking comments in the source code are how it knows whichsnippet goes where.)
The script that does all the magic is tool/bin/build.dart. You can run thatdirectly, or run:
$ make book
That generates the entire site in one batch. If you are incrementally workingon it, you'll want to run the development server:
$ make serve
This runs a little HTTP server on localhost rooted at the site/ directory.Any time you request a page, it regenerates any files whose sources have beenchanged, including Markdown files, interpreter source files, templates, andassets. Just let that keep running, edit files locally, and refresh yourbrowser to see the changes.
Building the interpreters
You can build each interpreter like so:
$ make clox
$ make jlox
This builds the final version of each interpreter as it appears at the end ofits part in the book.
You can also see what the interpreters look like at the end of each chapter. (Iuse this to make sure they are working even in the middle of the book.) This isdriven by a script, tool/bin/split_chapters.dart that uses the same commentmarkers for the code snippets to determine which chunks of code are present ineach chapter. It takes only the snippets that have been seen by the end of eachchapter and produces a new copy of the source in gen/, one directory for eachchapter's code. (These are also an easier way to view the source code since theyhave all of the distracting marker comments stripped out.)
Then, each of those can be built separately. Run:
$ make c_chapters
And in the build/ directory, you'll get an executable for each chapter, likechap14_chunks, etc. Likewise:
$ make java_chapters
This compiles the Java code to classfiles in build/gen/ in a subdirectory foreach chapter.
Testing
I have a full Lox test suite that I use to ensure the interpreters in the bookdo what they're supposed to do. The test cases live in test/. The Dartprogram tool/bin/test.dart is a test runner that runs each of those testfiles on a Lox interpreter, parses the result, and validates that that the testdoes what it's expected to do.
There are various interpreters you can run the tests against:
$ make test # The final versions of clox and jlox.
$ make test_clox # The final version of clox.
$ make test_jlox # The final version of jlox.
$ make test_c # Every chapter's version of clox.
$ make test_java # Every chapter's version of jlox.
$ make test_all # All of the above.
Testing your implementation
You are welcome to use the test suite and the test runner to test your own Loximplementation. The test runner is at tool/bin/test.dart and can be given acustom interpreter executable to run using --interpreter. For example, if youhad an interpreter executable at my_code/boblox, you could test it like:
$ dart tool/bin/test.dart clox --interpreter my_code/boblox
You still need to tell it which suite of tests to run because that determinesthe test expectations. If your interpreter should behave like jlox, use "jlox"as the suite name. If it behaves like clox, use "clox". If your interpreter isonly complete up to the end of one of the chapters in the book, you can usethat chapter as the suite, like "chap10_functions". See the Makefile for thenames of all of the chapters.
If your interpreter needs other command line arguments passed to use, pass themto the test runner using --arguments and it will forward to your interpreter.
Repository Layout
asset/– Sass files and jinja2 templates used to generate the site.book/- Markdown files for the text of each chapter.build/- Intermediate files and other build output (except for the siteitself) go here. Not committed to Git.c/– Source code of clox, the interpreter written in C. Also contains anXCode project, if that's your thing.gen/– Java source files generated by GenerateAst.java go here. Notcommitted.java/– Source code of jlox, the interpreter written in Java.note/– Various research, notes, TODOs, and other miscellanea.note/answers– Sample answers for the challenges. No cheating!site/– The final generated site. The contents of this directory directlymirror craftinginterpreters.com. Most content here is generated by build.py,but fonts, images, and JS only live here. Everything is committed, even thegenerated content.test/– Test cases for the Lox implementations.tool/– Dart package containing the build, test, and other scripts.