Functions ​

A function call runs a function with a CALL line. The PARAMETER lines below it give the values the function needs. The RESULT lines name the variables that receive what the function returns. Results you don't list are thrown away.

Built-in functions work everywhere. Library functions need an INCLUDE line for their library first, e.g. INCLUDE c0de/math. Then you call them by their full name, e.g. c0de/math/SIN. If a call fails and has no error label, the error is raised.

Built-in functions ​

Built-in functions work with arrays, hashes and errors and need no INCLUDE.

LEN ​

Counts the characters of a string or the elements of an array or hash.

Parameters and results

• value STRING|ARRAY|HASH: the string, array or hash to count
• result result INTEGER: the number of characters or elements

Example

CALL LEN
    PARAMETER value names ;
    RESULT result count

HAS_KEY ​

Checks if a hash contains a key.

Parameters and results

• hash HASH: the hash to look in
• key STRING: the key to look for
• result result BOOLEAN: true if the key exists

Example

CALL HAS_KEY
    PARAMETER hash stock ;
    PARAMETER key "gold" ;
    RESULT result hasGold

REMOVE ​

Removes one element from an array or a hash.

Use index for an array and key for a hash. The following array elements move down by one. A missing index raises INDEX_OUT_OF_BOUNDS, a missing key raises UNKNOWN_KEY. Leaving out index or key raises INVALID_ARGUMENT.

Parameters and results

• container ARRAY|HASH: the array or hash
• index INTEGER: position of the element to remove (optional, needed for arrays)
• key STRING: key of the element to remove (optional, needed for hashes)
• result result like container: the array or hash without the element

Example

CALL REMOVE
    PARAMETER container list ;
    PARAMETER index 1 ;
    RESULT result list

INSERT ​

Inserts a value into an array.

The following elements move up by one. index must be between 0 and the length of the array, otherwise INDEX_OUT_OF_BOUNDS is raised. Use the length to add the value at the end.

Parameters and results

• array ARRAY: the array
• index INTEGER: the position of the new element
• value the type of the elements: the value to insert
• result result like array: the array with the new element

Example

CALL INSERT
    PARAMETER array list ;
    PARAMETER index 0 ;
    PARAMETER value 42 ;
    RESULT result list

CLEAR ​

Returns an empty array or hash of the same type.

Parameters and results

• container ARRAY|HASH: the array or hash
• result result like container: an empty array or hash

Example

CALL CLEAR
    PARAMETER container stock ;
    RESULT result stock

SWAP ​

Swaps two values.

Both values must have the same type, otherwise TYPE_MISMATCH is raised. To swap two variables, use them as parameters and as result targets.

Parameters and results

• a any type: the first value
• b the type of a: the second value
• result a: the value of b
• result b: the value of a

Example

CALL SWAP
    PARAMETER a left ;
    PARAMETER b right ;
    RESULT a left
    RESULT b right

RAISE ​

Returns your own error to the caller of the function.

The caller raises the error or stores it in the error label of its CALL line. code must be 1000 or higher, otherwise INVALID_ARGUMENT is raised. The error gets the context and line of the CALL statement.

Parameters and results

• code INTEGER: the error code, 1000 or higher
• message STRING: the error message (optional, default empty)

Example

CALL RAISE
    PARAMETER code 1001 ;
    PARAMETER message "too big" ;

Input and output ​

These built-in functions talk to players through displays, laptops, tablets and I/O blocks. They need no INCLUDE. The devices are bound to the program and function, see the handbook Devices. The screen functions come from AmigaBASIC. Rows and columns start at 0.

PRINT ​

Writes a value on the screens and starts a new line.

The text appears on every display, laptop and tablet bound to the program and function. Strings are printed without quotes, BOOLEAN values as TRUE and FALSE. Arrays, hashes and structs are printed as JSON. To print several values on one line, join them with ⊕. Without a bound screen, PRINT does nothing.

Parameters and results

• value any type: the value to print

Example

CALL PRINT
    PARAMETER value "Hello" ;

WRITE ​

Puts a value into the I/O blocks as a variable item.

Each bound I/O block with an uninitialized variable item in its input gets the value. The item moves to the output. It is named after name. Without name, it is named after the variable, like count for PARAMETER value count ;. Otherwise it is named output.

If no bound I/O block has an uninitialized variable item, the cursor waits until a player puts one in. Laptops and tablets don't take part in WRITE.

Parameters and results

• value any type: the value to write
• name STRING: the name of the item (optional)

Example

CALL WRITE
    PARAMETER value count + step ;
    PARAMETER name "total" ;

INPUT ​

Reads a value into a variable.

variable must be the name of one declared variable, without index. A constant or loop variable doesn't work. The function writes into the variable directly. It first looks into the bound I/O blocks for an item with the same name and type, or a literal item of the right type. Otherwise it waits until a player types a line on a bound laptop or tablet.

Parameters and results

• variable variable: the variable that receives the value
• no results

Example

PROGRAM typing
NOOP
NOOP
FUNCTION ask
BEGIN
    VARIABLE count INTEGER
    CALL INPUT
        PARAMETER variable count ;
    CALL PRINT
        PARAMETER value count * 2 ;
END FUNCTION

CLS ​

Clears the screens.

The cursor of the screens moves to row 0, column 0. CLS works on all screens bound to the program and function.

Parameters and results

• no parameters and no results

Example

CALL CLS

LOCATE ​

Moves the cursor of the screens.

The next PRINT writes at this place. A row or column outside the screen moves the cursor to the nearest edge.

Parameters and results

• row INTEGER: the row
• column INTEGER: the column (optional, default 0)

Example

CALL LOCATE
    PARAMETER row 3 ;
    PARAMETER column 5 ;

CSRLIN ​

Returns the row of the cursor.

It answers for the screen of the device bound first. Without a screen, the result is 0.

Parameters and results

• result result INTEGER: the row of the cursor

Example

CALL CSRLIN
    RESULT result row

POS ​

Returns the column of the cursor.

It answers for the screen of the device bound first. Without a screen, the result is 0.

Parameters and results

• result result INTEGER: the column of the cursor

Example

CALL POS
    RESULT result column

COLOR ​

Sets the colors of the text printed from now on.

The colors are the 16 colors of Minecraft text, from 0 (black) to 15 (white). Background 0 is the color of the screen. A number outside 0 to 15 raises INVALID_ARGUMENT.

Every program has a constant for each color: COLOR_BLACK, COLOR_DARK_BLUE, COLOR_DARK_GREEN, COLOR_DARK_AQUA, COLOR_DARK_RED, COLOR_DARK_PURPLE, COLOR_GOLD, COLOR_GRAY, COLOR_DARK_GRAY, COLOR_BLUE, COLOR_GREEN, COLOR_AQUA, COLOR_RED, COLOR_LIGHT_PURPLE, COLOR_YELLOW and COLOR_WHITE.

Parameters and results

• foreground INTEGER: the color of the letters, 0 to 15
• background INTEGER: the color behind the letters, 0 to 15 (optional, default 0)

Example

CALL COLOR
    PARAMETER foreground COLOR_YELLOW ;
    PARAMETER background COLOR_DARK_BLUE ;

INKEY ​

Returns the oldest key a player typed on a laptop or tablet.

Only keys typed while no INPUT waits count. Enter arrives as CHR 13. If no key is waiting, the result is the empty string. INKEY doesn't wait.

Parameters and results

• result result STRING: the key, or the empty string

Example

CALL INKEY
    RESULT result key