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