From cbbb46ce0849bf37b0ccece2e4328d25fc64ebf8 Mon Sep 17 00:00:00 2001 From: Aaron Taylor Date: Tue, 2 Jul 2019 14:48:23 -0700 Subject: [PATCH] Added specification for VVhitespace language. --- rational.md | 31 +++++++++++++ reference.md | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 153 insertions(+) create mode 100644 rational.md create mode 100644 reference.md diff --git a/rational.md b/rational.md new file mode 100644 index 0000000..501e4aa --- /dev/null +++ b/rational.md @@ -0,0 +1,31 @@ +VVhitespace is descended from Whitespace, adding a vertical tab to the language +along with some restrictions to ease implementation. The name is intended to +embrace the spirit of Whitespace's visual incomprehensibility. + +Since Whitespace ignores [VTab] as a comment character, and since the +Whitespace VM is a superset of the VVhitespace VM, all valid VVhitespace +programs are also valid Whitespace programs. + +Locating a Whitespace interpreter capable of running all valid Whitespace +programs is left as an exercise for the reader. For the inquisitive, the +following program, read top-down, is both a valid VVhitespace and Whitespace +program. Does it terminate or infinitely loop? + +[Space] +[Space] +[Space] +[Tab] +[LF] +[LF] +[Space] +[LF] +[Space] +[Tab] +[LF] +[VTab] +[Space] +[Tab] +[LF] +[LF] +[LF] +[LF] diff --git a/reference.md b/reference.md new file mode 100644 index 0000000..c5c4344 --- /dev/null +++ b/reference.md @@ -0,0 +1,122 @@ +# Overview # + +This document is a complete specification for the VVhitespace language. + +Since Whitespace and VVhitespace are closely related, this document is heavily +copied/adapted from the "Whitespace Tutorial" published by e.c.brady@dur.ac.uk. + +# Reference # + +The only lexical tokens in the VVhitespace language are + + * Tab (ASCII 9), + * Line Feed (ASCII 10), + * Vertical Tab (ASCII 11), and + * Space (ASCII 32). + +The language itself is an imperative, stack based language. Each command +consists of a series of tokens, beginning with the Instruction Modification +Parameter (IMP). These are listed in the table below. + +| IMP | Meaning | +| :----------- | :----------------- | +| [Space] | Stack Manipulation | +| [Tab][Space] | Arithmetic | +| [Tab][Tab] | Heap access | +| [LF] | Flow Control | +| [Tab][LF] | I/O | + +The virtual machine on which programs run has a stack and a heap, both of +fixed, implementation defined size and both designed around a 64-bit word. The +programmer may push and pop words from the stack in addition to accessing the +heap on a per-word basis as a permanent store of variables and data structures. + +Many commands require numbers or labels as parameters. + +Numbers are integers ranging from `-(2^63)` to `+(2^63)-1` and are represented +in sign-magnitude format as a sign, either [Space] for positive or [Tab] for +negative, followed by a series of [Space] (zero) and [Tab] (one) digits +terminated by a [LF]. Note that positive and negative zero are considered +equivalent. As an example, the decimal number +42 has the following +representation. + + [Space] [Tab][Space][Tab][Space][Tab][Space] [LF] + +Labels consist of an opening [VTab] followed by a [LF] terminated list of up +to sixteen spaces and tabs. There is only one global namespace so all labels +must be unique. Labels are left-padded with [Space] up to sixteen characters; +the following two labels are interchangeable. + + [VTab] [Tab][Space][Tab] [LF] + [VTab] [Space][Tab][Space][Tab] [LF] + +## Stack Manipulation (IMP: [Space]) ## + +Stack manipulation is one of the more common operations, hence the shortness of +the IMP [Space]. There are four stack instructions. + +| Command | Params | Meaning | +| :---------- | :----- | :---------------------------------- | +| [Space] | Number | Push the number onto the stack | +| [LF][Space] | --- | Duplicate the top item on the stack | +| [LF][Tab] | --- | Swap the top two items on the stack | +| [LF][LF] | --- | Discard the top item on the stack | + +## Arithmetic (IMP: [Tab][Space]) ## + +Arithmetic commands operate on the top two items on the stack, and replace them +with the result of the operation. The first item pushed is considered to be +left of the operator. + +| Command | Params | Meaning | +| :------------- | :----- | :--------------- | +| [Space][Space] | --- | Addition | +| [Space][Tab] | --- | Subtraction | +| [Space][LF] | --- | Multiplication | +| [Tab][Space] | --- | Integer Division | +| [Tab][Tab] | --- | Modulo | + +## Heap Access (IMP: [Tab][Tab]) ## + +Heap access commands look at the stack to find the address of items to be +stored or retrieved. To store an item, push the address then the value and run +the store command. To retrieve an item, push the address and run the retrieve +command, which will place the value stored in the location at the top of the +stack. + +| Command | Params | Meaning | +| :------ | :----- | :------- | +| [Space] | --- | Store | +| [Tab] | --- | Retrieve | + +## Flow Control (IMP: [LF]) ## + +Flow control operations are also common. Subroutines are marked by labels, as +well as the targets of conditional and unconditional jumps, by which loops can +be implemented. Programs must be ended by means of [LF][LF][LF] so that the +interpreter can exit cleanly. + +| Command | Params | Meaning | +| :------------- | :----- | :------------------------------- | +| [Space][Space] | Label | Mark a location in the program | +| [Space][Tab] | Label | Call a subroutine | +| [Space][LF] | Label | Jump unconditionally to a label | +| [Tab][Space] | Label | Jump to label if TOS is zero | +| [Tab][Tab] | Label | Jump to label if TOS is negative | +| [Tab][LF] | --- | Return from subroutine | +| [LF][LF] | --- | End the program | + +## I/O (IMP: [Tab][LF]) ## + +Finally, we need to be able to interact with the user. There are IO +instructions for reading and writing numbers and individual characters. + +The read instructions take the heap address in which to store the result from +the top of the stack. + +| Command | Params | Meaning | +| :------------- | :----- | :------------------------------------------------ | +| [Space][Space] | --- | Output the character at the TOS | +| [Space][Tab] | --- | Output the number at the TOS | +| [Tab][Space] | --- | Read character and store at location given by TOS | +| [Tab][Tab] | --- | Read number and store at location given by TOS | -- 2.20.1