From be99c013631abbe612f5340be680ba4913343f7e Mon Sep 17 00:00:00 2001 From: Aaron Taylor Date: Mon, 30 Mar 2020 23:27:49 -0700 Subject: [PATCH] Rewrite of main VVhitespace README. --- README.md | 108 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 90 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index d0ef628..a1e2d3e 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,111 @@ # Overview # -Welcome to the VVhitespace language. This repository provides two main tools. +Welcome to VVhitespace! -A compiler, `vvc`, accepts human-readable VVhitespace source code and translates -it to true VVhitespace code. VVhitespace code is represented with the *whitespace -characters* `[tTvVsSnN]` corresponding to `[Tab]`, `[Vtab]`, `[Space]`, -`[Newline]`, respectively. The first character on a line which is not from this -set begins a comment which ends with the line. See the standard library for -examples in this style. +If you are impatient to get started, simply execute `make` in the top-level +directory to build the compiler and interpreter, then move to one of the +example directories like `examples/wumpus` and execute `make run`. -An interpreter, `vvi`, accepts true VVhitespace files as generated by `vvc` and -executes them according to the rules in `reference.md`. +VVhitespace is descended from Whitespace, adding a vertical tab to the language +along with some restrictions to ease implementation. VVhitespace code is +represented with the *whitespace characters* `[Tab]`, `[VTab]`, `[Space]`, and +`[Newline]`. All other characters are considered commentary. + +This repository includes several distinct parts: + + - A compiler, `vvc`, accepts human-readable VVhitespace source code and + translates it to true VVhitespace code. + + - An interpreter, `vvi`, accepts true VVhitespace files as generated by `vvc` + and executes them according to the rules in `reference.md`. + + - A library of useful functions including enhanced stack operations, printf, + math operations including random number generation, heap operations, string + manipulations and user interactions, and bitwise logic functions. See the + `stdlib/README.md` for more details. + + - Hunt the Wumpus, a text game in which you explore a randomly connected set + of caverns, avoiding deep pits and giant cave bats, all while shooting + arrows at a Wumpus that wants to eat a tasty, meaty human like yourself! The + cave entrance is rumored to be near `examples/hunt-the-wumpus/README.md`. + + - Examples including code commentary that demonstrate VVhitespace and the + stdlib. See individual subdirectories under `examples/` for details. + + - Tests for both the VVhitespace language and the stdlib. Intended to + increase confidence for users that want to tinker with the internals, both + test suites come with a README explaining how to run the tests and extend them + as necessary. To execute all tests, simply run `make test` in the top level + directory. + +From this point forward, READMEs will assume you have a basic knowledge of +VVhitespace (or at least Whitespace). The file `reference.md` provides a short +but comprehensive language reference copied largely from the original +Whitespace language tutorial. + + +# Status # + +Complete. Tested on FreeBSD and Debian Linux (w/'build-essential' package). # Instructions # To build the VVhitespace software, simply run `make` in the top level directory. This will produce two binaries, `vvc` for compiling human-readable -pseudo-vvhitespace into true vvhitespace, and `vvi` for interpreting/executing -vvhitespace programs. +pseudo-VVhitespace into true VVhitespace, and `vvi` for interpreting/executing +VVhitespace programs. Use these two programs to build and run your VVS programs: vvc -i your_code.pvvs -o output_file.vvs vvi -i output_file.vvs +By convention, the extension `.pvvs` is used for pseudo-VVhitespace code and +`.vvs` is used for true VVhitespace code. + +The stdlib uses the C preprocessor to `#include` library files. Projects like +`examples/hello-world` demonstrate combining the stdlib and the C preprocessor +in the `Makefile`. The invocation will take this general form: + + cpp -I/path/to/stdlib/files -I. -o temp.pvvs your_code.pvvs + vvc -i temp.pvvs -o output_file.vvs + vvi -i output_file.vvs + +Alternatively, you may simply hijack one of the example projects. All are +pre-configured to compile with the standard library using `make run` and only +require the user to `#include` the appropriate stdlib files for the functions +called. For example, if the `printf` function was used, the bottom of the file +should include this line: + + #include + +Before running the VVhitespace or stdlib tests, read `README.md` in their +respective directories. It details the steps required to configure the tests. +Every test is also a minimal example for a single VVhitespace feature or stdlib +function, with documented input and expected output. + + +# Helpful Hints # + +Syntax highlighting greatly eases both reading and writing VVhitespace code. +Examples for `vim` (and any other editor with regex based syntax highlighting) +can be found in `syntax_highlighting/README.md`. + +In addition to Hunt the Wumpus, the `examples/` directory provides several +other smaller examples. All have comprehensible `Makefile` and code that is +easily modified to use as the start of your own project. -# Examples # -The `examples/` folder contains examples with Makefiles. Simply `cd` into an -example and `make run` to build and execute it. Don't forget to build `vvc` -and `vvi` first! More details can be found in `examples/README.md`. +# Backward Compatibility # +Since the `[VTab]` character is considered a comment character in Whitespace, +most VVhitespace code should also be valid Whitespace code, and usually with +similar results. All other changes to the language attempt to restrict +implementation impediments without violating the original definition. -# Standard Library # +Tests are included for both the core VVhitespace language and the stdlib. After +compiling with `cpp` and `vvc`, the resulting tests may be executed with any +Whitespace compiler to identify any specific incompatibilities. Everything has +been kept simple in the hope it will be easy to modify. -A standard library provides a few convenience functions. More details can be found -in `stdlib/README.md`. A working example can be found in `examples/hello-stdlib`. -- 2.20.1