OOP Wrappers

KonsolScript's standard library uses the ByRef convention - every method writes its result to a pre-declared output variable. The wrapper library in include/ provides object-oriented facades over those modules, using return-type syntax instead.

#include "include/FileObject.ks"

Var:FileObject f;
f.Open("data.txt", "w")
f.Write("hello\n")
f.Close()

Wrappers live in minks/include/. Load one with #include "include/WrapperName.ks".

Stateless wrappers (StringObject, MathObject, RegexObject, OsObject, PathObject) pre-declare a singleton instance (str, math, regex, os, path) so you can call methods immediately after the #include.

Stateful wrappers (FileObject, CsvObject, TimeObject, DateObject) hold internal state - declare your own instance with Var:WrapperName name;.

Generic wrappers (ListOf, DictionaryOf) take a type parameter at declaration time: Var:ListOf:String names;.

FileObject

Wraps the File module. Stores the file handle internally - no handle variable needed in the calling script.

#include "include/FileObject.ks"

Method	Description
`f.Open(path, mode)`	Open file; mode is `"r"`, `"w"`, or `"a"`. Throws `FileException` on failure.
`f.Close()`	Close the file
`f.Write(text)`	Write string to file
`f.Read() : String`	Read next whitespace-delimited token
`f.ReadLine() : String`	Read next line
`f.ReadAll() : String`	Read entire remaining content
`f.IsEOF() : Boolean`	`true` if at end of file

Errors throw FileException - catch by type or let it propagate.

#include "include/FileObject.ks"

Var:FileObject f;

try {
    f.Open("report.txt", "w")
    f.Write("line one\n")
    f.Write("line two\n")
    f.Close()

    f.Open("report.txt", "r")
    while (f.IsEOF() == false) {
        Var:String line = f.ReadLine();
        Konsol:Print(line)
    }
    f.Close()
} catch (FileException e) {
    Konsol:Print("file error: ${e.message}")
}

JsonObject

Wraps the JSON module. Creates and manages the document handle internally - no handle variable needed in the calling script. The document is created automatically when the instance is declared.

#include "include/JsonObject.ks"

Method	Description
`j.Parse(str)`	Parse JSON string into the document
`j.Free()`	Release the document
`j.Set(path, value)`	Write a Number at path
`j.SetStr(path, value)`	Write a String at path
`j.SetBool(path, value)`	Write a Boolean at path
`j.Get(path) : Number`	Read value as Number
`j.GetStr(path) : String`	Read value as String
`j.Has(path) : Boolean`	`true` if path exists
`j.Type(path) : String`	`"object"` `"array"` `"string"` `"number"` `"bool"` `"null"`
`j.Length(path) : Number`	Element count for array or object
`j.Push(path, value)`	Append a Number to array at path
`j.PushStr(path, value)`	Append a String to array at path
`j.Stringify() : String`	Serialize entire document to JSON string
`j.StringifyAt(path) : String`	Serialize subtree at path

#include "include/JsonObject.ks"

Var:JsonObject j;

j.SetStr("host", "localhost")
j.Set("port", 8080)
j.SetBool("tls", false)
Konsol:Print(j.Stringify())   // {"host":"localhost","port":8080,"tls":false}

Var:JsonObject resp;
resp.Parse("{\"status\":200,\"name\":\"Alice\"}")
Konsol:Print(resp.GetStr("name"))   // Alice
Konsol:Print(resp.Get("status"))    // 200

CsvObject

Wraps the CSV module. Owns a CSV document handle internally.

#include "include/CsvObject.ks"

Method	Description
`c.Parse(str)`	Parse CSV string (comma delimiter)
`c.ParseDelim(str, delim)`	Parse with a custom delimiter
`c.Get(row, col) : String`	Read cell value
`c.Set(row, col, val)`	Write cell value
`c.Rows() : Number`	Number of rows
`c.Cols(row) : Number`	Number of columns in a row
`c.Stringify() : String`	Serialize to CSV string (comma delimiter)
`c.StringifyDelim(delim) : String`	Serialize with a custom delimiter
`c.Free()`	Release the document

#include "include/CsvObject.ks"

Var:CsvObject c;
c.Parse("name,age\nAlice,30\nBob,25")

Var:Number rows = c.Rows();
Var:Number i = 0;
while (i < rows) {
    Konsol:Print("${c.Get(i, 0)} is ${c.Get(i, 1)}")
    i = i + 1
}

StringObject

Wraps the String module. Stateless - the include declares a singleton str for immediate use. Join is not wrapped because it is variadic; call String:Join directly.

#include "include/StringObject.ks"

Method	Description
`str.Len(s) : Number`	Length of string (alias: `Length`)
`str.Left(s, n) : String`	First `n` characters
`str.Right(s, n) : String`	Last `n` characters
`str.Mid(s, start, len) : String`	Substring (alias: `Substring`)
`str.Replace(s, from, to) : String`	Replace all occurrences
`str.Trim(s) : String`	Strip leading and trailing whitespace
`str.Upper(s) : String`	Convert to uppercase
`str.Lower(s) : String`	Convert to lowercase
`str.Reverse(s) : String`	Reverse the string
`str.Compare(a, b) : Number`	`0` if equal, negative/positive otherwise
`str.Contains(s, sub) : Boolean`	`true` if `sub` is found in `s`
`str.Split(s, delim) : ListOf:String`	Split string by delimiter; returns a `ListOf:String`

#include "include/StringObject.ks"

Var:String name = "  Hello, World!  ";
Konsol:Print(str.Trim(name))               // Hello, World!
Konsol:Print(str.Upper(str.Trim(name)))    // HELLO, WORLD!
Konsol:Print(str.Len(str.Trim(name)))      // 13

Var:ListOf:String parts = str.Split("a,b,c", ",");
Konsol:Print(parts.Size())    // 3
Konsol:Print(parts.Get(0))    // a

MathObject

Wraps the Math module. Stateless - the include declares a singleton math for immediate use. Min and Max are not wrapped because they take a list argument; call Math:Min / Math:Max directly.

#include "include/MathObject.ks"

Method	Description
`math.Abs(n) : Number`	Absolute value (alias: `Absolute`)
`math.Round(n) : Number`	Round to nearest integer
`math.Floor(n) : Number`	Round down
`math.Ceil(n) : Number`	Round up (alias: `Ceiling`)
`math.Sqrt(n) : Number`	Square root (alias: `SquareRoot`)
`math.Sin(n) : Number`	Sine (alias: `Sine`)
`math.Cos(n) : Number`	Cosine (alias: `Cosine`)
`math.Tan(n) : Number`	Tangent (alias: `Tangent`)
`math.Log(n) : Number`	Natural logarithm
`math.Exp(n) : Number`	e raised to power n
`math.Power(base, exp) : Number`	base raised to exp
`math.Clamp(n, lo, hi) : Number`	Clamp n to [lo, hi]
`math.Lerp(a, b, t) : Number`	Linear interpolation
`math.Random() : Number`	Random number in [0, 1)
`math.RandomMax(max) : Number`	Random number in [0, max)
`math.Seed(n)`	Seed the random number generator

#include "include/MathObject.ks"

Konsol:Print(math.Clamp(150, 0, 100))   // 100
Konsol:Print(math.Power(2, 10))         // 1024
Konsol:Print(math.Round(math.Sqrt(2)))  // 1

RegexObject

Wraps the Regex module. Stateless - the include declares a singleton regex for immediate use. Groups is not wrapped because it writes to a pre-declared list variable; call Regex:Groups directly.

#include "include/RegexObject.ks"

Method	Description
`regex.Test(pattern, str) : Boolean`	`true` if pattern matches anywhere in string (alias: `Match`, `IsMatch`)
`regex.Find(pattern, str) : String`	First match; empty string if none
`regex.Replace(pattern, str, repl) : String`	Replace first match

#include "include/RegexObject.ks"

Var:String email = "user@example.com";
Konsol:Print(regex.Test("[a-z]+@[a-z]+\\.[a-z]+", email))   // true
Konsol:Print(regex.Find("\\d+", "order #4821"))              // 4821
Konsol:Print(regex.Replace("\\s+", "too  many   spaces", " "))

OsObject

Wraps the OS module. Stateless - the include declares a singleton os for immediate use. ListDir and Args are not wrapped because they write to a pre-declared list variable; call OS:ListDirectory / OS:Args directly.

#include "include/OsObject.ks"

Method	Description
`os.CurrentDirectory() : String`	Current working directory
`os.ChangeDirectory(p)`	Change working directory
`os.MakeDirectory(p) : Boolean`	Create directory; `true` on success
`os.MakeDirectories(p) : Boolean`	Create directory tree; `true` on success
`os.Remove(p) : Boolean`	Delete file or empty directory
`os.Rename(old, new)`	Rename or move a file
`os.GetEnvironment(name) : String`	Read environment variable
`os.SetEnvironment(name, value)`	Set environment variable
`os.System(cmd) : Number`	Run shell command; returns exit code
`os.Exit(code)`	Exit the process

#include "include/OsObject.ks"

Konsol:Print(os.CurrentDirectory())
os.MakeDirectory("output")
Var:Number code = os.System("echo hello");
Konsol:Print("exit: ${code}")

PathObject

Wraps the Path module. Stateless - the include declares a singleton path for immediate use.

#include "include/PathObject.ks"

Method	Description
`path.Join(a, b) : String`	Join two path segments
`path.DirectoryName(p) : String`	Parent directory of path
`path.FileName(p) : String`	File name with extension
`path.Stem(p) : String`	File name without extension
`path.Extension(p) : String`	File extension including `.`
`path.Exists(p) : Boolean`	`true` if path exists
`path.IsFile(p) : Boolean`	`true` if path is a regular file
`path.IsDirectory(p) : Boolean`	`true` if path is a directory
`path.Absolute(p) : String`	Resolve to absolute path

#include "include/PathObject.ks"

Var:String p = "src/main.ks";
Konsol:Print(path.DirectoryName(p))   // src
Konsol:Print(path.Stem(p))            // main
Konsol:Print(path.Extension(p))       // .ks
Konsol:Print(path.Exists(p))          // true / false

TimeObject

Wraps the Date module for time-of-day operations. Stateful - stores an internal timestamp initialised to the current time at construction. Declare your own instance; no singleton is pre-declared.

#include "include/TimeObject.ks"

Method	Description
`t.Now()`	Reset timestamp to current time
`t.Timestamp() : Number`	Raw Unix timestamp
`t.Hour() : Number`	Hour component (0-23)
`t.Minute() : Number`	Minute component (0-59)
`t.Second() : Number`	Second component (0-59)
`t.AddHours(n)`	Advance timestamp by n hours
`t.AddMinutes(n)`	Advance timestamp by n minutes
`t.AddSeconds(n)`	Advance timestamp by n seconds
`t.Format(fmt) : String`	Format as string using `strftime` format codes

#include "include/TimeObject.ks"

Var:TimeObject t;
Konsol:Print(t.Format("%H:%M:%S"))   // current time, e.g. 14:05:32

t.AddHours(2)
Konsol:Print(t.Format("%H:%M"))      // two hours later

DateObject

Wraps the Date module for calendar operations. Stateful - stores an internal timestamp initialised to the current time at construction. Declare your own instance; no singleton is pre-declared.

#include "include/DateObject.ks"

Method	Description
`d.Now()`	Reset timestamp to current time
`d.Timestamp() : Number`	Raw Unix timestamp
`d.Year() : Number`	Year component
`d.Month() : Number`	Month component (1-12)
`d.Day() : Number`	Day of month (1-31)
`d.Hour() : Number`	Hour component (0-23)
`d.Minute() : Number`	Minute component (0-59)
`d.Second() : Number`	Second component (0-59)
`d.AddDay(n)`	Advance timestamp by n days (alias: `AddDays`)
`d.Format(fmt) : String`	Format as string using `strftime` format codes
`d.Parse(s, fmt)`	Parse string into internal timestamp
`d.Diff(otherTs) : Number`	Difference from `otherTs` in seconds (alias: `DaysBetween`)

#include "include/DateObject.ks"

Var:DateObject d;
Konsol:Print(d.Format("%Y-%m-%d"))   // e.g. 2026-05-24

d.AddDays(7)
Konsol:Print(d.Format("%Y-%m-%d"))   // one week later

Var:DateObject deadline;
deadline.Parse("2026-12-31", "%Y-%m-%d")
Konsol:Print(deadline.Format("%B %d, %Y"))   // December 31, 2026

ListOf

Generic typed list wrapper. T may be Number, String, Boolean, or any class type. Declare with Var:ListOf:T name; - the type argument is bound at declaration time.

#include "include/ListOf.ks"

Method	Description
`l.Push(item)`	Append item to the end
`l.Pop() : T`	Remove and return the last item
`l.Get(index) : T`	Read item at index
`l.Size() : Number`	Number of items
`l.Contains(value) : Boolean`	`true` if value is present
`l.Remove(index)`	Remove item at index
`l.Sort()`	Sort in place
`l.Clear()`	Remove all items

#include "include/ListOf.ks"

Var:ListOf:String names;
names.Push("Alice")
names.Push("Bob")
names.Push("Charlie")
names.Sort()

Var:Number i = 0;
while (i < names.Size()) {
    Konsol:Print(names.Get(i))
    i = i + 1
}

DictionaryOf

Generic typed dictionary wrapper. T may be Number, String, Boolean, or any class type. Declare with Var:DictionaryOf:T name;. Keys is not wrapped because it writes to a pre-declared list variable; call Dictionary:Keys directly.

#include "include/DictionaryOf.ks"

Method	Description
`d.Set(key, value)`	Write a key-value pair
`d.Get(key) : T`	Read value for key
`d.Has(key) : Boolean`	`true` if key exists
`d.Remove(key)`	Delete a key
`d.Size() : Number`	Number of keys
`d.Clear()`	Remove all entries

#include "include/DictionaryOf.ks"

Var:DictionaryOf:Number scores;
scores.Set("Alice", 95)
scores.Set("Bob", 82)
scores.Set("Charlie", 88)

Konsol:Print(scores.Get("Alice"))    // 95
Konsol:Print(scores.Has("Dave"))     // false
Konsol:Print(scores.Size())          // 3