KonsolScript

KonsolScript is modern lightweight embeddable scripting language optimized for tooling, games, automation, and beginner accessibility designed for someone who values clarity, portability, and extensibility.

Table of Contents

1. Language basics
2. Operators
3. Control flow — if/else, while, for, foreach, break, continue, switch/case
4. Functions
5. Arrays
6. Structs (UDTs)
7. Classes
8. Error handling
9. Built-in modules — Konsol, Math, String, File, Time, List, Map, Json, Path, OS, Regex, Date, Hash, CSV
10. Adding a module
11. Plugin system
12. Available plugins — curl, sqlite, mysql, zip
13. Embedding API

Language basics

Types

Three primitive types, all stored in a Value variant:

Variable declaration

Var:Number x;
Var:Number y = 42;
Var:String name = "hello";
Var:Boolean flag = true;
Var:Number a = 1, b = 2, c = 3;

Variables can be assigned without re-declaring:

x = x + 1;
name = "world";

Literals

42            // integer
3.14          // float
0xFF          // hex (stored as Number)
"hello\n"     // string — supports \n \t \" \\
"Hi ${name}!" // interpolated string — ${expr} is evaluated at runtime
true false    // booleans

String interpolation

Embed any expression inside ${ } within a double-quoted string:

Var:String name = "world";
Konsol:Print("Hello ${name}!");         // Hello world!

Var:Number a = 3;
Var:Number b = 4;
Konsol:Print("${a} + ${b} = ${a + b}"); // 3 + 4 = 7

Var:String msg = "Result: ${a * b}";
Konsol:Print(msg);                      // Result: 12

• A bare $ not followed by { is treated as a literal character ("$5.00" stays $5.00).
• Escape sequences (\n, \t, \", \\) work inside interpolated strings.
• The whole interpolated string evaluates as a String type.

Guru-level: full expressions inside ${}

${} accepts any expression the runtime can evaluate — not just variable names. Arithmetic, ternary, function calls, and even nested interpolation all work. — ${} is a full expression slot, not merely a variable substitution.

Konsol:Print("area     = ${width * height}");
Konsol:Print("midpoint = ${(a + b) / 2}");
Konsol:Print("sign     = ${x > 0 ? "pos" : x < 0 ? "neg" : "zero"}");
Konsol:Print("doubled  = ${timesTwo(n)}");

Multi-line strings (triple-quote)

Use """...""" for strings that span multiple lines or contain double-quote characters:

Var:String msg = """Hello,
World!
This is line three.""";
Konsol:Print(msg);

// Double-quotes inside are fine
Var:String code = """Konsol:Print("hi");""";

// ${} interpolation works inside triple-quoted strings too
Var:String name = "Alice";
Var:String greeting = """Dear ${name},
  Welcome!""";
Konsol:Print(greeting);

• Content is literal — newlines, tabs, and single " are preserved as-is.
• ${expr} interpolation works the same as in regular strings.
• Closing """ must be exactly three unescaped double-quotes.

When the expression inside ${} gets complex, factor it into a variable first:

// discouraged — legal but harder to debug
Konsol:Print("${x > 0 ? "pos" : x < 0 ? "neg" : "zero"}");

// preferred
Var:String sign = x > 0 ? "pos" : x < 0 ? "neg" : "zero";
Konsol:Print("sign: ${sign}");

Comments

// single-line comment

/* multi-line
   comment */

Preprocessor

#define

Plain word-boundary text substitution before tokenisation:

#define MAX 100
#define PI 3.14159

Var:Number limit = MAX;

#include

Two forms:

KonsolScript file includes

#include "lib/utils.ks"
#include "helpers.ks"

• Paths are resolved relative to the including file's directory, then relative to the script root.
• Transitive: included files can #include other files.
• Include guard: each file is only tokenised once regardless of how many times it is included. Re-including a file is a no-op, so mutual or repeated includes are safe.
• All top-level statements in the included file run during the symbol-build pass. Functions, classes, and UDTs defined in included files are available everywhere in the script.

Plugin includes

#include "kse_sample"     // loads kse_sample.dll / .so from plugin search paths

Plugin search order for #include "name":

1. <directory of including file>/plugins/name.dll
2. <main script root>/plugins/name.dll
3. Dirs added via engine.addPluginPath() or the --plugin-path CLI flag
4. MINKS_PLUGIN_PATH env var (colon-separated on Linux/macOS; semicolon on Windows)
5. ~/.minks/plugins/ (Linux/macOS) — %APPDATA%\minks\plugins\ (Windows)
6. ./plugins/

If the library is not found, minks falls back to searching for name.ks. If that also fails, a runtime error is raised. Each plugin name is include-guarded — including the same name twice is a no-op.

// lib/math_utils.ks
function clamp(Number val, Number lo, Number hi):Number {
    if (val < lo) { return lo; }
    if (val > hi) { return hi; }
    return val;
}

// main.ks
#include "lib/math_utils.ks"

Var:Number x = clamp(200, 0, 100);
Konsol:Print(x);   // 100

Function parameters may only be written with a type prefix:

function add2(Number a, Number b):Number  { return a + b; }   // typed

Entry point

If the script defines a main function, it is called automatically. Global variable declarations are still 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.

Operators

Arithmetic

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

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

Comparison

Logical

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  (1100 ^ 1010 = 0110)
Var:Number toggled = 5 ^ 5;    // 0  (x ^ x = 0)
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

// works inside ${} interpolation too
Konsol:Print("sign: ${x > 0 ? "pos" : "neg"}");

Ternary has the lowest precedence after ||. Nesting is allowed — use parentheses for clarity.

Precedence (high to low)

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

Control flow

if / else if / else

if (x > 10) {
    Konsol:Print("big");
} else if (x > 5) {
    Konsol:Print("medium");
} else {
    Konsol:Print("small");
}

while

Var:Number i = 0;
while (i < 5) {
    Konsol:Print(i);
    i++;
}

for

for (Number i = 0; i < 10; i++) {
    Konsol:Print(i);
}

The init clause can use Number declaration or a plain assignment. The increment supports ++, --, and = expr.

break

while (true) {
    if (done == true) { break; }
}

continue

Skips the rest of the current iteration and jumps to the next. In a for loop the increment still runs.

for (Number i = 0; i < 10; i++) {
    if (i % 2 == 0) { continue; }
    Konsol:Print(i);   // prints odd numbers only
}

switch / case / default

Evaluates an expression and executes the matching case block. Works with numbers and strings. Supports fall-through (omit break) and a default branch.

switch (expr) {
    case value1:
        // statements
        break;
    case value2:
        // statements
        break;
    default:
        // statements
}

break exits the switch. continue inside a switch propagates to the enclosing loop. Nested switches are supported.

Var:Number x = 2;
switch (x) {
    case 1:
        Konsol:Print("one");
        break;
    case 2:
        Konsol:Print("two");
        break;
    default:
        Konsol:Print("other");
}

Var:String day = "Wed";
switch (day) {
    case "Mon": Konsol:Print("Monday"); break;
    case "Wed": Konsol:Print("Wednesday"); break;
    default:    Konsol:Print("another day");
}

Fall-through example (no break on case 1):

switch (n) {
    case 1:
        Konsol:Print("one or two");
    case 2:
        Konsol:Print("two");
        break;
}

foreach

Iterate over a List, Array, Map (yields keys, sorted), or String (yields characters) without a manual index counter.

foreach (varName in collectionName) {
    // body — varName holds the current element / key
}

break and continue work the same as in for / while.

List:String fruits;
List:Push("apple", fruits);
List:Push("banana", fruits);
List:Push("cherry", fruits);

foreach (String item in fruits) {
    Konsol:Print(item);         // apple  banana  cherry
}

// Map — keys yielded in sorted order
Map:New cfg;
Map:Set("host", "localhost", cfg);
Map:Set("port", "8080", cfg);

Var:String val;
foreach (key in cfg) {
    Map:Get(cfg, key, val);
    Konsol:Print(key + " = " + val);
}

// String — one character per iteration
Var:String word = "hi";
foreach (ch in word) {
    Konsol:Print(ch);           // h  i
}

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.

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.

Arrays

Fixed-size typed arrays. Size is set at declaration and does not change. Use List for dynamic resizable collections.

Declaration

Array:New name[size]:Type;

size can be a literal or a variable expression. Type is Number, String, or Boolean.

Array:New scores[5]:Number;
Array:New names[3]:String;
Array:New flags[4]:Boolean;

Var:Number n = 10;
Array:New buf[n]:Number;    // size from variable

Elements are zero-initialised: 0, "", or false.

Access

scores[0] = 95;
scores[1] = 87;
Konsol:Print(scores[0]);    // 95

Index reads out of bounds return 0 / "" / false. Index writes out of bounds are silently ignored.

Iterating

for (Number i = 0; i < 5; i++) {
    Konsol:Print(scores[i]);
}

foreach (s in scores) {
    Konsol:Print(s);
}

Note on performance

Array and List currently share the same internal Value storage, so there is no runtime performance difference between them. Array is kept as a distinct type to leave room for a typed contiguous-storage optimisation in a future release.

Structs (UDTs)

Simple data-only record types. No methods.

Var:Create(Point, Number x, Number y);

Var:Point p;
p.x = 10;
p.y = 20;
Konsol:Print(p.x + p.y);

Var:Create is processed at symbol-build time. Multiple fields separated by commas.

Classes

Full OOP with fields and methods.

Definition

Class:Create(Animal) {
    Var:String name;
    Var:Number age;

    function setName(String n) {
        name = n;
    }

    function speak() {
        Konsol:Print(name + " says hello");
    }

    function getAge() : Number {
        return age;
    }
}

Fields are declared with Var:Type fieldName; inside the body. Methods are declared with function. Inside a method, fields are accessible directly by name.

Instantiation and use

Class:Animal dog;       // single instance via Class:TypeName
Var:Animal cat;         // equivalent shorthand: Var:TypeName
dog.name = "Rex";
dog.age = 3;
dog.setName("Buddy");
dog.speak();

Var:Number a = dog.age;

Field access for reading uses instance.field. For writing, assign directly: instance.field = value.

Method calls use instance.method(args). Modified fields are written back to the instance after each method call.

Collections of class instances

List:Animal  pack;   // list of Animal instances
Array:New herd[10]:Animal;   // array of Animal instances

Multiple instances

Each Class:TypeName varName (or Var:TypeName varName) creates an independent instance with its own copy of the fields.

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

Runtime errors and uncaught exceptions print to stderr with the line number, the offending source line, and a caret (^) pointing to the exact token:

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

Uncaught throw exceptions show the same context, plus a full stack trace when the exception propagated through one or more function calls:

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

The trace lists frames innermost-first. Each frame names the function and the line in the caller where the call was made.

Calling a method on a class that was never registered — whether a plugin that wasn't loaded or a .ks file that wasn't included — raises a clear error rather than silently doing nothing:

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

Built-in modules

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

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

All stdlib modules follow the ByRef convention — there are no _ret exceptions.

Konsol

Konsol:Input stores a Number if the input looks like one, otherwise a String.

Passing more than one argument to Print, Message, or Log is a syntax error.

Math

All methods are ByRef — pre-declare a receiver variable and pass it as the last argument.

String

All methods are ByRef — pre-declare a receiver variable and pass it as the last argument.

List:String part;
String:Split("a,b,c", ",", part);
Var:Number sz;
List:Size(part, sz);       // 3
Var:String p0; Var:String p1; Var:String p2;
List:Get(part, 0, p0);     // a
List:Get(part, 1, p1);     // b
List:Get(part, 2, p2);     // c

File

File handles are integer IDs you choose (e.g. 1, 2).

File:Open(1, "data.txt", "w");
File:Write(1, "hello\n");
File:Close(1);

Var:Boolean exists;
File:Exists("data.txt", exists);
Konsol:Print(exists);   // true

// Read entire file at once
Var:String content;
File:Open(2, "data.txt", "r");
File:ReadAll(2, content);
File:Close(2);
Konsol:Print(content);  // hello

// Read line by line
Var:Boolean eof;
Var:String line;
File:Open(3, "data.txt", "r");
File:EOF(3, eof);
while (eof == false) {
    File:ReadLine(3, line);
    Konsol:Print(line);
    File:EOF(3, eof);
}
File:Close(3);

Time

Var:Number h;
Var:Number m;
Var:Number s;
Time:GetHour(h);
Time:GetMinute(m);
Time:GetSecond(s);
Konsol:Print("${h}:${m}:${s}");

Var:Number t0;
Var:Number t1;
Time:GetTimer(t0);
// ... work ...
Time:GetTimer(t1);
Konsol:Print("elapsed: ${t1 - t0}s");

List

Dynamic resizable array with a declared element type.

dst and outVar must be pre-declared. Filter/Map clear dst before filling it. Callback functions must use typed parameters and declare a return type (e.g. function fn(Number x) : Boolean).

List:Number scores;
List:Push(10, scores);
List:Push(20, scores);
Var:Number sz;
List:Size(scores, sz);
Konsol:Print(sz);         // 2
Var:Number val;
List:Get(scores, 0, val);
Konsol:Print(val);        // 10

Map

String-keyed dictionary.

Map:New scores;
Map:Set("Alice", 95, scores);
Map:Set("Bob", 82, scores);

Var:Number val;
Map:Get(scores, "Alice", val);
Konsol:Print(val);        // 95

Var:Boolean found;
Map:Has(scores, "Carol", found);
Konsol:Print(found);      // false

Var:Number sz;
Map:Size(scores, sz);
Konsol:Print(sz);         // 2

List:String keys;
Map:Keys(scores, keys);
List:Size(keys, sz);
Konsol:Print(sz);         // 2

Json

Parse, inspect, build, and serialize JSON. Documents are named and held in memory until freed. Paths use dot notation; numeric parts index arrays. Use "" for the root node.

Path examples: "name", "user.age", "items.0", "data.scores.2". Use "" for root.

Var:Number status;
Var:String name;
Var:String typeStr;
Var:Number len;
Var:String out;

// Parse and read
Json:Parse(resp, "{\"status\":200,\"user\":{\"name\":\"Alice\",\"scores\":[95,82]}}");
Json:Get(resp, "status", status);
Konsol:Print(status);                // 200
Json:Get(resp, "user.name", name);
Konsol:Print(name);                  // Alice
Json:Type(resp, "user.scores", typeStr);
Konsol:Print(typeStr);               // array
Json:Length(resp, "user.scores", len);
Konsol:Print(len);                   // 2

// Build and serialize
Json:NewObject cfg;
Json:Set(cfg, "host", "localhost");
Json:Set(cfg, "port", 8080);
Json:Stringify(cfg, "", out);
Konsol:Print(out);                   // {"host":"localhost","port":8080}

// Build array
Json:NewArray tags;
Json:Push(tags, "", "fast");
Json:Push(tags, "", "safe");
Json:Stringify(tags, "", out);
Konsol:Print(out);                   // ["fast","safe"]

Json:Free(resp);
Json:Free(cfg);
Json:Free(tags);

Path

Pure string-based path manipulation plus filesystem queries.

Var:String result;
Path:Join("src", "main.ks", result);
Konsol:Print(result);           // src/main.ks  (or src\main.ks on Windows)

Path:Extension("readme.md", result);
Konsol:Print(result);           // .md

Var:Boolean exists;
Path:Exists("script.ks", exists);
Konsol:Print(exists);           // true

OS

Operating-system services: working directory, directory listing, environment variables, and process control.

// Script arguments: minks script.ks hello world
List:String args;
OS:Args(args);
Var:Number count;
List:Size(args, count);
Konsol:Print(count);            // 2
Var:String first;
List:Get(args, 0, first);
Konsol:Print(first);            // hello

Var:String cwd;
OS:Cwd(cwd);
Konsol:Print(cwd);              // /home/user/project  (or C:\… on Windows)

Var:String greeting;
OS:SetEnv("GREETING", "hi");
OS:GetEnv("GREETING", greeting);
Konsol:Print(greeting);         // hi

Var:Boolean ok;
OS:MkDir("output", ok);

List:String entries;
OS:ListDir(".", entries);
Var:Number sz;
List:Size(entries, sz);
Konsol:Print(sz);               // number of entries in current directory

Regex

Pattern matching and capture groups using ECMAScript regex syntax (wraps std::regex). Patterns are compiled and cached on first use; a bad pattern returns false / "" / empty list rather than throwing.

Var:Boolean found;
Regex:Test("[0-9]+", "abc 42 def", found);
Konsol:Print(found);        // true

Var:String match;
Regex:Find("[a-z]+", "Hello World", match);
Konsol:Print(match);        // ello

Var:String result;
Regex:Replace("\\s+", "hello   world", " ", result);
Konsol:Print(result);       // hello world

List:String groups;
Regex:Groups("(\\w+)@(\\w+)", "user@host", groups);
// groups[0] = "user@host", groups[1] = "user", groups[2] = "host"
Var:String g0; Var:String g1; Var:String g2;
List:Get(groups, 0, g0);
List:Get(groups, 1, g1);
List:Get(groups, 2, g2);
Konsol:Print("${g0} → ${g1} at ${g2}");

Date

Unix-timestamp-based date arithmetic and formatting. All timestamps are Number (seconds since the Unix epoch, as returned by Date:Now).

Supported strftime format specifiers: %Y year · %m month · %d day · %H hour · %M minute · %S second.

Var:Number ts;
Date:Now(ts);

Var:String formatted;
Date:Format(ts, "%Y-%m-%d", formatted);
Konsol:Print(formatted);        // e.g. 2025-08-01

Var:Number year; Var:Number month; Var:Number day;
Date:Year(ts, year);
Date:Month(ts, month);
Date:Day(ts, day);
Konsol:Print("${year}-${month}-${day}");

// Add 7 days
Var:Number nextWeek;
Date:Add(ts, 7, nextWeek);
Date:Format(nextWeek, "%Y-%m-%d", formatted);
Konsol:Print(formatted);

// Days between two timestamps
Var:Number past;
Date:Parse("2025-01-01", "%Y-%m-%d", past);
Var:Number diff;
Date:Diff(past, ts, diff);
Konsol:Print("${diff} days since Jan 1");

Hash

Hashing and Base64 encoding. All methods are ByRef. Implementations are self-contained — no external library required.

Var:String h;
Hash:MD5("hello", h);
Konsol:Print(h);        // 5d41402abc4b2a76b9719d911017c592

Hash:SHA256("hello", h);
Konsol:Print(h);        // 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824

Var:String enc;
Hash:Base64Encode("hello world", enc);
Konsol:Print(enc);      // aGVsbG8gd29ybGQ=

Var:String dec;
Hash:Base64Decode(enc, dec);
Konsol:Print(dec);      // hello world

CSV

Parse, build, and serialize RFC 4180 CSV data. Documents are named and held in memory until freed. Rows and columns are 0-based.

Var:String src = "name,age\nAlice,30\nBob,25";
CSV:Parse(data, src);

Var:Number rows;
CSV:Rows(data, rows);
Konsol:Print(rows);     // 3

Var:String cell;
CSV:Get(data, 1, 0, cell);
Konsol:Print(cell);     // Alice

// Build from scratch
CSV:Set(out, 0, 0, "product");
CSV:Set(out, 0, 1, "price");
CSV:Set(out, 1, 0, "apple");
CSV:Set(out, 1, 1, "1.20");

Var:String csv;
CSV:Stringify(out, csv);
Konsol:Print(csv);

CSV:Free(data);
CSV:Free(out);

Adding a module

Modules are registered as class handlers — the same mechanism the built-in classes use. You do not need to modify the parser.

1. Create kse_mymodule.cpp

#include "kse.hpp"

static size_t mymodule_handler(Engine& e, size_t i) {
    ++i; // skip "MyModule"
    if (e.tokenText(i) != ":") return e.skipOptSemi(i);
    ++i; // skip ":"

    std::string method = e.tokenText(i);
    ++i; // skip method name
    if (e.tokenText(i) == "(") ++i; // skip (

    if (method == "Hello") {
        // read input argument, then outVar (ByRef convention)
        Value v = e.evalExpr(i);
        if (e.tokenText(i) == ",") ++i; // skip comma
        std::string outVar = e.tokenText(i); ++i; // read receiver name
        if (e.tokenText(i) == ")") ++i; // skip )

        std::string msg = "Hello from MyModule: " + toString(v);
        e.setVar(outVar, Value(msg));
        return e.skipOptSemi(i);
    }

    return e.skipOptSemi(i);
}

void register_mymodule(Engine& e) {
    e.registerClass("MyModule", mymodule_handler);
}

2. Register it in kse.cpp

Declare the registrar at the top:

void register_mymodule(Engine&);

Then call it in the Engine constructor:

Engine::Engine() {
    scopedVars_[""];
    register_math(*this);
    // ... existing registrations ...
    register_mymodule(*this);   // add this line
}

3. Add to Makefile

SRCS = kse.cpp kse_konsol.cpp kse_math.cpp kse_string.cpp \
       kse_file.cpp kse_time.cpp kse_class.cpp kse_try.cpp \
       kse_mymodule.cpp

4. Use it in a script

Var:String result;
MyModule:Hello("world", result);
Konsol:Print(result);

Engine API available to handlers

e.tokenText(i)          // text of token at i
e.tokenCmd(i)           // command/type id of token at i
e.tokenLine(i)          // source line number
e.tokenCount()          // total token count

e.evalExpr(i)           // evaluate expression starting at i; advances i past it
e.setVar("name", v)     // set a variable (use the caller's outVar name for return values)
e.getVar("name")        // get a variable's Value
e.hasVar("name")        // check existence

e.skipOptSemi(i)        // call as final return; skips ; if present
e.skipPast("}", i)      // scan forward to given token, return its index

// Value helpers (free functions from kse_types.hpp)
toString(v)             // Value → std::string
toDouble(v)             // Value → double
toBool(v)               // Value → bool
Value("text")           // make a string Value
Value(3.14)             // make a number Value
Value(true)             // make a bool Value

Multiple methods, multiple arguments

if (method == "Add") {
    Value a = e.evalExpr(i);
    if (e.tokenText(i) == ",") ++i;
    Value b = e.evalExpr(i);
    if (e.tokenText(i) == ",") ++i;
    std::string outVar = e.tokenText(i); ++i; // receiver
    if (e.tokenText(i) == ")") ++i;
    e.setVar(outVar, Value(toDouble(a) + toDouble(b)));
    return e.skipOptSemi(i);
}

The pattern: eval each input argument (leaving i at the following delimiter), skip commas between arguments, read the last token as the receiver variable name, skip ), write the result with e.setVar(outVar, ...).

Exposing the module as a script-side class

If you want script code to instantiate your module type like a class (field storage, method dispatch), register it via Class:Create at runtime from a .ks file, or directly manipulate e.classDefs() and e.classInsts() from C++ — the same maps the built-in Class: keyword uses.

Plugin system

Plugins are shared libraries (.dll on Windows, .so on Linux/macOS) that extend KonsolScript with new module-style classes callable with the same MyPlugin:Method(args) syntax as built-in modules. No recompile of minks is needed.

Loading plugins from a script

The recommended way — load plugins directly in the script that uses them:

#include "kse_mysql"     // finds kse_mysql.dll/.so in the plugin search path
#include "kse_audio"

See the #include section for the full search-path order.

Managing installed plugins

minks install <name>          install plugin from current directory
minks remove  <name>          delete it from the user plugin dir
minks list                    list all installed plugins

minks install searches the current working directory for <name>.dll / .so / .dylib, then lib<name>.dll / .so / .dylib. Run it from inside the directory where you built the plugin.

Installed plugins live in ~/.minks/plugins/ (Linux/macOS) or %APPDATA%\minks\plugins\ (Windows) and are available to all scripts without any flags.

cd sample_plugin
minks install kse_sample
minks list
# kse_sample

Adding a search directory (CLI)

minks --plugin-path ./my_libs script.ks

--plugin-path can be repeated. Added dirs are checked before the defaults.

Low-level explicit load (legacy / debug)

minks --plugin ./myplugin.dll script.ks
minks --plugin lib1.dll --plugin lib2.dll script.ks
minks -p ./kse_mysql.so -p ./kse_audio.so game.ks

--plugin (or -p) can be repeated. Libraries are loaded in the order given before the script runs. Prefer #include "name" in scripts over this flag for portability.

Writing a plugin — the PluginClass builder

Include minks_plugin.h (ships with minks). The PluginClass RAII fluent builder handles all token-stream parsing internally; you only write lambdas for each method.

#include "minks_plugin.h"
#include <iostream>

extern "C" void minks_register(Engine& e) {
    PluginClass(e, "MyLib")

        // .byRefMethod — last script arg is the outVar; SDK writes result there.
        // args[] inside the lambda contains only the INPUT arguments.
        .byRefMethod("Greet", [](auto args) -> Value {
            return Value(std::string("Hello, ") + toString(args[0]) + "!");
        })

        // .voidMethod — side-effects only; no receiver variable needed
        .voidMethod("Log", [](auto args) {
            std::cout << toString(args[0]) << "\n";
        })

        .byRefMethod("Add", [](auto args) -> Value {
            return Value(toDouble(args[0]) + toDouble(args[1]));
        });

    // PluginClass destructor fires here, registering "MyLib" with the engine.
}

From KonsolScript:

Var:String greeting;
MyLib:Greet("world", greeting);
Konsol:Print(greeting);         // Hello, world!

MyLib:Log("debug info");        // void — no receiver needed

Var:Number sum;
MyLib:Add(3, 7, sum);
Konsol:Print(sum);              // 10

Builder API

Plugins have no _ret path. Every non-void plugin method must use .byRefMethod — there is no legacy method() builder.

Argument extraction

Inside your lambda, args is std::vector<Value>. Use these free helpers (from kse_types.hpp):

Return values: Value(double), Value(std::string), Value(bool).

Build commands

# Windows
g++ -std=c++17 -shared -I<minks_dir> -o myplugin.dll myplugin.cpp

# Linux / macOS
g++ -std=c++17 -shared -fPIC -I<minks_dir> -o myplugin.so myplugin.cpp

Link additional libraries after myplugin.cpp:

g++ -std=c++17 -shared -fPIC -I../minks -o kse_mysql.so kse_mysql.cpp -lmariadb

<minks_dir> is the directory containing minks_plugin.h, kse.hpp, and kse_types.hpp.

Working example — sample plugin

sample_plugin/kse_sample.cpp exposes a Sample class with six byRefMethod entries and one voidMethod. Build, install, and use:

# from sample_plugin/
make
minks install kse_sample   # searches cwd for kse_sample.dll/.so

# In your .ks script:
#include "kse_sample"

Or for a quick test without installing (explicit load by path):

minks --plugin sample_plugin\kse_sample.dll tests\20_plugin.ks   # Windows
minks --plugin ./sample_plugin/kse_sample.so tests/20_plugin.ks  # Linux

Expected output (abridged):

=== Sample Plugin ===
plugin version: kse_sample 1.0.0
[Sample] Hello, world!
Add(3, 4)      = 7
Multiply(6, 7) = 42
(10+20)*2      = 60
Upper          = HELLO FROM PLUGIN
Repeat(ab, 5)  = ababababab
--- IsPrime ---
2 is prime
3 is prime
...

Plugin typed exceptions

Plugins can declare named exception classes that scripts catch by type — the same try / catch / finally syntax used for built-in exceptions.

A plugin registers its exception type once in minks_register:

registerPluginException(e, "MySQLException");

Then throws it from any method:

throwPluginException("MySQLException", mysql_error(conn), (double)mysql_errno(conn));

The caught instance exposes two fields:

From KonsolScript:

try {
    MySQL:Connect("localhost", "root", "wrongpass", "mydb", db);
} catch (MySQLException e) {
    Konsol:Print("MySQL error ${e.code}: ${e.message}");
} catch (Exception e) {
    Konsol:Print("Unexpected error: ${e.message}");
}

catch (Exception e) is the generic catch-all that matches any typed plugin exception. More specific types (MySQLException, CurlException, etc.) must be named exactly.

IDE false-positive on minks_plugin.h

Editors using clangd may flag 'kse.hpp' file not found or 'minks_plugin.h' file not found inside sample_app/ or sample_plugin/ source files. This is a false positive — clangd does not read those directories' Makefile and therefore does not pick up the -I.. flag. The make build compiles correctly. Add a compile_commands.json or a .clangd config with CompileFlags: Add: [-I..] to suppress it.

Available plugins

Plugins ship as separate builds alongside minks. Install with minks install <name> — the package manager automatically installs any required system library via apt, pacman, brew, or MSYS2 pacman depending on the platform.

All plugin methods follow the ByRef convention. Errors on open/connect throw a typed exception catchable in try / catch.

curl — HTTP client

Requires: libcurl (auto-installed)

#include "curl"

Curl:SetHeader("Authorization", "Bearer mytoken");
Curl:SetHeader("Accept", "application/json");

Var:String body;
Var:Number status;

try {
    Curl:Get("https://api.example.com/users", body);
} catch (CurlException e) {
    Konsol:Print("curl error: ${e.message}");
}

Curl:Status(status);
Konsol:Print("${status}: ${body}");

Curl:ClearHeaders();

sqlite — SQLite database

Requires: nothing — SQLite is compiled directly into the plugin (amalgamation)

#include "sqlite"

Var:Number db;
Var:Boolean ok;
Var:String rows;
Var:Number n;

try {
    SQLite:Open("data.db", db);
} catch (SQLiteException e) {
    Konsol:Print("open failed: ${e.message}");
}

SQLite:Exec(db, "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)", ok);
SQLite:Exec(db, "INSERT INTO users (name) VALUES ('Alice')", ok);
SQLite:LastInsertId(db, n);
Konsol:Print("inserted id: ${n}");

SQLite:Query(db, "SELECT * FROM users", rows);
Konsol:Print(rows);   // [{"id":1,"name":"Alice"}]

SQLite:Close(db);

Query results are returned as a JSON string — parse with the Json: module.

mysql — MySQL database

Requires: libmysqlclient (auto-installed)

#include "mysql"

Var:Number db;
Var:Boolean ok;
Var:String rows;

try {
    MySQL:Connect("localhost", "root", "secret", "mydb", db);
} catch (MySQLException e) {
    Konsol:Print("connect failed (${e.code}): ${e.message}");
}

MySQL:Exec(db, "INSERT INTO users (name) VALUES ('Alice')", ok);

Var:Number lastId;
MySQL:LastInsertId(db, lastId);

MySQL:Query(db, "SELECT * FROM users ORDER BY id", rows);
Konsol:Print(rows);   // [{"id":1,"name":"Alice"}]

MySQL:Close(db);

Query results are returned as a JSON string — parse with the Json: module.

zip — Zip archives

Requires: libzip (auto-installed)

#include "zip"

Var:Number z;
Var:Boolean ok;
Var:String content;
Var:Number n;

try {
    Zip:Open("archive.zip", z);
} catch (ZipException e) {
    Konsol:Print("open failed: ${e.message}");
}

Zip:AddText(z, "hello.txt", "Hello from minks!", ok);
Zip:AddFile(z, "data/config.json", "config.json", ok);
Zip:AddDir(z, "logs/", ok);
Zip:Count(z, n);
Konsol:Print("entries: ${n}");
Zip:Close(z);   // writes to disk

// Read back
Zip:Open("archive.zip", z);
Zip:Read(z, "hello.txt", content);
Konsol:Print(content);          // Hello from minks!
Zip:Extract(z, "hello.txt", "extracted.txt", ok);
Zip:Close(z);

Embedding API

libkonsolscript is the interpreter as a shared library. Any C++17 application can link against it to make itself scriptable — no dependency on the minks CLI.

libkonsolscript.dll   (Windows)
libkonsolscript.so    (Linux)
libkonsolscript.dylib (macOS)
libkonsolscript.a     (all platforms — static, built with `make static`)

The public API surface is two headers:

Linking

Makefile (Windows/MinGW):

CXX      = g++
CXXFLAGS = -std=c++17 -I/path/to/minks

sample_app.exe: main.cpp
    $(CXX) $(CXXFLAGS) -o $@ main.cpp -L/path/to/minks -lkonsolscript
    # Copy libkonsolscript.dll next to the exe so Windows can find it
    cmd /C copy /Y /path/to/minks/libkonsolscript.dll .

Makefile (Linux):

CXX      = g++
CXXFLAGS = -std=c++17 -I/path/to/minks

sample_app: main.cpp
    $(CXX) $(CXXFLAGS) -o $@ main.cpp \
        -L/path/to/minks -lkonsolscript -Wl,-rpath,'$$ORIGIN'
    # rpath=$ORIGIN means libkonsolscript.so is found next to the binary

macOS: replace -Wl,-rpath,'$$ORIGIN' with -Wl,-rpath,@loader_path.

Engine lifecycle

#include "kse.hpp"

Engine engine;          // ctor registers all stdlib modules
engine.setDebug(true);  // optional: trace each statement to stderr

The Engine constructor registers all built-in modules (Konsol, Math, String, File, Time, List, Map, Json, OS, Hash, Date, CSV). No extra initialisation is needed.

Running scripts

Inline / REPL-style — append a source fragment and execute immediately:

engine.eval(R"(
    Var:Number x = 6 * 7;
    Konsol:Print(x);
)");

eval() preserves engine state between calls, so variables declared in one call are visible in the next. This is the same mode the minks REPL uses.

File-style — parse a complete script, then run it:

std::ifstream f("game.ks");
std::ostringstream ss; ss << f.rdbuf();

engine.loadScript(ss.str(),
    "/path/to/scripts",   // base dir for #include resolution
    "game.ks");           // filename shown in error messages

engine.run();

Passing data between host and script

Host → script (set a global before running the script):

engine.setVar("player_name",  Value(std::string("Alice")));
engine.setVar("player_score", Value(0.0));
engine.setVar("debug_mode",   Value(true));

Script → host (read a global after run() or eval() returns):

Value score = engine.getVar("player_score");
double s = toDouble(score);

Value status = engine.getVar("status");
std::string st = toString(status);

getVar returns a zero-value (0, "", false) for names that do not exist — same semantics as KonsolScript's zero-value design.

Constructing Value

Value(42.0)                        // Number
Value(std::string("hello"))        // String  — always use std::string, not const char*
Value(true)                        // Boolean

Calling script functions from the host

Value result = engine.callFunction("add", { Value(3.0), Value(4.0) });
double n = toDouble(result);   // 7

The function must be defined in a script that was already loaded/eval'd. Missing functions throw a std::runtime_error.

Registering a host class

Host-side classes use the same handler mechanism as built-in modules. The handler receives the raw token stream and must advance past the full statement.

engine.registerClass("Game", [](Engine& e, size_t i) -> size_t {
    ++i;                                    // skip "Game"
    if (e.tokenText(i) != ":") return e.skipOptSemi(i);
    ++i;                                    // skip ":"
    std::string method = e.tokenText(i++); // read method name
    if (e.tokenText(i) == "(") ++i;        // skip (

    if (method == "GetScore") {
        std::string outVar = e.tokenText(i++);
        if (e.tokenText(i) == ")") ++i;
        e.setVar(outVar, Value(current_score));   // ByRef pattern
    }
    return e.skipOptSemi(i);
});

For simpler class registration without token parsing, use the PluginClass builder from minks_plugin.h (see Plugin system

Plugin search paths (embedding)

When a script uses #include "foobar", the engine searches its plugin path list. The host can prepend directories to this list before running any script:

engine.addPluginPath("/opt/mygame/plugins");

For iOS / embedded targets where dlopen is not available, register plugins statically before running the script:

// foobar_plugin.cpp exports:  extern "C" void minks_register(Engine&);
engine.addPluginPreload("foobar", foobar_plugin_init);
// Now #include "foobar" in a script calls foobar_plugin_init instead of dlopen

Compile with -DMINKS_NO_DYNLOAD to strip all dynamic-loading code from libkonsolscript entirely.

Worked example: sample_app

sample_app/ in the minks repository is a minimal host application that demonstrates the complete embedding workflow. It has no dependency on the minks CLI source.

sample_app/main.cpp (abridged):

#include "kse.hpp"
#include <fstream>
#include <sstream>

int main(int argc, char* argv[]) {
    Engine engine;

    // Host → script: expose app metadata as globals
    engine.setVar("app_name",    Value(std::string("SampleApp")));
    engine.setVar("app_version", Value(1.0));

    if (argc >= 2) {
        // File mode: load and run a .ks script
        std::ifstream f(argv[1]);
        std::ostringstream ss; ss << f.rdbuf();
        std::string path = argv[1];
        size_t sep = path.find_last_of("/\\");
        std::string dir = (sep != std::string::npos) ? path.substr(0, sep) : ".";
        engine.loadScript(ss.str(), dir, path);
        return engine.run() ? 0 : 1;
    }

    // Inline mode: eval fragments, read results back
    engine.eval("Var:Number result = 0; for (Number i=1;i<=10;i++){result=result+i;}");
    double sum = toDouble(engine.getVar("result"));   // 55
    return 0;
}

sample_app/demo.ks — the matching script:

Var:String banner = "Running inside: " + app_name + " v" + app_version;
Konsol:Print(banner);

Var:Number pw = 0;
Math:Power(2, 10, pw);
Konsol:Print(pw);    // 1024

Build and run:

cd sample_app
make
./sample_app           # inline demo
./sample_app demo.ks   # file mode

Platform notes

Notes and known limits

• Division by zero returns 0.
• Arrays are fixed-size; out-of-bounds reads return 0/""/false.
• #include "file.ks" is fully supported with transitive includes and include-guard deduplication. See Preprocessor.
• Variables declared inside main() are properly scoped and cleaned up after main returns (fixed).
• 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.