--------------------------------------------------------------------------- Argh! and Aargh! Language Specification $Id: Argh-Spec.txt,v 1.10 2004/07/14 11:45:55 wilde Exp $ Many thanks to Daniel Cristofani, who did a great job revising and cleaning up this spec. --------------------------------------------------------------------------- General Argh! provides a two-dimensional code/data array of 80x40 cells, and an infinite stack. Both the array cells and the stack can hold signed integer values. The range of the storeable values is implementation- dependent, but they are guaranteed to be at least signed 32-bit values. The stack is initially empty. A valid Argh! program consists of printable 7-bit ASCII characters, spaces, and linefeeds (no tabs!). On startup the code/data array is initialized with the Argh! program, without the linefeeds, starting at position 0,0 (the top left corner). The program must fit into the code/data array, so no line of the program may be longer than 80 characters and the whole program must not be longer than 40 lines. The program may be smaller than the code/data array, in which case the values of the uninitialized cells are undefined. The instruction pointer starts at position 0,0 of the code/data array. The "execution direction" (direction of movement of the instruction pointer) may be any of "left", "down", "up", "right", and can be changed by flow control instructions. There is no default execution direction, so a valid Argh! program must start with a flow control instruction. When the cell at the instruction pointer is executed its value is evaluated as an Argh! instruction, and that instruction is performed; then the instruction pointer moves one cell in the execution direction. If Argh! tries to execute a cell which is not a valid Argh! instruction, or if program execution tries to leave the code/data array, Argh! will fail and print out its standard error message. Each Argh! instruction consists of one ascii character. This is the complete list of valid instructions: Flow Control: h - set execution direction to "left" j - set execution direction to "down" k - set execution direction to "up" l - set execution direction to "right" H - jump (move instruction pointer) left to the next cell whose value matches the value on top of the stack, and set execution direction to "left" J - jump down to the next cell whose value matches the value on top of the stack, and set execution direction to "down" K - jump up to the next cell whose value matches the value on top of the stack, and set execution direction to "up" L - jump right to the next cell whose value matches the value on top of the stack, and set execution direction to "right" x - if the value on top of the stack is positive, turn the execution direction 90 degrees to the right X - if the value on top of the stack is negative, turn the execution direction 90 degrees to the left q - quit: end program execution Stack: s - store (push) value of the cell below the current cell to stack S - store (push) value of the cell above the current cell to stack d - duplicate top value on stack D - delete top value off stack a - add value of the cell below the current cell to the value on top of the stack A - add value of the cell above the current cell to the value on top of the stack r - reduce the value on top of the stack by the value of the cell below R - reduce the value on top of the stack by the value of the cell above f - fetch (pop) value from top of stack and store to cell below F - fetch (pop) value from top of stack and store to cell above I/O: p - send value below the current cell to stdout P - send value above the current cell to stdout g - get one byte from stdin and store in cell below G - get one byte from stdin and store in cell above e - insert value of system EOF in cell below E - insert value of system EOF in cell above Undocumented Instructions: # - behaves just like 'j', but only if its position in the code/data array is 0,0 (the left/top corner) and only if there is a '!' in the cell on its right side. The '#' instruction was introduced to make Argh! programs executable by puting "#!/path/to/argh" in the first line on systems which know this kind of magic. Anyway '#' is a valid, though undocumented, instruction and the sha-bang (#!) line becomes part of the code/data array, so any Argh!-implementation must understand '#' --------------------------------------------------------------------------- Aargh! -- the extended Argh! Aargh! is similar to Argh! except that the height of the code/data array is unrestricted. That means that the code/data array in Aargh! is still 80 cells wide, but it can consist of an arbitrary number of lines (not just 40 as in Argh!). This extension of Argh! has two main implications: - Aargh! programs can be of any length; the code does not need to fit into 40 lines. - Aargh! programs with self-modifying code can grow without limit in the "down" direction. In contrast to Argh! Aargh! is believed to be Turing-complete.