KAL v2 language About 2 min read

KAL syntax & structure

The anatomy of a KAL v2 program: version header, AUTOMATION block, CONFIG fields, declarations, constants and functions.

Program skeleton#

kal

KAL VERSION 2.0;
AUTOMATION skeleton {

    CONFIG {
        target: CHANNEL [
            label: "Target channel",
            description: "Where messages are sent",
            required: true,
            section: "Channels & Roles"
        ];
    }

    WHEN COMMAND ping {
        REPLY "Pong from " + guild.name + "!";
    }
}

Piece	Rule
`KAL VERSION 2.0;`	Mandatory, exactly on line 1
`AUTOMATION name { … }`	One block wraps everything; the name identifies the script
`CONFIG { … }`	Optional; one per program; server-specific values arrive as `config.<field>`
Triggers	Any mix of `WHEN` blocks and one or more `SCHEDULE` blocks
Statements	End with `;`; blocks are `{ … }`

CONFIG fields#

kal (fragment)

CONFIG {
    log_channel: CHANNEL [
        label: "Log channel",
        description: "Where warnings are posted",
        section: "Channels & Roles",
        required: true
    ];
    threshold: NUMBER [
        label: "Warning threshold",
        description: "Warnings before action",
        default: 3
    ];
    strict: BOOLEAN [
        label: "Strict mode",
        description: "Escalate immediately",
        default: false
    ];
}

Field types: STRING, NUMBER, BOOLEAN, CHANNEL, ROLE. Metadata keys are label, description, section, required, default. There are no min/max keys — anything unknown is ignored. Fields appear as a form on the script's dashboard configuration page; values arrive in the config context variable.

Variables and constants#

kal

KAL VERSION 2.0;
AUTOMATION variables_demo {

    WHEN COMMAND stats {
        DECLARE count AS NUMBER = 10;
        DECLARE label AS STRING = "points";
        DECLARE active AS BOOLEAN = true;

        SET count += 5;
        SET count -= 3;
        SET count *= 2;
        SET count /= 4;
        SET count %= 4;

        REPLY label + ": " + ("" + count);
    }
}

DECLARE name [AS TYPE] [= expression]; — untyped declarations infer their type; assignment forms =, +=, -=, *= , /=, %= all exist.
SET reassigns (also into obj.prop and arr[i] targets).
Reading a variable that was never declared is a compile error (S002_UNRESOLVED_IDENTIFIER), not a runtime null.

Constants#

kal

KAL VERSION 2.0;
AUTOMATION tax_demo {

    CONSTANT TAX_RATE = 1.08;

    WHEN COMMAND quote (price AS NUMBER) {
        REPLY "With tax: " + ("" + (price * TAX_RATE));
    }
}

The keyword is CONSTANT — not CONST. Constants are declared at the top level and can never be reassigned.

Functions#

kal

KAL VERSION 2.0;
AUTOMATION functions_demo {

    FUNCTION add_tax(amount AS NUMBER) AS NUMBER {
        RETURN amount * 1.08;
    }

    FUNCTION greet(name AS STRING = "friend") AS STRING {
        RETURN "Hi " + name;
    }

    WHEN COMMAND quote (price AS NUMBER) {
        REPLY greet("Sam") + " — with tax: " + ("" + add_tax(price));
    }
}

Functions declare parameter types, may give parameters defaults, may declare a return type with AS, and RETURN a value. Calls are ordinary expressions: add_tax(price) can appear anywhere a value can. Call depth is capped at 64.

Naming rules#

Names are letters, digits, _ and -; identifiers are case-insensitive keywords but case-sensitive names.
Some spellings are reserved in every position and cannot be variable or command names — for example now, menu, add and rate. Prefer descriptive names like ts, chooser or append_item. If an unexpected "Expected identifier" error appears on a name that looks fine, it is one of the reserved spellings — rename it.