-
Notifications
You must be signed in to change notification settings - Fork 1
Tutorial
Grok is a relatively simple language. The commands are based off of the Vim editor; though they are not one-to-one matches, the goal is that those who know Vim can easily pick up on the commands in Grok.
A Grok program is laid out in the wordbox, which extends infinitely in all directions. The instruction pointer, or IP, moves through the wordbox, executing any instructions it encounters. The IP starts at coordinates (0,0), in the top-left of the program, and starts off moving to the right. The IP's direction can be changed, and if it goes off the edge of the wordbox, it wraps around to the other side.
The movement commands are h j k l. These correspond to left, down, up, and right, respectively. When the IP executes one of these commands, it will start moving in that direction, continuing until its direction is changed again or the program is terminated with the q command.
Grok is stack-based, so most commands do something to the stack, either writing to it or reading from it. The stack is usually referred to as the Document. Grok also has several commands for manipulating the register, which can be used to store a single value for later use or to store a value that you want constant access to. If a value is pushed to the register when a value is already stored there, the old value will be discarded.
As a general rule, the capitalized form of a command indicates register manipulation. For example, x discards the top value on the Document, whereas X discards the value in the register.
To push characters and numbers more easily, Grok has an insert mode and a register insert mode (regin mode). Insert mode and regin mode are similar, but regin mode acts on the register instead of the document.
The command to enter insert mode is i. While in insert mode, any characters encountered will be pushed to the Document as their corresponding ASCII values. The program exits insert mode when the escape character ( ` ) is encountered. Characters are held until the escape character is encountered. They are then pushed in reverse order so that they can be easily outputted in the correct order. For example, iabcd` will push d, c, b, a to the stack, so that the first outputted character is a.
Alternatively, if the insert contains only numbers, a single integer of arbitrary length can be pushed. For example, i123` will push the number 123 to the stack. However, if there are both characters and numbers, then the rules for characters apply. For example, i12ab` will push b, a, 2, 1 to the stack, so that the first outputted character is 1.
Regin mode is similar to insert mode, but with some key differences. The command to enter regin mode is I. Since it acts on the register, it can only push a single value. This can be either a single character, or a single integer of arbitrary length. Because it can only push a single value, regin mode will auto-escape. After a character or number has been pushed, the next character will be executed as a command. For example, Iaq will push the ASCII value of a to the register, then q terminates the program. Similarly, I123q will push the number 123 to the register, then q terminates the program.
Grok has several commands for input and output. The command to take input from the user is :. Input works very similarly to insert mode. If the input is entirely numeric, it will be interpreted as a single integer of arbitrary length. If the input contains characters, all characters and numbers will be pushed in reverse order as their corresponding ASCII values.
Output comes in several different forms. The w command pops a value from the Document and outputs it as a character. The z command pops a value from the Document and outputs it as a number. Since characters are stored as ASCII values, the character a could be outputted as a character or a number: w -> a or z -> 97. The capitalized forms of these commands, W and Z, will output a value from the register instead.
The following will cause errors in Grok:
- Attempting to divide by 0.
- Attempting to execute an invalid instruction.
- Overflows if the implementation does not support arbitrary-precision integers.
Regardless of the error, the error message displayed will be "You don't grok Grok." The command prompt argument -e, or --show-errors, will show the true error message instead.