Standard Library
DOCUMENTATION
XCX 4.4.1 Standard Library and Modules
Built-in Modules
crypto
Cryptography utilities.
| Method | Returns | Description |
|---|---|---|
crypto.hash(data, "bcrypt") | s | Hashes password using bcrypt |
crypto.hash(data, "argon2") | s | Hashes password using argon2 (recommended) |
crypto.hash(data, "base64_encode") | s | Encodes binary data/string to Base64 string |
crypto.hash(data, "base64_decode") | s | Decodes Base64 string back to binary/string |
crypto.verify(password, hash, algo) | b | Returns true if password matches hash |
crypto.token(length) | s | Random hex token; length is the byte length, so the result is 2 * length hexadecimal characters |
xcx
_
⛶
×
1s: hash = crypto.hash(password, "bcrypt");
2s: hash2 = crypto.hash(password, "argon2");
3b: valid = crypto.verify(password, hash2, "argon2");
4s: token = crypto.token(32); --- 64 hexadecimal characters (32 bytes)
store (File I/O)
All paths must be relative to the project root. Absolute paths or path traversal (..) trigger halt.fatal.
| Method | Signature | Returns | Description |
|---|---|---|---|
store.write(p, c) | (s, s) → b | b | Overwrites file. Creates directories if needed. |
store.read(p) | (s) → s | s | Returns file contents; halt.fatal if missing. |
store.append(p, c) | (s, s) → b | b | Appends to file. Creates if missing. |
store.exists(p) | (s) → b | b | Checks existence. No side effects. |
store.delete(p) | (s) → b | b | Removes file or directory (recursive). |
store.list(p) | (s) → array:s | array:s | Returns list of files and folders. |
store.isDir(p) | (s) → b | b | true if path is a directory. |
store.size(p) | (s) → i | i | File size in bytes. |
store.mkdir(p) | (s) → b | b | Creates directory (recursive). |
store.glob(pat) | (s) → array:s | array:s | Returns files matching glob pattern. |
store.zip(s, t) | (s, s) → b | b | Archives source to target zip. |
store.unzip(z, d) | (s, s) → b | b | Extracts zip to destination. |
xcx
_
⛶
×
1store.write("log.txt", "First line");
2store.append("log.txt", "\nSecond line");
3s: content = store.read("log.txt");
4if (store.exists("lock.pid")) then;
5 >! "Already running";
6end;
env
| Method | Signature | Returns | Description |
|---|---|---|---|
env.get(name) | (s) → s | s | Returns env variable value; halt.error if not set |
env.args() | () → array:s | array:s | Returns CLI arguments passed to the program as an array |
xcx
_
⛶
×
1s: db_url = env.get("DATABASE_URL");
2
3array:s: args = env.args();
4for arg in args do;
5 >! arg;
6end;
random
| Method | Signature | Returns | Description |
|---|---|---|---|
random.choice from col | (set/array) → T | T | Picks a random element from the provided set or array. |
random.int(min, max @step num) | (i, i, @i) → i | i | Picks a random integer in range [min, max]. Default step: 1. |
random.float(min, max @step num) | (f, f, @f) → f | f | Picks a random float in range [min, max]. Default step: 0.5. |
xcx
_
⛶
×
1set:N: pool {1,,10};
2i: picked = random.choice from pool;
3
4--- Works on arrays too
5array:s: words {"hello", "world"};
6s: w = random.choice from words;
7
8--- Picks 1, 3, 5, 7, or 9
9i: odd = random.int(1, 10 @step 2);
10
11--- Picks 0.0, 0.5, 1.0, 1.5, or 2.0
12f: weight = random.float(0.0, 2.0);
13
14--- Picks 0.0, 0.25, 0.5, 0.75, 1.0
15f: precision = random.float(0.0, 1.0 @step 0.25);
date (module)
xcx
_
⛶
×
1date: now = date.now();
perf
Provides a monotonic, high-resolution timer for performance benchmarking. Unlike date.now(), the values returned by perf are guaranteed to be monotonic (never go backward) and are not affected by system clock adjustments (NTP/Daylight Saving Time).
| Method | Signature | Returns | Description |
|---|---|---|---|
perf.ms() | () → i | i | Elapsed time in milliseconds since the VM started |
perf.us() | () → i | i | Elapsed time in microseconds (10⁻⁶ seconds) since the VM started |
perf.ns() | () → i | i | Elapsed time in nanoseconds (10⁻⁹ seconds) since the VM started |
xcx
_
⛶
×
1i: start = perf.ms();
2--- Code to benchmark
3i: elapsed = perf.ms() - start;
4>! "Elapsed: " + s(elapsed) + " ms";
#### Error Handling and Halts
| Scenario | Behavior / Error |
|---|---|
| Complete lack of OS monotonic timer support | halt.fatal raised on the first method invocation |
Calling perf methods with arguments (e.g. perf.ms(10)) | Compile-time signature mismatch error |
Assigning perf values directly to date variables | Compile-time type mismatch error |
Counter overflow (perf.ns() after ~292 years) | No halt.error (wrap-around to negative value) |
| Platform lacks native microsecond/nanosecond timer | Auto-fallback to next lower precision, scaled (never fails) |
Module System
include
Merges code from another file into the current namespace.
xcx
_
⛶
×
1include "utils.xcx";
2include "math.xcx" as m;
3
4m.PI;
5m.sqrt(16.0);
Without an alias - all symbols are available directly in the current namespace. With an alias - all top-level symbols are prefixed: alias.symbol.
Cyclic dependencies are detected and rejected at compile time.