KOD Statements and Expressions

From Meridian 59 - Open Source Wiki
Jump to: navigation, search

Overview

Blakod statements correspond roughly to similar statements in C. The main differences are due to Blakod’s dynamic type scheme, and message handler calls.

Values in Blakod are 32 bits long; 4 of these bits act as a tag that determine the value’s type. One bit is also used for sign, leaving 27 bits available for data. Thus, the maximum expressible number in Blakod is 134,217,727 and care must be taken to ensure calculations in Blakod do not exceed this amount. Blakod can directly express values of type integer, resource, class, message handler, and nil. There is no non-integer numerical type. The interpreter uses other tag values for runtime types such as objects and list cells. Type checking is done at runtime; thus, expressions with type errors will compile but may cause runtime errors.

The special value nil is denoted by a dollar sign ($). Nil is assigned to message handler parameters that are not explicitly assigned a value, and it is also used to mark the end of a list. Nil can be assigned to variables, returned from message handlers, or tested for equality; it is an error to perform any other operation on nil.

The special value self contains the identifier of the object whose message handler is being executed. Self is implemented as a property of every object.

Blakod programs are made up of assignment statements, conditional clauses, loops, calls, and return statements. Comments are introduced by the percent character (%) and extend to the end of the line.

Assignments take the form lvalue = expression, where lvalue is the name of a property or a local variable. The right hand side is evaulated, and the result is assigned to the left hand side.

Expressions consist of identifiers, constants, and message handler calls combined with standard operators. Blakod contains the following operators: addition, subtraction, multiplication, division, pre and post increment/decrement, unary minus, modulo, logical and bitwise AND, OR, and NOT, and the standard relational operators (equal, less than, etc.). A boolean expression evaluates to 0 if it is false, or nonzero if it is true. The logical AND and OR operators “short-circuit;” i.e. they only evaluate their second arguments if necessary. The following table shows the precedence of Blakod operators in descending order.

Operators

++ -- − (unary minus) NOT ∼
∗ / MOD
+ −
< > <= >= = <>
&
AND
OR

if/elseif/else

The if statement performs conditional execution. Its syntax is

if test { then-clause } or

if test { then-clause } else { else-clause }

if test { then-clause } else if { else-clause } else { else-clause }

The braces are required in all cases.

while

The basic looping construct in Blakod is the while loop. A while statement has the syntax

while loop-test { loop-body }.

The loop body is evaluated until the loop test becomes false (equal to zero).

do/while

Similar syntax to a C do/while loop. The statements inside the loop are evaluated once, then the condition is checked and if TRUE, execution begins at the top of the loop. Braces are required, as is the semicolon after the while expression.

 do
 {
    % Statements
 } while ++i < 10;

for

TODO.

foreach

The foreach loop construct is for use with lists only. Its syntax is

foreach loop-var in list { loop-body }.

The loop variable takes on each of the first values of the list during evaluation of the body of the loop. The break and continue statements can be used to interrupt loop execution as in C. These statements apply to the innermost enclosing loop; it is an error for these statements to appear outside a loop.

Function calls may appear either as expressions, in which case they evaluate to the return value of the function they call, or as statements, in which case the return value is ignored.

switch/case

TODO.

return and propagate

There are two kinds of return statements, return and propagate. One of these must be the last statement in every message handler. A propagate statement indicates that execution should proceed to the message handler of the same name in the closest superclass in the current class’s hierarchy, if any. A return statement indicates that execution should return immediately to the caller. Return can optionally be followed by an expression whose value is returned to the caller as the value of the calling expression. If no expression appears after the return, the value nil is returned to the caller.

Debug Strings

Debug strings are a special kind of string that is mainly intended for debugging use. They are specified by a text string inside double quotes in an expression (i.e. "text"). The primary use for debug strings is to pass them to the Debug function, described in the next section, for output to a log file. The original codebase allows debug strings to be used as parameters to StringEqual and ParseString for use in text comparisons and in parsing mail destination lists, and debug strings can also be passed to AppendTempString which will add them to the global temp string. The 103 codebase has also added a C function for logging Admin/DM commands, GodLog, which handles debug strings similarly to the Debug function. In addition, the 103 codebase allows SetString to create a string out of a debug string. Debug strings are not handled by the other string functions, so care must be taken not to use debug strings where they are not appropriate.