Grobots - Documentation - Language

Grobots are programmed in a simple stack-based language derived from Forth. This imitates RoboWar, but the language itself is much closer to Forth. These stack-based languages are good for this sort of application because they are very easy to implement, and easier to learn and use than other similarly low-level languages.

The Grobots language doesn't have a name yet; I will call it Grobocode here for lack of a better name. If you are used to RoboTalk, you will find it pleasantly powerful. If you are used to Forth, you will find it annoyingly underpowered. If you don't know any stack-based languages, you will just find it weird.

Introduction

Like all Forth dialects, keeps intermediate results of calculations on a stack: operands are pushed onto the stack, and operators take their arguments from the stack. Expressions are written in postfix order - the operator comes after all its arguments. This may be unfamiliar, but fortunately it doesn't take long to get used to. What in a conventional language would be:

gamma = 1 / sqrt(1 - (v / c)^2)

1 v c / square - sqrt reciprocal gamma!

Here's how it works. Start with an empty stack, and execute the first instruction, 1, which pushes a value on the stack.

stack: 1
  Then v, which pushes the value of that variable:
stack: 1 201285
  Then c:
stack: 1 201285 299780
  / takes the top two arguments and leaves their quotient:
stack: 1 0.6714
  square takes one argument
stack: 1 0.45
  -
stack: 0.55
  sqrt
stack: 0.7416
  reciprocal
stack: 1.35
  gamma! stores the value into the variable of that name.
(empty stack)

Try clicking on a robot and opening the Debugger window. Then pause the simulation and give the Step Brain command to slowly advance the brain. Watch the stack change.

There are instructions to operate on the stack, so you can do fancier things like using a result more than once, or shuffling things to be in the right order:

fibonacci: ;n -- f_n
  dup 1 <= if drop 1 return then
  dup 1 - fibonacci swap 2 - fibonacci +
return

See if you can understand how that works. (You'll need to look up a lot of the operators, and this may be confusing to trace since it's recursive.) n -- f_n is a stack diagram, saying the newly defined fibonacci operator takes one argument (n) and returns one result (f_n).

The most confusing errors are stack underflow and overflow. Underflow means means you tried to remove more values from the stack than were actually there. For example, 2 + will probably underflow, because + needs two arguments. Overflow means you kept leaving values on the stack, so they piled higher and higher until the interpreter gave up.

Model details

Grobocode runs on a two-stack machine, like traditional Forth. There is a return stack, which is only used for return addresses, and a data stack, used for arguments and return values of operators.

The only data type is a 32-bit fixed-point number, with 12 bits of fraction (and 1 of sign and 19 of integer). The range is about +/- 524,288, and the precision 1/4096 (.00024). Integer values may be used as addresses.

Syntax

Grobocode syntax is a sequence of words separated by white space. There are several kinds of words; suffixes are sometimes used to indicate which kind. Each word (except compile-time words and label declarations) compiles to one instruction.

Semicolon makes a comment to the end of the line. This works everywhere, not just in code.

Variables and constants are defined somewhat clumsily by leaving the language and using reader tags. #var name initial-value defines a variable, #vector name initial-x initial-y defines a vector variable, and #const name value defines a constant.

Primitive Operators

Hardware access words are not included here, but are listed on the hardware page.

Compile-Time Words

Some words execute at compile time, for convenience in writing common control structures. There are conditionals and loops so far.