Add an interpreter

[fur] / README.md

diff --git a/README.md b/README.md
index e599640..8ea0e99 100644 (file)
--- a/README.md
+++ b/README.md
@@ -3,16 +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.
 
 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:
 
 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$ 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
+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
 logic, lists, structures (similar to objects), and strings (implemented as

-[ropes](https://en.wikipedia.org/wiki/Rope_(data_structure)))).  It doesn't yet support
+[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.
 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.