Argh! Tutorial Part 1

In 2004 I created a little esoteric programming language called Argh!, which, more than ten years later, is still some fun to a small bunch of people. One noteworthy phenomenon in the history of Argh! is, that there are seemingly more people creating new implementations of interpreters, compilers and tools for Argh! than people writing actual Argh! programs. So I decided to start this series of Argh! tutorials, in the vain hope of showing the beauty of Argh! programming to the world and maybe lure you, my dear reader, into writing some cool Argh! code your self. As you might have guessed by now: I’m always happy to hear about new Argh! programs and open to include or at least mention them in the official Argh! repository.

The Language

Argh! follows some simple design rules to ensure its esoteric beauty:

• Easy to read and write: Argh! programs must not contain anything but plain printable 7bit ASCII characters. All Argh! instructions are plain single roman alphabetic characters, no confusing, hard to type special characters. Further more Argh! programs may at most contain 80 characters per line and may not be longer than 40 lines (at least in vanilla Argh!, see below).

• Easy to learn: Argh! consists only of few, intuitive instructions, and many unnecessary bloating features are omitted. Notably omitted are: advanced math functions like multiplication and division, advance text formatting functions like textual representation of numerical values, interpreted character sequences to create non printing characters (like ‘\n’) and arbitrary numerical constants. All these are easily implemented ad hoc anyway.

• Easy to debug: Many compilers and interpreters error messages tend to be hard to understand and are sometimes outright misleading. That’s why Argh! specifies one unified error message that must be used by any implementation in any error condition. The error message is “Argh!”, which is always correct and very user friendly as it matches the feelings of any hacker facing a bug.

Argh! provides a combined code/data array of the size 80×40 characters in which the Argh! code is loaded at start up. Argh! programs provide a two dimensional program flow and executed directly in the code/data array. Each cell in the code/data array can be interpreted as code or as data and its completely write able to the program. In addition Argh! provides an classic stack for data storage.

In the end of this overview it should be mentioned that Argh! nowadays is actually a whole family of language dialects, besides good old vanilla Argh! there is the extended Aargh! which is just like Argh! but with the limitation in the height of the code/data array removed, which also removes the limitation on the number of lines for an Aargh! program. Then there is Arrgh!, which introduces concurrency features, and last but not least the combination of both extensions: Aarrgh!

For the complete and authoritative specification of Argh!, please read the official Argh-Spec.txt.

Example: Hello World

Enough theory for now, nothing creates the illusion of understanding like an example, so lets have a look at the obligatory Hello World in Argh! to illustrate some on the basic concepts introduced above:

lpppppppppppsrfj
 Hello World*  j
             qPh

Execution of an Argh! program always starts at the top left, so the first instruction is l. l is one of Argh!’s four direction instructions h,j,k and l. It does nothing but to specify in which direction code execution is continued. The actual direction each instruction stands for should be obvious to any user of vi (or maybe player of nethack): h goes left, j down, k up and l right. As there is no default execution direction, every Argh! program has to start with an execution direction setting instruction.

So our first instruction l tells the Argh! interpreter to continue execution one instruction to the right.

The next instruction is p. p stands for print and instructs the interpreter to print out the character below the current instruction, which in the case at hand is ‘H’, so the character ‘H’ is send to standard out. As p does not influence the direction of code execution it stays as before, which is still right so the next instruction to execute is again p, this time printing the character ‘e’ to stdout.

This pattern repeats until the last p has send ‘d’ to stdout, now the complete string “Hello World” was printed on standard out and one might think the task is solved, but no, the most interesting part is still ahead:

At the end of the string the classical hello world example does output a new line character, and of cause we want to do the same. Now, as mentioned above, Argh! code can neither contain non printable characters (like new line would be)¹ nor does it support special character sequences like ‘\n’ to create them. So how do we create a new line character? The answer is simple: we calculate it! Just like in C characters in Argh! are nothing more than integer values which can be used as such for arithmetic operations. The integer values of characters are there ASCII code values, so what we need is to generate the decimal value 10 for the new line character and then print it out.

Lets see how its done in our example: the next instruction is s, which stands for store it puts the value in the cell below on the top of the stack. The character in the cell below is ‘*’ which has the ASCII value 42. So now the value 42 is on the top of the stack. Just as with p the execution direction is kept, so the next instruction is r. r stand for reduce and subtracts the character in the cell below (more precisely the ASCII value of the character) from the top of the stack. The character below is ‘ ’ (ASCII space) and its value is 32, so the top of the stack is now 42 - 32 = 10 (the result replaces the old value on the top of the stack).

We can not print out values from the stack directly, so we have to place the generated new line character (value 10) in the code/data array, this is done by the next instruction: f stands for fetch and takes the top value from the stack (it is removed from the stack) and puts it in the cell below the instruction.

The next instructions are direction instruction again: j instructs the interpreter to step downwards now, so does the next j and finally the h sets the direction to left. As you see the direction instructions can be used to “walk” through the code/data array. Now the next instruction is P (remember, execution of the code goes from right to left now, as the current execution direction was set by h). P is just like p, the only difference is, that the character to print is taken from above the instruction not from below as p does. The is true to all instructions operating on the code/data array: lower case instructions operate on cells below them, while their upper case variants operate on the cells above.

So the P instruction finally prints out our new line character, as that is what the f (two rows up) placed in the cell above the P. Now we reach the final instruction q which stands for quit and lets our program terminate normally.

And so ends our little Hello World example and with it this first Argh! tutorial. In the next part I will talk about conditionals and jumps.

Keep on hacking!