CAOS language spec

This describes the known CAOS language as used in the Creatures Evolution Engine.

Basic token types

These are the types of tokens which can be present in CAOS source files.

• integer - any signed 32-bit integer, literals are capped at the limits, not overflowed
  • Literals can be in binary, eg %010101
  • Literals can be characters, eg 'A' or '$'
    • Don't think you can have a ' as a char - escaping doesn't work
• float - any float (?)
• string - any string, enclosed in double-quotes, \", \\ and \n are valid (more?)
• bytestring - a bunch of bytes enclosed in square brackets, eg [1 2 15 255]
  • You can use any integer as the values (so binary/characters are valid)
• function - four-character identifier representing a CAOS function
• label - as used by GSUB, GOTO and SUBR

Additional parameter types

These are types which aren't in the above list but can be used as parameters or return values.

• anything - like it says, any type.
• decimal - either an integer or a float
  • Note that CAOS will cast integers to floats and vice versa when passing parameters. Casting a float to an integer rounds.
  • So decimal is only used when type needs preserving, eg for OUTV
• variable - a variable (ie, the result of VAxx/OVxx/etc)
• agent - an agent.

Languageness

Tokens are normally separated by whitespace of some kind. Newlines are just treated as normal whitespace.

• Commands can span several lines
• There can be several on a line.

However, there is no need for whitespace directly after a string, bytestring or decimal.

• This may be a bug in CEE. It's present in openc2e too for compatibility reasons.

CAOS source files are made up of CAOS commands (functions without a return value), one after another.

• eg: 'OUTV 1 OUTV %01011 OUTS "hello"'

Obviously you can use functions too.

• eg: 'SETV VA00 1 TARG PNTR ADDV VA00 UNID OUTV VA00'
  • Note it's impossible to work out when functions/commands start/end if you don't know their details
  • This is why it's good for coders to keep one-command-per-line, although this isn't helpful *enough*

Conditions

Conditions compare variables/literals. For instance, 'VA00 > 4'.

Condition operators: <> = >= > <= <

Text equivalents (can be used interchangably): NE EQ GE GT LE LT

• So 'VA00 GT 4' is equivalent to the above example.

You can join conditions together with 'AND' or 'OR'.

• eg: 'VA00 > 4 OR VA01 EQ 2'.

They're evaluated simply from left to right.

• 'a OR b AND c' means '(a OR b) AND c', not 'a OR (b AND c)'.
  • You're stuck with this, brackets aren't allowed.
• This means you can step along one-at-a-time and just combine with the last result based on whether it was joined by an AND or OR.
• Conditions do not short-circuit

When comparing integer and float, the integer is cast to float first (3.6 eq 4 is not true, but 4.0 eq 4 is).

Strings can be compared too.

• "hi" = "bye" is false
• "a" < "b" is true, because in ASCII a is a smaller number than b
• "bye" > "byaaa" is true. This is undocumented behaviour, but is likely the case because e is greater than a
• "bye" > "by" is true. This is undocumented behaviour, but is likely the case because e is greater than a missing value

Used with: DOIF, ELIF, UNTL.