KonsolScript

KonsolScript is a modern, lightweight embeddable scripting language built for tooling, automation, AI orchestration, and game scripting. Wire LLM APIs into automated pipelines, build AI-powered CLI tools, orchestrate multi-model workflows, or script interactive games — all with a clean, readable syntax that values clarity, portability, and extensibility.

What can you build?

From beginner CLI tools to AI-powered pipelines — KonsolScript's modules and plugins cover a wide range of real-world apps:

• File organizer — rename and sort files by date (File, Path, OS)
• CSV / JSON pipeline — filter, transform, and report on datasets (CSV, Json, List)
• LLM prompt pipeline — batch files through an AI API, collect results to CSV (curl, Json, File)
• AI log triage — scan logs with Regex, send anomalies to an LLM, output a report (Regex, curl, Json)

→ Full project ideas — beginner to advanced

Table of Contents

1. What can you build? — app ideas you can ship with the built-in modules and plugins
2. Kookbook — full project ideas, beginner to advanced
3. Var — types, variables, literals, string interpolation, structs
4. Preprocessor — #define and #include (file and plugin)
5. Operators
6. Control flow — if/else, while, for, foreach, break, continue, switch/case
7. Functions
8. Array — fixed-size typed arrays
9. Class — OOP classes with fields and methods
10. Object — root class, Exception
11. Error handling — try/catch/finally, throw
12. Built-in modules — Konsol, Math, String, File, Time, List, Map, Json, Path, OS, Regex, Date, Hash, CSV
13. Plugin system
14. Available plugins — curl, sqlite, mysql, zip, net

Var

Variables, types, literals, string interpolation, multi-line strings, comments, and struct (UDT) definitions.

→ Full Var reference

Operators

Arithmetic

Use Math:Power(base, exp, out) for exponentiation — ^ is bitwise XOR.

+ on a string and any value concatenates both as strings.

Comparison

Logical

Var:Boolean active = true;
Var:Boolean admin  = false;
if (active == true && admin == false) {
    Konsol:Print("active non-admin");
}
if (!admin) {
    Konsol:Print("not an admin");
}
Var:Boolean allowed = (active == true || admin == true);

Logical operators are most useful inside conditions — see Control flow for if, while, for, switch, and more.

Bitwise

Operands are truncated to 64-bit integer before the operation; the result is stored as Number.

Var:Number flags = 1 | 4;      // 5
Var:Number masked = flags & 3; // 1
Var:Number flipped = 12 ^ 10;  // 6
Var:Number shifted = 1 << 8;   // 256
Var:Boolean isOdd = (n & 1) == 1;

Assignment

Ternary

condition ? valueIfTrue : valueIfFalse

Var:Number x = 10;
Var:String label = x > 0 ? "positive" : "non-positive";
Konsol:Print(label);        // positive

Ternary has the lowest precedence after ||. Nesting is allowed.

Precedence (high to low)

Unary (`-`, `!`, `~`) → `* / %` → `+ -` → `<< >>` → comparison → `&` → `^` → `|` → `&&` → `||` → ternary `?:`

Control flow

See Control flow for if / else if / else, while, for, break, continue, switch / case, and foreach.

Functions

function greet(String name) {
    Konsol:Print("Hello, " + name);
}

function add(Number a, Number b) : Number {
    return a + b;
}

greet("world");
Var:Number result = add(3, 4);

Parameter types can be written as Number x or Var:Number x — both work.

Return type annotation (: Number, : String, : Boolean) is required for non-void functions. Void functions omit the suffix.

Functions can be called in expressions:

Var:Number n = add(1, 2) * 10;

Recursion is supported. Each call gets its own local scope; locals are erased after the call.

Entry point

If the script defines a main function, it is called automatically. Global variable declarations are executed first to initialise globals.

Var:Number count = 0;   // initialised before main() runs

function main() {
    Konsol:Print(count);
}

If there is no main, all top-level statements execute in order.

Array

Fixed-size typed arrays. Size is set at declaration and does not change.

→ Full Array reference

Class

Full OOP with fields and methods. Every user-defined class implicitly extends Object.

→ Full Class reference

Object

Object is the implicit root of every user-defined class, providing getType(), toString(), and isInstanceOf(). Exception extends Object and is used in try / catch.

→ Full Object reference

Error handling

try {
    throw "something went wrong";
} catch (String e) {
    Konsol:Print("Caught: " + e);
} finally {
    Konsol:Print("always runs");
}

• throw accepts any expression; the string value becomes the exception message.
• The catch parameter (String e) is optional — bare catch { } works too.
• finally is optional.
• Nested try/catch is supported; exceptions propagate outward until caught.
• An uncaught exception at the top level prints an error and exits with a non-zero code.

Error output format

KonsolScript Error (line 5): undefined variable 'total'
  5 | Konsol:Print(total);
    |              ^^^^^

Uncaught throw exceptions show the same context plus a full stack trace:

Uncaught exception (line 12): something went wrong
  12 | throw "something went wrong";

Stack trace:
  at inner (called from line 8)
  at outer (called from line 3)
  at main

Calling a method on a class that was never registered raises a clear error:

Runtime error at line 3: unknown class 'Sample' — missing #include?

Built-in modules

All stdlib calls use the Module:Method(args) syntax. Methods that return a value follow the ByRef convention: pre-declare a receiver variable and pass it as the last argument.

Var:Number h;
Time:GetHour(h);
Konsol:Print(h);    // current hour

Plugin system

Plugins are shared libraries that extend KonsolScript with new modules — no recompile of minks needed.

→ Plugin system guide

Available plugins

Install with minks install <name>.

Notes and known limits

• Division by zero throws MathException — catch with catch (MathException e).
• Arrays are fixed-size; out-of-bounds access throws ArrayException — catch with catch (ArrayException e). e.code holds the attempted index.
• #include "file.ks" is fully supported with transitive includes and include-guard deduplication. See Var — Preprocessor.
• Variables declared inside main() are properly scoped and cleaned up after main returns.
• Math:Random uses srand/rand; not cryptographically secure. Use Math:Seed(n) for reproducible sequences.
• String:Mid uses 1-based start index (like BASIC), not 0-based.