-rw-r--r-- 688 Makefile
-rw-r--r-- 1473 README.md
drwxr-xr-x - examples
-rw-r--r-- 3678 rationale.md
-rw-r--r-- 5388 reference.md
drwxr-xr-x - stdlib
drwxr-xr-x - stdlib_tests
drwxr-xr-x - syntax_highlighting
drwxr-xr-x - tests
-rw-r--r-- 5186 vv_compiler.c
-rw-r--r-- 16275 vv_interpreter.c

Overview

Welcome to VVhitespace!

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/hunt-the-wumpus and execute make run.

VVhitespace is descended from Whitespace, making a number of small changes with the intention of taming the language, providing the tools necessary to write non-trivial, whitespace-only applications. As a proof of concept, I have implemented Hunt the Wumpus in VVhitespace.

This repository includes several distinct parts:

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.

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 <stdio.pvvs>

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.

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.

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.