Not the JVM Lisp at LuxLang/lux, and not the Lux9 microkernel. Scripts are still .lux; the command is still lux. Site: luxlang.dev · lux9.dev.
Lux is a dynamically-typed scripting language for system automation, cloud integration, and embedded scripting. Originally written in Plan 9 C, it runs on macOS, Linux, OpenBSD, and Plan 9.
The language is still Lux (Latin for "light"): Lox from Crafting Interpreters, grown up for Plan 9. Lux9 is the public name so it can be found. Full Lox parity, plus a real standard library and first-class Plan 9 support.
Built from first principles (inspired by "Crafting Interpreters"), Lux combines a clean language design with modern features: HTTP/HTTPS, cryptography, AWS integration, databases, and file I/O. The language itself is defined in SPEC.md.
Language:
- Dynamic typing — numbers, strings, arrays, hashes, objects
- First-class functions — lexical scoping, closures, recursion
- Classes & inheritance — single inheritance, methods, fields
- Modules —
import "path.lux"for code organization - Automatic GC — mark-and-sweep garbage collector
Standard Library:
- File I/O — read, write, append, list directories
- JSON — parse and serialize
- XML — basic parsing
- Strings/Arrays — slice, find, split, sort, binary search, array concatenation (
+) - Dictionaries — native
Dictclass withput/get/has/remove/size/clearplusiter()returning an array of{key, value}entries - Float64Array — typed double buffer, reductions and dot product
- DataFrame / CSV — quoted CSV, groupBy, sortBy,
lib/dataframe.lux - Graphs — BFS/DFS and Graphviz DOT export,
lib/graph.lux - Math — abs, ceil, floor, sqrt, pow, log, sin, cos
- HTTP — client (GET/POST/PUT) and server (routes, static, virtual hosts, OpenAPI/Swagger UI, Lambda via
server.handle/ Mangum) - Network —
netLookup(DNS) andnetPing(TCP-connect RTT), norun() - 9P — serve a synthetic 9P2000 tree and connect as a client (
NineP, unix socket or TCP). See NINEP.md. - Templates — native
renderTemplate({{ }},{% for %},{% include %}) - Crypto — SHA-256, HMAC-SHA256, AWS request signing
- Cloud — AWS S3, STS, IAM operations
- Databases — SQLite, PostgreSQL, MySQL (opt-in)
- Code formatting —
luxfmt(gofmt-style) - Testing —
luxtestwith timeouts and reporting - Web checks —
lib/webtest.lux(POSIX): curl status/body, k6 load, Playwright (shells out; no VM change) - Assertions —
assert(condition, message)for test-driven development - Syntax —
luxcheckfast lightweight syntax checker - Linting —
luxlintstatic checks: unused vars, unreachable code, duplicate functions, shadowed globals
cd posix
make
./lux ../examples/demo.luxcd posix
gmake # GNU make required
./lux ../examples/demo.luxmk
./8.out ../examples/demo.luxlux -v (or lux --version) prints the release, the system it was compiled on, the git branch, and git describe. A -dirty suffix means the tree had uncommitted changes. Database drivers show up only when that build enabled them:
lux 1.2.0 darwin/arm64 front v1.2.0
lux 1.2.0 linux/x86_64 oracle v1.2.0-4-gabcd123 +oracle
The line is fixed at compile time, so a copy on another machine still names the branch it came from.
print "Hello, Lux!";
fun fib(n) {
if (n < 2) return n;
return fib(n - 2) + fib(n - 1);
}
print fib(10); // 55
./lux -c "print 1 + 2;" # POSIX: Quick eval (scripting, CI)
./lux -c "assert(len(\"hi\") == 2);" # Assertions for checks
./lux -c 'var out = run("echo hello"); print out;' # POSIX: Subprocess
# Plan 9: 8.out -c 'print 1 + 2;' (use single quotes; rc parses " differently)
# Plan 9: 8.out -c 'var out = run("echo hello"); print out;' # Subprocess./luxtest -t 5 tests/ # All tests with 5s timeout
./luxtest tests/fib.lux # Single test./luxfmt --write myfile.lux # In-place (POSIX)
./luxfmt -w myfile.lux # In-place (Plan 9)
### Lint
```bash
./luxlint myfile.lux # Warn on unused vars, unreachable code, duplicate functions, shadowed globals
# Plan 9: rc luxlint.rc (build first)Exit codes: 0 = no issues, 1 = warnings, 65 = compile error, 64 = usage error.
See BUILD.md for comprehensive platform-specific build guides:
- macOS — Homebrew setup, native arch (arm64 or x86_64)
- Linux — Debian, Ubuntu, Fedora, CentOS
- OpenBSD — GNU Make, port package paths
- Plan 9 — mk tool, compiler selection
- Optional features — SQLite, PostgreSQL, MySQL database drivers
Lux is ideal for:
- System automation — File I/O, process orchestration, configuration management
- Cloud scripting — Direct AWS S3/STS/IAM integration, HTTP/HTTPS clients
- Embedded scripting — Lightweight bytecode interpreter, Plan 9 native
- Testing frameworks — Built-in
assert()andluxtestrunner - Portable tools — Single binary, runs on macOS, Linux, OpenBSD, Plan 9
Lux is NOT ideal for: Lux is NOT ideal for:
- Large numerical compute — Lux is not tuned for large-scale number‑crunching; prefer numerical Python/Julia for heavy workloads. For moderate numeric work you can use Float64Array, BLAS wrappers, or build the POSIX runtime with optimizations (see
posix/Makefileandbenchmark.md). - GUI development (no graphics APIs)
- Mobile development (not designed for mobile targets)
// GET — returns response body string, or nil on failure
// Single object endpoint (property access works on all builds):
var res = httpGet("https://fakestoreapi.com/products/1");
if (res != nil) {
var data = parseJSON(res);
if (data != nil) {
print data.title;
print data.price;
}
}
// Array endpoint (requires lux built with JSON→native-array parseJSON):
// var list = parseJSON(httpGet("https://fakestoreapi.com/products"));
// print list[0].title;
// POST with custom headers (httpRequest also returns body string or nil)
class Headers { init() {} }
var headers = Headers();
headers.Authorization = "Bearer token123";
headers.Content_Type = "application/json";
class User {
init(username, email) {
this.username = username;
this.email = email;
}
}
var body = toJSON(User("alice", "alice@example.com"));
var resp = httpRequest("POST", "https://api.example.com/users", body, headers);
if (resp != nil) {
print "User created!";
}
// Multipart POST (curl -F). httpPost() is JSON-only — use Form + httpRequest.
import "../lib/http.lux";
var form = Form();
form.field("name", "legacy");
form.file("file", "script.js", "application/x-javascript");
var formHeaders = Headers();
formHeaders.accept = "application/json";
var formResp = httpRequest("POST", "https://api.example.com/upload", form, formHeaders);
// NDJSON / Ollama stream: true — one callback per line (not one buffered body)
fun onLine(line) {
print line;
}
httpStream("POST", "http://10.0.0.22:11434/api/chat", body, headers, onLine);
// Configurable Server: routes, static, multi-domain vhosts (see examples/vhost_server.lux)
import "../lib/swagger.lux";
var server = Server(8080);
server.workers(4);
server.vhost("example.com", "public/example");
server.get("/health", handleHealth, Op("Health check", "ops"));
swagger(server); // GET /docs
server.start();
// Same routes on AWS Lambda (Mangum-style) — no listen/bind:
// var page = server.handle("GET", "/health");
// Mangum(server); // lib/mangum.lux + lambda/handler.lux
// Legacy one-liner with built-in routes:
httpServer(8080);
// Handles GET /, GET /echo, POST /echo automatically
// Read entire file
var content = readFile("input.txt");
print content;
// Write file
writeFile("output.txt", "Hello, Lux!");
// Append to log
appendFile("events.log", "Timestamp: " + epoch() + "\n");
// List directory
var files = listDir(".");
print files;
// Check existence
if (fileExists("config.json")) {
var config = parseJSON(readFile("config.json"));
}
var out = run("echo hello");
print out; // hello
// With file I/O
var lines = run("wc -l config.json");
print lines;
var ip = netLookup("example.com");
if (ip != nil) print ip; // first resolved address, or nil
var ms = netPing("example.com", 443);
if (ms >= 0) print ms; // TCP-connect round-trip milliseconds
else print "unreachable"; // -1 on timeout / refused / bad args
POSIX Lux can serve a small 9P tree and connect to Plan 9 (or to another Lux). See NINEP.md.
var fs = NineP();
fs.export("/README.md", "README.md");
fs.listen("/tmp/lux.9p"); // blocks; unix socket or tcp!host!port
var c = NineP.connect("unix!/tmp/lux.9p");
c.get("/README.md", "/tmp/README.copy");
c.close();
var user = {
"name": "Alice",
"age": 30,
"tags": ["admin", "dev"]
};
// Serialize
var json = toJSON(user);
writeFile("user.json", json);
// Parse
var data = parseJSON(readFile("user.json"));
print data["name"]; // Alice
print data["tags"][0]; // admin
// SHA-256 hash
var hash = sha256("password123");
// HMAC-SHA256
var signature = hmacSha256("secret", "message");
// AWS request signing
var sig = awsSignRequest("us-east-1", "s3", "AWS4-HMAC-SHA256",
"20250101T000000Z", "...");
// Run: ./luxtest script.lux
assert(1 + 1 == 2, "basic math");
assert(len([1, 2, 3]) == 3, "array length");
assert("hello".startsWith("hel"), "string prefix");
class Calculator {
add(a, b) { return a + b; }
}
var calc = Calculator();
assert(calc.add(2, 3) == 5, "calculator.add");
print "All assertions passed!";
- Numbers:
42,3.14(all numbers are doubles) - Strings:
"hello","world" - Booleans:
true,false - Nil:
nil
String literals can span multiple lines in source code. Newlines are preserved as-is in the string value:
// String with embedded newlines
var message = "Line 1
Line 2
Line 3";
print message;
// Output:
// Line 1
// Line 2
// Line 3
// Works in return statements
fun getMultiLine() {
return "foo
bar";
}
print getMultiLine();
// Output:
// foo
// bar
// Also works directly in print
print "Hello
World";
// Output:
// Hello
// World
Note: Lux does not support escape sequences like \n or \t - use actual newlines in your source code instead.
var x = 10;
var name = "Alice";
var flag = true;
// If/else
if (x > 5) {
print "big";
} else {
print "small";
}
// While loop
while (x > 0) {
print x;
x = x - 1;
}
// For loop
for (var i = 0; i < 10; i = i + 1) {
print i;
}
// break / continue
for (var i = 0; i < 10; i = i + 1) {
if (i == 2) continue; // skip this iteration
if (i == 5) break; // leave the loop
print i;
}
|— logical OR (short-circuit). Example:if (a | b) { ... }&— logical AND (short-circuit). Example:if (a & b) { ... }- Ternary conditional:
cond ? exprTrue : exprFalsereturns a value and can be used inside expressions.
and / or keywords are aliases for & / |. These are logical (short-circuit) operators, not bitwise. || and && are not currently aliases.
fun greet(name) {
return "Hello, " + name;
}
print greet("World");
// Closures
fun makeCounter() {
var count = 0;
fun increment() {
count = count + 1;
return count;
}
return increment;
}
var counter = makeCounter();
print counter(); // 1
print counter(); // 2
class Person {
init(name, age) {
this.name = name;
this.age = age;
}
greet() {
print "Hi, I'm " + this.name;
}
}
var alice = Person("Alice", 30);
alice.greet();
class Animal {
init(name) {
this.name = name;
}
speak() {
print this.name + " makes a sound";
}
}
class Dog < Animal {
speak() {
print this.name + " barks!";
}
}
var buddy = Dog("Buddy");
buddy.speak(); // Buddy barks!
// Create arrays with bracket syntax
var numbers = [1, 2, 3, 4, 5];
var names = ["Alice", "Bob", "Charlie"];
var mixed = [42, "hello", true, nil];
// Access elements by index (0-based)
print numbers[0]; // 1
print names[2]; // Charlie
// Modify existing elements
numbers[0] = 100;
print numbers[0]; // 100
// Get array length
print numbers.length; // 5
// Iterate over arrays
var i = 0;
while (i < names.length) {
print names[i];
i = i + 1;
}
// Arrays grow dynamically when assigning past current length
var data = [1, 2, 3];
data[0] = 10; // Overwrite existing index
data[5] = 50; // Auto-grows array
print data.length; // 6
print data[3]; // nil (gap values are filled with nil)
// Array concatenation with +
var a = [1, 2];
var b = a + [3]; // b is [1, 2, 3]
// Nested arrays
var matrix = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
print matrix[1][2]; // 6
// Arrays from native functions
var xmlResponse = parseXml("<items><item>A</item><item>B</item></items>", "item");
// parseXml returns an array of matching tag contents
for (var j = 0; j < xmlResponse.length; j = j + 1) {
print xmlResponse[j];
}
Lux now exposes a native Dict class for string→string maps. The class supports put, get, has, remove, size, clear, and iter(). Calling iter() returns an array of {key, value} objects that you can loop over from Lux.
var book = Dict();
book.put("alice", "{\"name\":\"Alice\",\"email\":\"alice@example.com\"}");
book.put("bob", "{\"name\":\"Bob\",\"email\":\"bob@example.com\"}");
var entries = book.iter();
var json = "{";
var first = 1;
var i = 0;
while (i < entries.length) {
var entry = entries[i];
if (first == 0) { json = json + ","; }
first = 0;
json = json + "\"" + entry.key + "\":" + entry.value;
i = i + 1;
}
json = json + "}";
print json;
The iterator is handy for rebuilding structured data or producing JSON output without importing helper libraries.
// Import code from other files to organize your programs
// Paths are relative to the current working directory
// math_utils.lux:
fun add(a, b) {
return a + b;
}
fun multiply(a, b) {
return a * b;
}
// main.lux:
import "math_utils.lux";
print(add(5, 3)); // 8
print(multiply(4, 7)); // 28
// Features:
// - Imported files are executed once (cached to prevent duplicates)
// - All definitions go into global scope
// - Circular imports are prevented automatically
// - Import paths are relative to where you run the program
// - Each import is its own compiler chunk (helps the 256 identifier-slot limit; see below)
// Example directory structure:
// project/
// main.lux
// utils/
// math.lux
// string.lux
// From project/ directory:
import "utils/math.lux";
import "utils/string.lux";
mk
cd posix/
make
Platform guides:
- Linux:
posix/README-LINUX.md - OpenBSD:
posix/README-OPENBSD.md
8.out
8.out script.lux
8.out -c 'print 1 + 2;' # Plan 9: use single quotes (rc shell)
8.out -c 'assert(len("hello") == 5);' # CI-style checks
# POSIX: ./lux -c "print 1 + 2;"
Pass arguments after the script path. Inside the script, call args() to get them as an array of strings:
./lux script.lux foo bar
var a = args();
print a.length; // 2
print a[0]; // foo
print a[1]; // bar
args() returns an empty array in the REPL, with lux -c, or when no extra arguments are given.
8.out examples/demo.lux # Simple working demo
8.out examples/tutorial_simple.lux # Quick tutorial (recommended)
8.out examples/quickref.lux # Language quick reference
8.out examples/test_concat.lux # String concatenation examples
8.out tests/test_fileio.lux # File I/O examples
8.out tests/test_fileops.lux # Complete file operations test
8.out tests/test_json.lux # JSON parsing and serialization
8.out tests/test_http_plan9.lux # HTTP client (Plan 9 HTTP)
8.out tests/test_https.lux # HTTPS client with TLS (Plan 9)
posix/lux tests/test_http.lux # HTTP/HTTPS examples (POSIX)
8.out tests/test_http_server.lux # HTTP server (both Plan 9 and POSIX)
posix/lux examples/lambda_web.lux # Local HTTP server (Mangum if Lambda event file)
posix/lux examples/lambda_web.lux --once # One request via server.handle, no listen
posix/lux examples/swagger_server.lux # OpenAPI /docs (port 8085)
posix/lux examples/oauth_server.lux # OAuth2 client-credentials (port 8086)
8.out examples/dataframe_prototype.lux # DataFrame / CSV demo
8.out examples/graph_demo.lux # Graph + Graphviz DOT
8.out tests/c29-inherit.lux # Inheritance examples
8.out tests/closure.lux # Closure examples
Compile error:
[line N] Error at 'name': Too many unique identifiers in one chunk.
With a script path the same error is file.lux:N: Error at 'name': … so Acme can plumb it.
This is not a file line-count limit. Each compiled function is a chunk (top-level script, each fun, each method, each import). Identifier opcodes (assert, .status, globals, …) can only point at constant-pool slots 0..255. String literals share that same pool (they can use OP_CONSTANT_LONG for later slots, but they still take indices). Names are not interned: every assert(...) at top level burns another slot.
A test file with lots of assert + string literals hits this while a 400-line lib/ file is fine, because methods each get their own chunk.
Fix: wrap the busy top-level code in a function (see tests/test_webtest.lux):
fun run() {
assert(len("hi") == 2, "len");
// more asserts ...
}
run();
Or split files / import. Full table: SPEC.md §13.
Lux supports automatic type conversion with the + operator:
- Numbers:
1 + 2→3(numeric addition) - Arrays:
[1, 2] + [3]→[1, 2, 3](array concatenation; both operands must be arrays) - Strings:
"Hello" + " World"→"Hello World" - Mixed types:
"Score: " + 42→"Score: 42"(auto-converts to string) - Multiple types:
"Player " + 1 + " wins!"→"Player 1 wins!"
Any type (number, boolean, nil) is automatically converted to string when used with + and at least one string operand. For building large arrays, prefer index assignment (arr[i] = x) over repeated concatenation, since arr + [x] in a loop copies the whole array each time (O(n²)).
Use help() in the REPL to list callable globals (native functions, classes, and functions).
Use help("name") to inspect one symbol.
help();
help("dbQuery");
help("str"); // unknown names can suggest close matches
print epoch(); // Unix epoch seconds (UTC)
class Greeter {
init(name) {
this.name = name;
}
hello() {
print "hello " + this.name;
}
}
help("Greeter"); // shows class type and known method names
help() groups callables by category (Core, Math, File and Directory, String and Array, Data Formats, Float64, HTTP, Network, 9P, Crypto, AWS, Database, and User or Other) so long lists are easier to scan.
epoch() returns Unix timestamp seconds in UTC, which is useful for durable event timestamps.
Plan 9 REPL tip: if multiline input is awkward in your terminal, define classes on one line and then inspect them.
class Greeter {init(name){this.name = name;} hello(){print "hello " + this.name;}}
help("Greeter");
Typical output for help("dbQuery"):
dbQuery
dbQuery(conn, sql)
Execute SQL and return rows for queries.
Type: native function
Terminate the Lux runtime immediately. The optional numeric code defaults to 0 (success); non-zero values signal failure and make luxtest/shell detect an error. On POSIX builds the process exit code matches code, while on Plan 9 the interpreter exits with reason exit <code>.
if (!fileExists("config.json")) {
print "Missing config file";
exit(1); // abort with failure
}
// Normal shutdown
exit();
Lux includes native file I/O functions for both Plan 9 and POSIX systems:
Reads the entire contents of a file and returns it as a string.
var content = readFile("data.txt");
if (content != nil) {
print content;
} else {
print "Failed to read file";
}
Opens a file for line-at-a-time reading. init always returns the instance; check f.ok after construction. readLine() returns the next line without the newline (trailing \r is stripped). An empty line is "". nil means EOF, a closed handle, an open failure, or a line longer than 32 MiB. close() releases the OS handle; the GC also closes the handle if you drop the instance.
var f = File("results.ndjson");
if (!f.ok) {
print "cannot open";
} else {
var line = f.readLine();
while (line != nil) {
var obj = parseJSON(line);
line = f.readLine();
}
f.close();
}
Use File for large files. readFile still loads the whole file into one string.
NDJSON (one JSON object per line): stream with File.readLine(), or cache strSplit once — never re-read inside the loop. See NDJSON.md.
Native HTML template renderer (Plan 9 and POSIX). ctx must be an instance whose fields supply values (e.g. a small class with title / items). Expanded {% include %} / {% include_md %} results are cached for the process lifetime — restart after editing templates or included Markdown.
| Syntax | Behavior |
|---|---|
{{ key }} |
Lookup ctx.key, HTML-escaped; missing → empty |
{% for x in items %}…{% endfor %} |
Non-nested loop over an array field |
{% include "file.tpl" %} |
Include relative to the current template’s directory |
{% include_md "file.md" %} |
Render Markdown to HTML and insert (unescaped tags) |
class TplCtx {
init(title, items) {
this.title = title;
this.items = items;
}
}
var html = renderTemplate("public/index.tpl", TplCtx("Hi", ["a", "b"]));
res.html(html);
See examples/template_server/server.lux and tests/test_template.lux.
Convert a Markdown string to an HTML fragment (Plan 9 and POSIX). Supports headings (#–######), paragraphs, *emphasis* / **strong**, [text](url), unordered/ordered lists, fenced code blocks, and inline `code`. Text is HTML-escaped. javascript: URLs are not turned into links.
var html = markdownToHtml("# Hi\n\nHello *world*.");
res.html(html);
Read a Markdown file and convert it with markdownToHtml.
var html = renderMarkdown("notes/todo.md");
res.html(html);
Quick local preview of a directory of .md files:
./lux examples/mdview.lux examples/mdview
# Plan 9: 8.out examples/mdview.lux examples/mdview
# browse http://127.0.0.1:8090/
See examples/mdview.lux, examples/mdview/sample.md, and tests/test_markdown.lux.
Writes content to a file, creating it if it doesn't exist or truncating if it does.
if (writeFile("output.txt", "Hello, World!")) {
print "File written successfully";
}
Appends content to the end of an existing file.
if (appendFile("log.txt", "New log entry\n")) {
print "Log updated";
}
Deletes a file from the filesystem.
if (deleteFile("temp.txt")) {
print "File deleted";
}
Checks if a file exists.
if (fileExists("config.txt")) {
var config = readFile("config.txt");
}
Creates a new directory.
if (createDir("data")) {
print "Directory created";
}
Lists directory contents as a newline-separated string.
var files = listDir(".");
if (files != nil) {
print "Files in current directory:";
print files;
}
Returns the current time in seconds (useful for benchmarking).
var start = clock();
// ... some code ...
var elapsed = clock() - start;
print "Elapsed: " + elapsed + " seconds";
floor is the integer floor. The rest wrap math.h (IEEE NaN/Inf on domain errors; bad arity or type returns nil).
print abs(-3); // 3
print ceil(1.2); // 2
print sqrt(9); // 3
print pow(2, 10); // 1024
print log(1); // 0
print sin(0); // 0
print cos(0); // 1
Lux includes native JSON parsing and serialization for easy data interchange.
Parses a JSON string and returns a Lux value. JSON objects become Lux class instances with properties. JSON arrays become native Lux arrays (index with arr[0], size with arr.length).
var jsonStr = "{\"name\":\"Alice\",\"age\":30,\"active\":true}";
var obj = parseJSON(jsonStr);
if (obj != nil) {
print obj.name; // Alice
print obj.age; // 30
print obj.active; // true
}
// Array example
var arrStr = "[1,2,3,4,5]";
var arr = parseJSON(arrStr);
if (arr != nil) {
print arr.length; // 5
print arr[0]; // 1
print arr[4]; // 5
}
// Nested objects
var nested = "{\"user\":{\"name\":\"Bob\",\"level\":5}}";
var data = parseJSON(nested);
print data.user.name; // Bob
Converts a Lux value to a JSON string. Supports numbers, strings, booleans, nil, and objects (class instances).
JSON in Lux scripts — escaping tip:
- Inside a Lux string literal, every JSON
"must be written as\":parseJSON("{\"name\":\"Alice\"}")orhttpPost(url, "{\"ok\":true}") - Prefer building objects (classes) and calling
toJSON(...)so you never hand-escape quotes. - Do not call
toJSONon a string that is already JSON text — that double-encodes it into a JSON string value ("{\"ok\":true}"instead of{"ok":true}).
class Person {
init(name, age) {
this.name = name;
this.age = age;
}
}
var person = Person("Charlie", 25);
var json = toJSON(person);
print json; // {"name":"Charlie","age":25}
// Round-trip: parse and serialize
var original = "{\"x\":10,\"y\":20}";
var parsed = parseJSON(original);
var serialized = toJSON(parsed);
print serialized; // {"x":10,"y":20}
Practical Example: Save/Load Game Data
// Save game state
class GameState {
init(level, score) {
this.level = level;
this.score = score;
}
}
var state = GameState(5, 1000);
var json = toJSON(state);
writeFile("save.json", json);
// Load game state
var loaded = readFile("save.json");
if (loaded != nil) {
var state = parseJSON(loaded);
print "Level: " + state.level;
print "Score: " + state.score;
}
Lux includes native string parsing primitives for building custom parsers and text manipulation.
Strings can be indexed like arrays for read access. Indexing returns a single-character string.
var s = "hello";
print s[0]; // "h"
print s[1]; // "e"
var i = 0;
while (i < len(s)) {
print s[i];
i = i + 1;
}
String assignment by index is not supported (s[0] = "H" is invalid).
Returns the length of a string in bytes.
var text = "Hello, World!";
print len(text); // 13
Searches for needle in haystack starting at optional start index. Returns the index of the first match, or -1 if not found.
var text = "alpha,beta,gamma";
print strFind(text, "beta"); // 6
print strFind(text, "beta", 0); // 6
print strFind(text, "beta", 7); // -1 (not found after index 7)
print strFind(text, "nothere"); // -1
print strFind(text, ","); // 5 (first comma)
Extracts a substring from start (inclusive) to end (exclusive). Negative or out-of-bounds indices are clamped to valid ranges.
var text = "Hello, World!";
print strSlice(text, 0, 5); // "Hello"
print strSlice(text, 7, 12); // "World"
print strSlice(text, 7, 100); // "World!" (clamped to end)
// Extract between delimiters
var data = "key=value";
var eqIdx = strFind(data, "=");
if (eqIdx != -1) {
var key = strSlice(data, 0, eqIdx);
var value = strSlice(data, eqIdx + 1, len(data));
print "Key: " + key; // "key"
print "Value: " + value; // "value"
}
Checks if pattern starts at position index in text. Useful for efficient pattern matching without creating substrings.
var text = "alpha,beta,gamma";
print strStartsWithAt(text, "alpha", 0); // true
print strStartsWithAt(text, "beta", 6); // true
print strStartsWithAt(text, "beta", 7); // false
print strStartsWithAt(text, ",", 5); // true
Removes leading and trailing ASCII whitespace (space, tab, newline, carriage return).
var text = " Hello, World! \n";
print strTrim(text); // "Hello, World!"
// Parse user input
var input = " alice@example.com\t";
var email = strTrim(input);
print email; // "alice@example.com"
Splits text into an array of strings using separator as the delimiter. If separator is empty, splits into individual characters.
var csv = "alpha,beta,gamma";
var parts = strSplit(csv, ",");
print parts.length; // 3
print parts[0]; // "alpha"
print parts[1]; // "beta"
print parts[2]; // "gamma"
// Split into characters
var word = "abc";
var chars = strSplit(word, "");
print chars.length; // 3
print chars[0]; // "a"
print chars[1]; // "b"
// Parse lines
var multiline = "line1\nline2\nline3";
var lines = strSplit(multiline, "\n");
var i = 0;
while (i < lines.length) {
print "Line " + (i + 1) + ": " + lines[i];
i = i + 1;
}
Decodes one application/x-www-form-urlencoded value. + becomes a space. %HH becomes that byte (%3D is =, %22 is ", %27 is ', %0D is carriage return, %0A is newline, %28 / %29 are parentheses). A % that is not two hex digits is left as %.
print urlDecode("name%3D%22Ada%22"); // name="Ada"
print urlDecode("a+b"); // a b
Parses a raw HTML form body. Splits on & and the first = in each part, then urlDecodes the name and the value. Decode after the split so a value may contain = or &. Duplicate names keep the last value. Read a field with getField.
fun handleSql(req, res) {
var form = parseForm(req.body);
var sql = getField(form, "sql");
if (sql == nil) {
res.status(400);
res.send("missing sql");
return;
}
print sql;
res.send("ok");
}
A textarea named sql with SELECT * FROM t WHERE name = "foo" arrives as sql=SELECT+*+FROM+t+WHERE+name+%3D+%22foo%22. parseForm returns the original SQL, including real line breaks from %0D%0A. Splitting req.body on + cuts the statement on every space and leaves the percent sequences in place.
Practical Example: Custom XML Parser
// Extract all values for a given XML tag
fun extractXmlTag(xml, tagName) {
var results = [];
var openTag = "<" + tagName + ">";
var closeTag = "</" + tagName + ">";
var cursor = 0;
while (cursor < len(xml)) {
var openIdx = strFind(xml, openTag, cursor);
if (openIdx == -1) {
return results;
}
var valueStart = openIdx + len(openTag);
var closeIdx = strFind(xml, closeTag, valueStart);
if (closeIdx == -1) {
return results;
}
var value = strSlice(xml, valueStart, closeIdx);
results = results + [strTrim(value)];
cursor = closeIdx + len(closeTag);
}
return results;
}
var xmlResponse = "<items><item>A</item><item>B</item><item>C</item></items>";
var items = extractXmlTag(xmlResponse, "item");
print items.length; // 3
print items[0]; // "A"
print items[1]; // "B"
Lux includes native array search and sort helpers.
Returns the index of the first matching element, or -1 if not found.
var nums = [10, 20, 30, 20];
print arrayIndexOf(nums, 20); // 1
print arrayIndexOf(nums, 99); // -1
Returns true if the array contains the value.
var names = ["alice", "bob", "carol"];
print arrayContains(names, "bob"); // true
print arrayContains(names, "dave"); // false
Sorts an array in place and returns the same array. Supports all-number arrays or all-string arrays.
var nums = [9, 2, 7, 1, 5];
arraySort(nums);
print nums; // [1, 2, 5, 7, 9]
var words = ["pear", "apple", "orange", "banana"];
arraySort(words);
print words; // ["apple", "banana", "orange", "pear"]
var mixed = [1, "two", 3];
print arraySort(mixed); // nil (mixed types not sortable)
Performs binary search on a sorted array. Returns the index if found, or -1.
var nums = [9, 2, 7, 1, 5];
arraySort(nums); // required before binary search
print arrayBinarySearch(nums, 7); // 3
print arrayBinarySearch(nums, 42); // -1
var words = ["pear", "apple", "orange", "banana"];
arraySort(words);
print arrayBinarySearch(words, "banana"); // 1
Platform: Plan 9 and POSIX (macOS, Linux, OpenBSD).
Float64Array provides a typed double-precision buffer for numerical work. Use it for dot products, moving averages, or when you need faster element access than regular Lux arrays.
Returns true if Float64Array natives are available in this build. Use this to skip numeric tests on older binaries that lack the natives.
if (float64_available()) {
var a = float64_new(100);
// ...
}
Creates a new Float64Array of the given length, initialized to zeros.
var a = float64_new(100);
Returns the element at index. Indices are 0-based. Fails if index is out of bounds.
var val = float64_get(a, 5);
Sets the element at index to value. Returns true on success. Fails if index is out of bounds.
float64_set(a, 0, 1.5);
float64_set(a, i, (i % 100) * 0.01);
Computes the dot product of two Float64Arrays. Both arrays must have the same length. Uses a native C implementation for speed.
var a = float64_new(1000);
var b = float64_new(1000);
// ... fill a and b ...
var sum = float64_dot(a, b);
Sets every element to value and returns the same array.
Returns a new Float64Array with the same elements.
Copies [start, end) (clamped to bounds), same half-open rule as strSlice.
Reductions. mean / min / max return nil on an empty array; sum of empty is 0.
Elementwise sum or product. Same length required. Returns a new array; a and b are unchanged.
BLAS-style y[i] += a * x[i] in place. Same length required. Returns y.
var x = float64_new(3);
var y = float64_new(3);
float64_fill(x, 2);
float64_fill(y, 1);
float64_axpy(0.5, x, y); // y is now [2, 2, 2]
Example — moving average:
var data = float64_new(10000);
var kernel = float64_new(64);
// Fill kernel with 1/64 for uniform average
var i = 0;
while (i < 64) {
float64_set(kernel, i, 1.0 / 64);
i = i + 1;
}
// Compute dot product of sliding window with kernel
var view = float64_new(64);
var idx = 0;
while (idx + 64 <= 10000) {
var k = 0;
while (k < 64) {
float64_set(view, k, float64_get(data, idx + k));
k = k + 1;
}
var avg = float64_dot(view, kernel);
idx = idx + 1;
}
Tip: Reuse a single view buffer in loops instead of allocating a new one each iteration to avoid GC pressure.
Lux is not a pandas/numpy replacement. For moderate tables and small graphs, import modules from lib/ (paths are relative to the process working directory; tests run from posix/ use ../lib/...). Multipart HTTP lives in lib/http.lux (Form). OpenAPI / Swagger UI lives in lib/swagger.lux (Op, swagger). OAuth 2.0 client-credentials lives in lib/oauth.lux (OAuth). MCP Streamable HTTP lives in lib/mcp.lux (mcpMount).
Quoted CSV via native parseCSV(text, [sep]) (Lux parseCSVQuoted is the fallback). DataFrame is column-oriented.
import "../lib/dataframe.lux";
var df = read_csv_text("name,age\nAlice,30\nBob,25\nCarol,27");
df.toNumber("age");
print df.sortBy("age").to_csv();
var gb = df.groupBy("name", "age", "mean");
print gb.to_csv();
var rec = fromRecords([["Ada", 1]], ["name", "id"]);
// SQL: fromRecords(dbQuery(conn, "SELECT name, id FROM t"), ["name", "id"])
Useful methods: head, select, filter (predicate gets a row object), mapColumn, toNumber, sortBy, groupBy(key, value, agg) with count/sum/mean/min/max (groupBy(key, nil, nil) counts), unique, valueCounts, describe, to_csv (RFC 4180 quoting), read_csv_file. getField(obj, name) looks up an instance field by string (for dbQuery rows). parseCSV(text, sep) accepts an optional separator; read_csv_text always uses comma.
Edge-list Graph (set g.directed = true for directed). addNode, addEdge, neighbors, bfs, dfs, toDot() for Graphviz.
import "../lib/graph.lux";
var g = Graph();
g.addEdge("alice", "bob");
g.addEdge("bob", "carol");
writeFile("friends.dot", g.toDot());
See examples/dataframe_prototype.lux and examples/graph_demo.lux.
Library-only wrappers around curl, k6, and Playwright. They write a temp script, run() it, and parse files — no VM changes. Plan 9 can still generate scripts; live .run() needs those binaries.
import "../lib/webtest.lux";
var r = HttpCheck().get("https://example.com/health");
assert(r.status == 200, "health status");
assert(strFind(r.body, "ok") >= 0, "health body");
var k = K6();
k.get("https://example.com/api/items");
k.vus(10);
k.duration("30s");
var s = k.run(); // needs k6 on PATH
assert(s.failed < 0.01, "error rate");
assert(s.p95 < 500, "p95");
var p = Playwright();
p.goto("https://example.com/login");
p.fill("#user", "admin");
p.click("button[type=submit]");
p.text("h1");
var out = p.run(); // needs node + npx playwright
assert(out.ok == true, "playwright");
HttpCheck uses curl (-K config) so you get status / headers / body (ok is 2xx). Headers are a Dict or an array of "Name: value" strings. K6.parseSummary maps p(95) via getField. Playwright queues goto / fill / click / waitFor / text / screenshot then launches one browser. See examples/webtest_demo.lux.
Lux includes HTTP client functions for making web requests on both Plan 9 and POSIX platforms.
Platform Support:
- Plan 9: HTTP and HTTPS (uses native
dial()with libsec TLS) - POSIX: HTTP and HTTPS (uses libcurl)
Makes an HTTP GET request and returns the response body as a string (not a response object — there is no statusCode or .body field).
// HTTPS example (both platforms) — single product object
var response = httpGet("https://fakestoreapi.com/products/1");
if (response != nil) {
print "Received: " + response;
var data = parseJSON(response);
if (data != nil) {
print "Title: " + data.title;
print "Price: " + data.price;
}
} else {
print "Request failed";
}
// HTTP example (both Plan 9 and POSIX)
var httpResp = httpGet("http://httpbin.org/get");
if (httpResp != nil) {
var data = parseJSON(httpResp);
print "URL: " + data.url;
}
Makes an HTTP POST request with JSON body and returns the response. Always sends Content-Type: application/json. For multipart/form-data, use httpRequest with a Form or httpPostForm.
class User {
init(name, email) {
this.name = name;
this.email = email;
}
}
var user = User("Alice", "alice@example.com");
var jsonBody = toJSON(user);
if (jsonBody != nil) {
var response = httpPost("https://api.example.com/users", jsonBody);
if (response != nil) {
print "User created!";
var result = parseJSON(response);
if (result != nil) {
print "ID: " + result.id;
}
}
}
POST multipart/form-data. parts is a Form instance or an array of part instances (name, optional value / path / filename / type). File parts are read from disk in C (length-aware). Extra headers are merged; Content-Type is always set with a boundary.
Prefer the Form helper in lib/http.lux:
import "../lib/http.lux";
class Headers { init() {} }
var form = Form();
form.field("method", "GET");
form.field("name", "legacy");
form.file("file", "script.js", "application/x-javascript");
var headers = Headers();
headers.accept = "application/json";
var resp = httpRequest("POST", "https://api.example.com/scenarios", form, headers);
// or: var resp = form.post(url, headers);
Makes an HTTP PUT request with JSON body and returns the response.
class UpdateData {
init(status) {
this.status = status;
}
}
var update = UpdateData("active");
var jsonBody = toJSON(update);
if (jsonBody != nil) {
var response = httpPut("https://api.example.com/resource/123", jsonBody);
if (response != nil) {
print "Resource updated!";
}
}
Like httpRequest, but delivers the response line by line (NDJSON, Ollama "stream": true). body and headers may be nil. onLine(line) is called without the trailing newline; empty lines are skipped. Return false from onLine to stop. Timeout is 600s (connect 15s). mcpOllamaChat in lib/mcp.lux unwraps Ollama message.content / response deltas.
var text = "";
fun onDelta(delta) {
text = text + delta;
print delta;
}
class Headers { init() {} }
var headers = Headers();
headers.Content_Type = "application/json";
mcpOllamaChat("http://10.0.0.22:11434/api/chat",
"{\"model\":\"qwen2.5-coder:14b\",\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}",
headers, onDelta);
Starts a basic HTTP server listening on the specified port. The server runs in a blocking loop and responds to requests with built-in routes. Press Ctrl+C to stop the server.
Built-in Routes:
GET /→ Returns a hello messageGET/POST /echo→ Echoes back the request method, path, and body- Other paths → Returns 404 Not Found
// Start a server on port 8080
print "Starting HTTP server on port 8080...";
httpServer(8080);
Testing from command line:
# From another terminal or machine:
curl http://localhost:8080/
curl http://localhost:8080/echo
curl -X POST http://localhost:8080/echo -d '{"test":"data"}'Features:
- Listens on all network interfaces (accessible from external machines)
- Automatic Content-Length header parsing for POST bodies
- Returns JSON responses with proper HTTP headers
- Handles multiple sequential connections
- Simple built-in routing
Use Cases:
- Quick HTTP API testing
- Local web service development
- Receiving webhooks
- Simple microservices
- Development/debugging endpoints
Platform Support:
- Plan 9: Uses native
announce(),listen(),accept()system calls - POSIX: Uses standard BSD sockets API (
socket(),bind(),listen(),accept())
Create a configurable HTTP server with user-defined routes. See examples/static_server.lux, examples/template_server/server.lux, examples/vhost_server.lux, and tests/test_http_server_routes.lux.
fun handleHello(req, res) { res.send("Hello from Lux!"); }
/* res.send → text/plain; res.html → text/html; res.json → application/json */
/* res.header / res.begin / res.write / res.event / res.end → extra headers + SSE */
fun handleData(req, res) {
var body = parseJSON(req.body);
if (body == nil) {
res.status(400);
res.send("{\"error\":\"invalid json\"}");
return;
}
print body;
res.status(201);
res.json(body); /* echo parsed JSON, e.g. {"name":"John"} */
}
/* Fixed JSON response (not a Lux object literal — use parseJSON): */
fun handleAck(req, res) {
res.status(201);
res.json(parseJSON("{\"status\":\"received\"}"));
}
var server = Server(8080);
server.workers(4); /* prefork: N processes accept in parallel (default 4; 1 = no fork) */
server.get("/hello", handleHello);
server.post("/data", handleData);
server.static("public"); /* serve GET files from ./public/ */
server.start();
An HTML form (method="post", no JavaScript) sends application/x-www-form-urlencoded, not JSON. req.body still has + for spaces and %HH for other bytes. Use parseForm(req.body) and getField, or urlDecode on a single value. parseJSON stays for JSON posts.
Concurrency (server.workers(n)): Prefork model — after bind/announce, Lux spawns n worker processes (clamped to 1..32; default 4 if unset). Each worker has its own VM copy and runs an accept/handle loop; the parent waits and respawns dead workers. workers(1) keeps a single-process loop (handy for debugging). In-memory mutations are not shared across workers after fork; use files, DB, or external services for shared state. TLS still terminates outside Lux (tlssrv on 9front).
Virtual hosts (many domains, one port): Lux parses the Host header into req.host (port stripped). Use server.vhost(host, root) for per-domain static trees and server.getHost / server.postHost for host-scoped routes. Global get/post still match any Host. Host matching is case-insensitive. GET static files are tried first (vhost root, else server.static), then host-specific routes, then global routes.
fun helloTech(req, res) {
res.json(parseJSON("{\"site\":\"technomancy\"}"));
}
fun helloWill(req, res) {
print req.host;
res.json(parseJSON("{\"site\":\"william\"}"));
}
fun health(req, res) {
res.json(parseJSON("{\"ok\":true}"));
}
var server = Server(8080);
server.vhost("technomancy.site", "/usr/www/sites/technomancy.site");
server.vhost("williamgunnells.com", "/usr/www/sites/williamgunnells.com");
server.getHost("technomancy.site", "/api/hello", helloTech);
server.getHost("williamgunnells.com", "/api/hello", helloWill);
server.get("/health", health); /* any Host */
server.start();
curl -H 'Host: technomancy.site' http://127.0.0.1:8080/
curl -H 'Host: williamgunnells.com' http://127.0.0.1:8080/api/hello9front edge (TLS / www redirects stay outside Lux): run Lux on :8080 behind tlssrv (SNI/acmed certificates). Keep rc-httpd for ACME http-01 on port 80 and www.* → apex redirects; register only apex names with vhost/getHost. See also TODO.md.
res.json notes:
- Pass a value to serialize (
parseJSONobjects, class instances with fields), not pre-built JSON text. res.json("{\"a\":1}")returns a JSON string ("{\"a\":1}"), not an object.Dictdata lives in native storage;res.json(aDict)only sees internal fields (e.g._ptr). UseparseJSON/toJSON,dict.iter(), orres.sendwith a string you build. Seetests/test_dict.lux.
AWS Lambda (Mangum-style): Use the same Server routes without start(). server.handle(method, path, [body], [host], [authorization]) runs one request and returns {statusCode, body, contentType}. lib/mangum.lux maps API Gateway REST (v1), HTTP API / Function URL (v2) events onto that (including Authorization), and writes a Lambda proxy response. The custom runtime in lambda/bootstrap still feeds /tmp/lambda_event.json and posts /tmp/lambda_response.json.
import "../lib/mangum.lux"; /* or "lib/mangum.lux" when cwd is the repo / Lambda task root */
fun handleHome(req, res) {
res.html("<h1>Hello from Lux</h1>");
}
var server = Server(0); /* port unused for handle / Mangum */
server.get("/", handleHome);
/* Local, no socket: */
var page = server.handle("GET", "/");
print page.statusCode; /* 200 */
print page.body;
/* On Lambda (see lambda/handler.lux): */
Mangum(server);
Package lux, lambda/bootstrap, lambda/handler.lux, and lib/mangum.lux so the task cwd is /var/task.
Same routes in both examples (GET / HTML, GET /health JSON, GET/POST /echo):
examples/lambda_web.lux— localserver.start()on 8084;--onceusesserver.handle;Mangumwhen/tmp/lambda_event.jsonexistslambda/handler.lux— Lambda custom-runtime entry (Mangum(server))
See tests/test_mangum.lux.
Middleware (server.use): Register functions with signature (req, res, next). Call next() to continue the chain (more middleware, then the matched route handler). See examples/server_middleware.lux.
fun logger(req, res, next) {
print "Request: " + req.method + " " + req.path;
next();
}
server.use(logger);
Omit next() to short-circuit — send a response yourself and the route handler never runs:
fun requireAuth(req, res, next) {
if (req.path == "/secret") {
res.status(401);
res.send("unauthorized");
return; /* no next() → handler never runs */
}
next();
}
server.use(requireAuth);
OpenAPI / Swagger UI (lib/swagger.lux): swagger(server) mounts FastAPI-style GET /docs (Swagger UI) and GET /openapi.json from the route table. Pass an optional Op as the last argument to get / post / getHost / postHost, or attach one later with swaggerDoc. See examples/swagger_server.lux and tests/test_swagger.lux.
MCP Streamable HTTP (lib/mcp.lux): Point Cline at a dedicated path (/mcp), not /. mcpMount(server, "/mcp", name, version, tools, onCall) answers initialize, notifications/* (202), tools/list, and tools/call with JSON-RPC. GET without SSE is 405, which the spec allows. Buffered res.json is valid Streamable HTTP; use res.begin / res.event / res.end when you want text/event-stream. For Ollama "stream": true, httpStream / mcpOllamaChat call your callback per NDJSON line. See tests/test_mcp.lux, tests/test_http_stream.lux, and examples/mcp/ (ask_devops_assistant plus allow-listed devops.md). The Cline UI may require https://; edit cline_mcp_settings.json to use http://127.0.0.1:8080/mcp.
import "../lib/swagger.lux";
fun handleHealth(req, res) {
res.json(parseJSON("{\"ok\":true}"));
}
fun handleEcho(req, res) {
res.json(parseJSON("{\"ok\":true}"));
}
var server = Server(8085);
server.swaggerTitle = "Demo API"; /* optional; default "Lux API" */
var healthOp = Op("Health check", "ops");
healthOp.example = parseJSON("{\"ok\":true}");
server.get("/health", handleHealth, healthOp);
var echoOp = Op("Echo the request", "echo");
echoOp.body = parseJSON("{\"msg\":\"hi\"}");
echoOp.status = 200;
server.post("/echo", handleEcho, echoOp);
/* After the fact, e.g. from an imported route file: */
server.get("/later", handleEcho);
swaggerDoc(server, "GET", "/later", Op("Registered later", "misc"));
swagger(server);
server.start();
Op(summary, tag) also accepts description, body (example request), example (example response), and status (response code, default 200). Without an Op, the spec still lists the path so Try it out works. /docs and /openapi.json are omitted from the spec. server.swaggerVersion defaults to "1.0.0". Swagger UI loads from a CDN; GET /openapi.json works offline.
OAuth 2.0 (lib/oauth.lux): Client-credentials grant that issues a Bearer token. oa.mount(server) adds POST /oauth/token and checks Authorization: Bearer … on other routes. Token requests and paths in oa.skip (default /oauth/token, /docs, /openapi.json) stay public. A valid token sets req.clientId. See examples/oauth_server.lux and tests/test_oauth.lux.
import "../lib/oauth.lux";
import "../lib/swagger.lux";
fun handleHealth(req, res) {
res.json(parseJSON("{\"ok\":true}"));
}
fun handleSecret(req, res) {
var obj = parseJSON("{\"ok\":true,\"client\":\"\"}");
obj.client = req.clientId;
res.json(obj);
}
var server = Server(8086);
var oa = OAuth("change-me");
oa.addClient("demo", "demo-secret");
oa.skip[oa.skip.length] = "/health";
oa.mount(server);
server.get("/health", handleHealth);
server.get("/secret", handleSecret);
swagger(server); /* /docs Authorize: paste Bearer token, or client credentials */
server.start();
Mint a token, then send it as Bearer:
var g = oa.grant("demo", "demo-secret");
print g.token_type; /* Bearer */
print g.access_token;
var headers = parseJSON("{}");
headers.Authorization = oa.bearer("demo", "demo-secret"); /* "Bearer <token>" */
var resp = httpRequest("GET", "http://127.0.0.1:8086/secret", nil, headers);
curl -s -X POST http://127.0.0.1:8086/oauth/token \
-d '{"grant_type":"client_credentials","client_id":"demo","client_secret":"demo-secret"}'
# {"access_token":"demo.<exp>.<hmac>","token_type":"Bearer","expires_in":3600}
curl -s -H 'Authorization: Bearer <access_token>' http://127.0.0.1:8086/secretJSON or application/x-www-form-urlencoded bodies work on the token endpoint. Tokens are clientId.exp.hmac signed with oa.secret; oa.expiresIn defaults to 3600 seconds. client_id must not contain .. This is machine-to-machine auth, not browser login (no authorization-code redirect). If oa.mount runs before swagger(), /docs advertises HTTP Bearer plus the token URL.
Test from another machine:
curl http://10.0.0.31:8080/hello
curl -H "Content-Type: application/json" -d '{"name":"John"}' http://10.0.0.31:8080/dataController imports: Define server before importing route modules so they can register routes:
var server = Server(8080);
import "routes/user.lux"; /* routes/user.lux calls server.get(...) */
server.start();
Simple persistence: Use globals holding parseJSON results (not {} map literals):
var lastPost = nil;
fun postData(req, res) {
lastPost = parseJSON(req.body);
res.status(201);
res.json(parseJSON("{\"ok\":true}"));
}
fun getData(req, res) {
if (lastPost == nil) {
res.json(parseJSON("{\"data\":null}"));
} else {
res.json(lastPost);
}
}
var server = Server(8080);
server.post("/data", postData);
server.get("/data", getData);
server.start();
Practical Example: Fetch and Process API Data
// Fetch user data from API
var response = httpGet("https://jsonplaceholder.typicode.com/users/1");
if (response != nil) {
var user = parseJSON(response);
if (user != nil) {
print "Name: " + user.name;
print "Email: " + user.email;
print "City: " + user.address.city;
// Save locally
writeFile("user_" + user.id + ".json", response);
}
}
// Post analysis results
class AnalysisResult {
init(userId, score, status) {
this.userId = userId;
this.score = score;
this.status = status;
}
}
var result = AnalysisResult(1, 95, "passed");
var json = toJSON(result);
if (json != nil) {
var postResp = httpPost("https://api.example.com/results", json);
if (postResp != nil) {
print "Results submitted successfully";
}
}
Implementation Notes:
- Plan 9 HTTP Client: Uses native
dial()system call with manual HTTP/1.0 protocol andlibsecfor TLS/HTTPS support. HTTP (port 80) and HTTPS (port 443) both supported with automatic fallback. - POSIX HTTP Client: Uses libcurl library with full HTTP/1.1 and HTTPS support, automatic redirects, and robust error handling.
- HTTP Client (Both): 30-second timeouts (POSIX), automatic
Content-Type: application/jsonheader, returnsnilon failure. - Plan 9 HTTP Server: Uses native
announce(),listen(),accept()system calls with manual HTTP/1.0 protocol parsing. - POSIX HTTP Server: Uses standard BSD sockets (
socket(),bind(),listen(),accept()) with HTTP/1.0 protocol. - HTTP Server (Both): Binds to all interfaces, handles Content-Length parsing, supports sequential connections, returns JSON responses.
DNS lookup and a TCP-connect probe. These do not shell out via run() (dig / ping). netPing is not ICMP echo; it times a TCP connect to a port (same idea as tcping).
Platform Support:
- Plan 9:
netLookupqueries/net/cs;netPingusesdial("tcp!host!port")timed withnsec() - POSIX:
netLookupusesgetaddrinfo;netPinguses a non-blockingconnectwith a 2-second timeout
Resolve a hostname to its first IP address. Returns nil on failure. The first address may be IPv4 or IPv6, depending on resolver order (localhost is often ::1).
var ip = netLookup("example.com");
if (ip != nil) {
print "resolved: " + ip;
}
TCP-connect probe. Returns round-trip milliseconds on success, or -1 if the host is unreachable, the port is closed/filtered, the timeout expires, or the arguments are invalid. port is required (use 80 or 443). On Plan 9 the time includes name resolution.
var ms = netPing("example.com", 443);
if (ms >= 0) {
print "reachable, rtt " + ms + " ms";
} else {
print "down or filtered";
}
Lux includes native AWS S3 integration with AWS Signature Version 4 authentication. This provides boto3-like functionality for direct S3 API access using AWS credentials.
Authentication Support:
- ✅ Permanent credentials (AWS Access Key + Secret Key)
- ✅ Temporary credentials (STS Session Token)
- ✅ AWS Signature Version 4 compliant
- ✅ All AWS regions supported
Platform Support:
- Plan 9: Uses libsec (HMAC-SHA256) with native TLS
- POSIX: Uses OpenSSL (HMAC-SHA256) with libcurl
Lists objects in an S3 bucket. Returns the XML response from S3's ListObjectsV2 API.
Parameters:
bucket: S3 bucket nameaccessKey: AWS access key IDsecretKey: AWS secret access keyregion: AWS region (e.g., "us-east-1", "eu-west-1")prefix(optional): Filter objects by prefixsessionToken(optional): STS session token for temporary credentials
// List all objects in bucket
var bucket = "my-bucket"
var accessKey = "AKIAIOSFODNN7EXAMPLE"
var secretKey = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
var region = "us-east-1"
var response = s3ListObjects(bucket, accessKey, secretKey, region)
if (response != nil) {
print "Objects in bucket:"
print response
}
// List objects with prefix
var logs = s3ListObjects(bucket, accessKey, secretKey, region, "logs/")
if (logs != nil) {
print "Log files:"
print logs
}
// Using STS temporary credentials
var sessionToken = "FwoGZXIvYXdzEBYaDJvZ3..." // From STS
var result = s3ListObjects(bucket, accessKey, secretKey, region, "", sessionToken)
if (result != nil) {
print "Listed with temporary credentials"
}
Downloads an object from S3 and returns its contents as a string.
Parameters:
bucket: S3 bucket namekey: Object key (path in bucket)accessKey: AWS access key IDsecretKey: AWS secret access keyregion: AWS regionsessionToken(optional): STS session token
// Download a file
var content = s3GetObject(bucket, "data/file.txt", accessKey, secretKey, region)
if (content != nil) {
print "File contents:"
print content
// Save locally
writeFile("downloaded.txt", content)
}
// Download JSON configuration
var configKey = "config/app.json"
var configStr = s3GetObject(bucket, configKey, accessKey, secretKey, region)
if (configStr != nil) {
var config = parseJSON(configStr)
if (config != nil) {
print "App version: " + config.version
print "Environment: " + config.environment
}
}
// Using temporary credentials
var fileData = s3GetObject(bucket, "reports/report.csv",
accessKey, secretKey, region, sessionToken)
if (fileData != nil) {
print "Downloaded report with STS token"
}
Uploads content to S3. Returns true on success, false on failure.
Parameters:
bucket: S3 bucket namekey: Object key (destination path)content: Content to upload (as string)accessKey: AWS access key IDsecretKey: AWS secret access keyregion: AWS regionsessionToken(optional): STS session token
// Upload a text file
var content = "Hello from Lux! Timestamp: " + clock()
var success = s3PutObject(bucket, "test/hello.txt", content,
accessKey, secretKey, region)
if (success) {
print "File uploaded successfully"
} else {
print "Upload failed"
}
// Upload JSON data
class DataPoint {
init(timestamp, value, status) {
this.timestamp = timestamp
this.value = value
this.status = status
}
}
var data = DataPoint(clock(), 42, "active")
var jsonStr = toJSON(data)
if (jsonStr != nil) {
var uploaded = s3PutObject(bucket, "data/point.json", jsonStr,
accessKey, secretKey, region)
if (uploaded) {
print "JSON data uploaded to S3"
}
}
// Upload with temporary credentials
var logData = "Application log: System started\n"
var result = s3PutObject(bucket, "logs/app.log", logData,
accessKey, secretKey, region, sessionToken)
if (result) {
print "Log uploaded with STS credentials"
}
Practical Example: S3 Data Pipeline
// Configuration
var bucket = "analytics-bucket"
var accessKey = "YOUR_ACCESS_KEY"
var secretKey = "YOUR_SECRET_KEY"
var region = "us-west-2"
// 1. Download raw data from S3
print "Downloading raw data..."
var rawData = s3GetObject(bucket, "input/data.json", accessKey, secretKey, region)
if (rawData == nil) {
print "Error: Could not download data"
} else {
// 2. Process the data
var data = parseJSON(rawData)
if (data != nil) {
print "Processing " + data.count + " records"
// 3. Generate report
class Report {
init(timestamp, recordCount, status) {
this.timestamp = timestamp
this.recordCount = recordCount
this.status = status
}
}
var report = Report(clock(), data.count, "completed")
var reportJson = toJSON(report)
// 4. Upload results back to S3
if (reportJson != nil) {
var uploaded = s3PutObject(bucket, "output/report.json", reportJson,
accessKey, secretKey, region)
if (uploaded) {
print "Report uploaded successfully"
} else {
print "Error: Upload failed"
}
}
}
}
// 5. List all processed files
print "Listing processed files..."
var files = s3ListObjects(bucket, accessKey, secretKey, region, "output/")
if (files != nil) {
print "Output files:"
print files
}
Use Cases:
- Data pipeline processing (download, transform, upload)
- Configuration management (store/retrieve app configs)
- Log aggregation and analysis
- Backup and restore operations
- File synchronization
- Static site deployment
- Serverless data processing
Security Best Practices:
- ✅ Use STS temporary credentials when possible
- ✅ Store credentials in environment variables or config files (not in code)
- ✅ Use IAM roles with minimum required permissions
- ✅ Rotate access keys regularly
- ✅ Enable S3 bucket encryption
- ✅ Use VPC endpoints for private S3 access
- ✅ Enable CloudTrail logging for S3 API calls
Implementation Notes:
- AWS Signature V4: Full implementation of AWS Signature Version 4 signing algorithm
- HMAC-SHA256: Uses libsec (Plan 9) or OpenSSL (POSIX) for cryptographic operations
- URL Encoding: Automatic URL encoding for object keys with special characters
- SNI Support: Server Name Indication for TLS connections to S3 endpoints
- Payload Hashing: SHA-256 hashing of request payloads for signature calculation
- Timestamp: Uses UTC time in ISO8601 format for request signing
- Error Handling: Returns
nilorfalseon errors (network, auth, S3 errors)
NaN boxing is enabled by default for better performance. This uses a clever bit manipulation technique to store type information within IEEE 754 double values, reducing memory usage and improving cache performance.
To disable NaN boxing, edit common.h and comment out:
#define NAN_BOXING- Flexible concatenation: Mix any type with strings using
+(automatic conversion) - File I/O: Use built-in functions for reading/writing files and managing directories
- JSON support: Parse and serialize JSON for data persistence and configuration files
- HTTP/HTTPS client: Make GET/POST/PUT requests to APIs and web services (both HTTP and HTTPS on both platforms)
- HTTP server: Start a basic HTTP server with
httpServer(port)for local development and testing - AWS S3 integration: Direct S3 access with
s3ListObjects,s3GetObject,s3PutObjectusing AWS credentials or STS tokens - Error handling: File, JSON, HTTP, and S3 operations return
nilorfalseon failure - always check return values - Arrays: Native array support with bracket syntax - create with
[1, 2, 3], access witharr[0], get size witharr.length. Important: Arrays have fixed size - you can only modify existing indices, not add new ones. To build arrays dynamically, pre-allocate with nil values. - Dict class: Use the native
Dictclass for efficient string→string maps and caches (put,get,has,remove,size,clear,iter()). - No exceptions: Use return values to indicate success/failure
- Global scope: All functions and classes are global
- Numeric addition:
+performs addition when both operands are numbers - Truthiness:
falseandnilare falsy, everything else is truthy
print "Hello, World!";
fun fib(n) {
if (n <= 1) return n;
return fib(n - 1) + fib(n - 2);
}
print fib(10); // 55
class Counter {
init() {
this.value = 0;
}
add(n) {
this.value = this.value + n;
return this;
}
get() {
return this.value;
}
}
var c = Counter();
print c.add(5).add(3).get(); // 8
// Write data to a file
var data = "User: Alice\nScore: 100\n";
if (writeFile("score.txt", data)) {
print "Score saved!";
}
// Read it back
var saved = readFile("score.txt");
if (saved != nil) {
print "Loaded data:";
print saved;
}
// Append more data
appendFile("score.txt", "User: Bob\nScore: 95\n");
// List files in directory
createDir("saves");
writeFile("saves/game1.txt", "Level 1 complete");
writeFile("saves/game2.txt", "Level 2 complete");
var files = listDir("saves");
print "Save files:";
print files;
// Lux has no built-in dictionary/hashmap type,
// but you can use object properties for key-value storage
// Simple dictionary
class Dict {
init() {}
}
var config = Dict();
config.host = "localhost";
config.port = 8080;
config.debug = true;
print "Server: " + config.host + ":" + config.port;
// Nested dictionaries for complex data
var user = Dict();
user.name = "Alice";
user.age = 30;
var address = Dict();
address.street = "123 Main St";
address.city = "Portland";
address.zip = "97201";
user.address = address;
print user.name + " lives in " + user.address.city;
// Useful for JSON work - build complex structures
var gameData = Dict();
gameData.player = "PlayerOne";
gameData.level = 5;
gameData.score = 1500;
var inventory = Dict();
inventory.gold = 100;
inventory.potions = 3;
inventory.keys = 1;
gameData.inventory = inventory;
// Serialize to JSON for saving
var json = toJSON(gameData);
if (json != nil) {
writeFile("game.json", json);
print "Game saved!";
}
// Load and access nested data
var loaded = readFile("game.json");
if (loaded != nil) {
var data = parseJSON(loaded);
print "Welcome back, " + data.player;
print "Gold: " + data.inventory.gold;
}
- SPEC.md — language definition (grammar, types, operators, natives)
- tutorial.lux - Start here for a guided tour of all features
- examples.lux - Practical examples including bank accounts, game characters, and data structures
- quickref.lux - Syntax cheatsheet and common patterns
- benchmark.lux - Performance testing
- Bytecode VM: Compiles to bytecode for efficient execution
- Single-pass compiler: Fast compilation with minimal memory overhead
- Mark-and-sweep GC: Automatic memory management with stress testing support
- Upvalue closures: Proper closure support with heap allocation when needed
- Method binding: Fast method invocation with bound method optimization
Source Code (.lux)
↓
Scanner (tokens)
↓
Compiler (bytecode)
↓
VM (execution)
Run the test suite:
8.out chapter28_test.lux
8.out ch29-inherit.lux
Based on "Crafting Interpreters" by Robert Nystrom Ported to Plan 9 C with NaN boxing optimization
All code here fall under MIT License:
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
