Add an interpreter

[fur] / README.md

diff --git a/README.md b/README.md
index 1b0478a..8ea0e99 100644 (file)
--- a/README.md
+++ b/README.md
@@ -3,15 +3,51 @@
 Fur is a programming language for the next millenium. In 1000 years, humans will likely still like
 furry animals, so Fur is named in their honor.
 
-Example Fur programs are in the `examples/` folder. The main compiler (`main.py`) compiles Fur
+## Installation
+
+1. Create and activate a virtual environment with Python 3. On most systems, this will look something like `python3 -m venv .env/ && .env/bin/activate`.
+2. Install dependencies from `requirements.txt` using `pip`: `pip install -r requirements.txt`.
+3. That's all!
+
+# Running
+
+Example Fur programs are in the `examples/` folder. The main compiler (`main.py compile`) compiles Fur
 programs to C. An example of usage:
 
-    ~/fur$ python3 main.py examples/01_hello.fur
+    ~/fur$ python main.py examples/01_hello.fur
     ~/fur$ gcc examples/01_hello.fur.c 
     ~/fur$ ./a.out
     Hello, world~/fur$ 
 
-Fur is GPL and will only ever target GPL compilers. Fur supports closures, integer math, boolean
-logic, and strings (implemented as [ropes](https://en.wikipedia.org/wiki/Rope_(data_structure\))). It
-doesn't yet support exceptions, multithreading, modules, or anything resembling a standard library.
-If that sounds like something you want to use in production code, good luck to you.
+You can also run the programs through an interpreter (`main.py interpret`):
+
+    ~/fur$ python main.py examples/01_hello.fur
+    Hello, world$
+
+The final way to invoke the main program is `main.py ir`. This outputs an intermediate "assembly" for the bytecode representation of the program:
+
+    ~/fur$ python main.py ir examples/01_hello.fur
+    __main__:
+        push_string "Hello, world"
+        push sym(print)
+        call 1
+        drop
+        end nil
+
+## Integration tests
+
+Integration tests are divided into three categories:
+
+* Compiler output tests: test that compiled Fur programs give expected output. Run with `python integration_tests.py CompilerOutputTests`.
+* Interpreter output tests: test that interpreted Fur programs give expected output. Run with `python integration_tests.py InterpreterOutputTests`.
+* Memory lead tests: test that compiled Fur programs don't leak memory (requires Valgrind). Run with `python integration_tests.py MemoryLeakTests`.
+
+Calling `python integration_tests.py` with no arguments runs all the integration tests.
+
+## Disclaimers
+
+Fur is GPL 3 and will only ever target GPL compilers. Fur supports closures, integer math, boolean
+logic, lists, structures (similar to objects), and strings (implemented as
+[ropes](https://en.wikipedia.org/wiki/Rope_(data_structure))).  It doesn't yet support
+exceptions, multithreading, modules, or anything resembling a standard library.  If that sounds
+like something you want to use in production code, good luck to you.