Brass Core Plugins

function/macro

Defines a function.

Syntax

.function name([arg1 [, arg2 [, ...]]])
	[statements]
.endfunction

Remarks

The function can contain any code, including mathematical expressions, directives and assembly source.

To return a value from the function, simply assign a label with the name of the function itself.

If you put the macro keyword in front of an argument name the passed argument is substituted into the function via a macro replacement rather than an as an evaluated label.

If you develop a complex function that is frequently used in your source file consider converting it to a function plugin, as they execute significantly faster and have much better control over the compilation process.

Warning

If a return value is not explicitly set, the function returns NaN.

Examples

Binary and hexadecimal formatting echo functions.

/* Output the eight bits of value as 1s or 0s */
.function echobinary(value)
    .for bit is 7 to 0
        .if value & 1 << bit
            .echo 1
        .else
            .echo 0
        .endif
    .loop
.endfunction

/* Output the eight bits of value as 1s or 0s with a % prefix */
.function echobinarybyte(value)
    .echo '%' \ echobinary(value)
.endfunction

/* Output the sixteen bits of value as 1s or 0s with a % prefix */
.function echobinaryword(value)
    .echo '%'
    echobinary(value >> 8)
    echobinary(value)
.endfunction

/* Output the four bits of value as a hex digit */
.function echohexnybble(value)
    .echo choose(1 + (value & %1111),
        '0', '1', '2', '3', '4', '5', '6', '7',
        '8', '9', 'A', 'B', 'C', 'D', 'E', 'F')
.endfunction

/* Output the eight bits of value as two hex digits */
.function echohex(value)
    echohexnybble(value >> 4)
    echohexnybble(value)
.endfunction

/* Output the eight bits of value as two hex digits */
.function echohexbyte(value)
    .echo '$' \ echohex(value)
.endfunction

/* Output the eight bits of value as two hex digits */
.function echohexword(value)
    .echo '$'
    echohex(value >> 8)
    echohex(value)
.endfunction

echobinaryword(1234) ; Outputs %0000010011010010
.echoln

echohexword(%1011111011101111) ; Outputs $BEEF
.echoln

Passing a string via the macro keyword.

.function repeatstring(macro str, repeat)
    .for i = 0, i < repeat, ++i
        .db str
    .loop
.endfunction

repeatstring("Hello", 3)

Passing by reference.

.function increment(macro label)
    ++label
.endfunction

x = 1
.echoln "x=", x

increment(x)
.echoln "x=", x

A recursive function that calculates n!

#function f(n)
    .if n == 0
        f = 1
    .else
        f = n * f(n - 1)
    .endif
#endfunction

.echoln f(30) ; Outputs 2.65252859812191E+32.

Distance function using the Pythagorean theorem.

.function distance(x,y)
    distance = sqrt(x * x + y * y)
.endfunction

.echoln distance(3, 4) ; Outputs 5.

Z80 TI calculator bcall() implementation.

/* Enumeration for different calculator models */
#enum Model
    TI8X, ; TI-83 Plus
    TI83  ; TI-83

/* Set to TI8X or TI83 */
Model = Model.TI83

/* Use bcall() to invoke ROM calls */
#function bcall(label)
    .if Model == Model.TI8X
        rst 28h
        .dw label
    .else
        call label
    .endif
#endfunction