| 1 | # Overview # |
| 2 | |
| 3 | Welcome to VVhitespace! |
| 4 | |
| 5 | If you are impatient to get started, simply execute `make` in the top-level |
| 6 | directory to build the compiler and interpreter, then move to one of the |
| 7 | example directories like `examples/hunt-the-wumpus` and execute `make run`. |
| 8 | |
| 9 | VVhitespace is descended from Whitespace, adding a vertical tab to the language |
| 10 | along with some restrictions to ease implementation. VVhitespace code is |
| 11 | represented with the *whitespace characters* `[Tab]`, `[VTab]`, `[Space]`, and |
| 12 | `[Newline]`. All other characters are considered commentary. |
| 13 | |
| 14 | VVhitespace makes a number of small changes to Whitespace with the intention of |
| 15 | *taming* it by providing the tools necessary in order to make non-trivial |
| 16 | whitespace-only applications. As proof of concept, I wrote an implementation of |
| 17 | Hunt the Wumpus in VVhitespace. |
| 18 | |
| 19 | This repository includes several distinct parts: |
| 20 | |
| 21 | - A compiler, `vvc`, accepts human-readable VVhitespace source code and |
| 22 | translates it to true VVhitespace code. |
| 23 | |
| 24 | - An interpreter, `vvi`, accepts true VVhitespace files as generated by `vvc` |
| 25 | and executes them according to the rules in `reference.md`. |
| 26 | |
| 27 | - A library of useful functions including enhanced stack operations, printf, |
| 28 | math operations including random number generation, heap operations, string |
| 29 | manipulations and user interactions, and bitwise logic functions. See the |
| 30 | `stdlib/README.md` for more details. |
| 31 | |
| 32 | - Hunt the Wumpus, a text game in which you explore a randomly connected set |
| 33 | of caverns, avoiding deep pits and giant cave bats, all while shooting |
| 34 | arrows at a Wumpus that wants to eat a tasty, meaty human like yourself! The |
| 35 | cave entrance is rumored to be near `examples/hunt-the-wumpus/README.md`. |
| 36 | |
| 37 | - Examples including code commentary that demonstrate VVhitespace and the |
| 38 | stdlib. See individual subdirectories under `examples/` for details. |
| 39 | |
| 40 | - Tests for both the VVhitespace language and the stdlib. Intended to |
| 41 | increase confidence for users that want to tinker with the internals, both |
| 42 | test suites come with a README explaining how to run the tests and extend them |
| 43 | as necessary. To execute all tests, simply run `make test` in the top level |
| 44 | directory. |
| 45 | |
| 46 | From this point forward, READMEs will assume you have a basic knowledge of |
| 47 | VVhitespace (or at least Whitespace). The file `reference.md` provides a short |
| 48 | but comprehensive language reference copied largely from the original |
| 49 | Whitespace language tutorial. |
| 50 | |
| 51 | |
| 52 | # Status # |
| 53 | |
| 54 | Complete. Tested on FreeBSD and Debian Linux (w/'build-essential' package). |
| 55 | |
| 56 | |
| 57 | # Instructions # |
| 58 | |
| 59 | To build the VVhitespace software, simply run `make` in the top level directory. |
| 60 | This will produce two binaries, `vvc` for compiling human-readable |
| 61 | pseudo-VVhitespace into true VVhitespace, and `vvi` for interpreting/executing |
| 62 | VVhitespace programs. |
| 63 | |
| 64 | Use these two programs to build and run your VVS programs: |
| 65 | |
| 66 | vvc -i your_code.pvvs -o output_file.vvs |
| 67 | vvi -i output_file.vvs |
| 68 | |
| 69 | By convention, the extension `.pvvs` is used for pseudo-VVhitespace code and |
| 70 | `.vvs` is used for true VVhitespace code. |
| 71 | |
| 72 | The stdlib uses the C preprocessor to `#include` library files. Projects like |
| 73 | `examples/hello-world` demonstrate combining the stdlib and the C preprocessor |
| 74 | in the `Makefile`. The invocation will take this general form: |
| 75 | |
| 76 | cpp -I/path/to/stdlib/files -I. -o temp.pvvs your_code.pvvs |
| 77 | vvc -i temp.pvvs -o output_file.vvs |
| 78 | vvi -i output_file.vvs |
| 79 | |
| 80 | Alternatively, you may simply hijack one of the example projects. All are |
| 81 | pre-configured to compile with the standard library using `make run` and only |
| 82 | require the user to `#include` the appropriate stdlib files for the functions |
| 83 | called. For example, if the `printf` function was used, the bottom of the file |
| 84 | should include this line: |
| 85 | |
| 86 | #include <stdio.pvvs> |
| 87 | |
| 88 | Before running the VVhitespace or stdlib tests, read `README.md` in their |
| 89 | respective directories. It details the steps required to configure the tests. |
| 90 | Every test is also a minimal example for a single VVhitespace feature or stdlib |
| 91 | function, with documented input and expected output. |
| 92 | |
| 93 | |
| 94 | # Helpful Hints # |
| 95 | |
| 96 | Syntax highlighting greatly eases both reading and writing VVhitespace code. |
| 97 | Examples for `vim` (and any other editor with regex based syntax highlighting) |
| 98 | can be found in `syntax_highlighting/README.md`. |
| 99 | |
| 100 | In addition to Hunt the Wumpus, the `examples/` directory provides several |
| 101 | other smaller examples. All have comprehensible `Makefile` and code that is |
| 102 | easily modified to use as the start of your own project. |
| 103 | |
| 104 | |
| 105 | # Backward Compatibility # |
| 106 | |
| 107 | Since the `[VTab]` character is considered a comment character in Whitespace, |
| 108 | most VVhitespace code should also be valid Whitespace code, and usually with |
| 109 | similar results. All other changes to the language attempt to restrict |
| 110 | implementation impediments without violating the original definition. |
| 111 | |
| 112 | Tests are included for both the core VVhitespace language and the stdlib. After |
| 113 | compiling with `cpp` and `vvc`, the resulting tests may be executed with any |
| 114 | Whitespace compiler to identify any specific incompatibilities. Everything has |
| 115 | been kept simple in the hope it will be easy to modify. |
| 116 | |