O Language runtime API

On this page

This reference covers functions registered in the interpreter at revision eb2301c. The bytecode compiler has a separate registry; see execution paths. Argument counts and behaviors below describe the current implementation, including known inconsistencies.

Values and collections

Function	Arguments	Result
`len(value)`	Array, string or integer	Integer count. For an integer, counts its decimal digits including a minus sign.
`first(array)`, `last(array)`	Array	First or last item; empty arrays return `EMPTY`.
`rest(array)`	Array	New array without the first item; empty arrays return `EMPTY`.
`push(array, value)`	Array and value	New array with the value appended.
`push(hash, key, value)`	Hash, key and value	New hash with the entry added or replaced.
`map(fn, array)`	Function and array	Array of callback results for integer elements; non-integer array elements are skipped.
`map(fn, hash)`	Function and hash	Calls the function with each key and value; collects its results into an array.
`itostr(integer)`	Integer	Decimal string.
`atostr(array[, separator])`	Array and optional string	Concatenates item results. The current implementation appends the separator after every item, including the last.
`type(value)`	Runtime value	Runtime type label, such as `INTEGER` or `ARRAY`.
`inspect(values…)`	Any number of values	Prints each inspection form and returns `EMPTY`.
`getval(collection, key)`	Intended for hash/string or array/integer	Argument validation is inconsistent and the implementation can index a missing second argument. Avoid using this helper. Use `collection[key]` instead.

Hash indexing supports string, integer and boolean keys. Missing keys and out-of-range array indexes return NULL.

Console and text

Function	Arguments	Result
`output(format, values…)`	Format string followed by optional values	Writes formatted text and a newline; returns `EMPTY`. Formatting follows Go’s `fmt.Sprintf` rules.
`input(prompt)`	Prompt string	Writes the prompt and reads one line from standard input.
`replace(text, find, replacement)`	Three strings	String with every matching substring replaced.
`regexp_check(pattern, text)`	Two strings	Boolean match result. Invalid patterns return a runtime error.
`regexp_find(pattern, text)`	Two strings	Array of matching substrings.
`colorize(text, color[, background])`	Text, color name and optional boolean	Terminal-colored string; true selects background coloring.
`rand(max[, alphabet])`	Integer and optional string	Integer from zero through max, inclusive; with an alphabet, returns max + 1 randomly selected characters.

Files and environment

Function	Arguments	Result or behavior
`read(path)`	String path	File contents as a string; read errors become an empty string.
`write(path, contents)`	Two strings	Creates the file if needed and returns a boolean.
`remove(path)`	String path	Removes a file and returns a boolean.
`mkdir(path)`, `rmdir(path)`	String path or array of paths	Creates or removes directories; returns `EMPTY`.
`finfo(path)`	String path	Hash containing `name`, `size`, `isdir`, `perm` and `date`.
`chmod(path, mode)`	String path and integer mode	Calls host chmod and returns true; the current wrapper discards the host error.
`exist(path)`	String path	Boolean from the host filesystem stat call.
`wdir()`, `chdir(path)`	No arguments; or a directory string	Current working directory, or changes it and returns the resulting path.
`renderf(path, values)`	Template path and hash	Replaces literal `{% key %}` markers with hash values.
`sysenv()`	No arguments	Hash of environment names and values.
`sysenv(key)`	String key	Reads an environment value.
`sysenv(key, value)`	Two strings	Sets a process environment value and returns it.
`args(index)`	Integer	Process argument at the supplied index; index zero is the executable path. An unavailable index returns an empty string.
`fwatch(path, fn)`	Path string and function	Registers a filesystem watcher and invokes the callback when a change is reported.

File, environment and directory calls operate on the host process. They are not sandboxed.

JSON, XML and web

Function	Arguments	Result or behavior
`json(value)`	Runtime value	JSON string.
`jsonp(text)`	JSON string	Parsed runtime value.
`jsonf(path)`	File path	Reads and parses JSON.
`xmlp(text)`	XML string	Parsed runtime value.
`xmlf(path)`	File path	Reads and parses XML.
`webserver(port, routes)`	Integer/string port and route hash, route object, array or string	Starts the built-in HTTP server. The route hash’s method/response options are described in web projects.

The web server binds on the supplied port. Review routes and file-upload settings before exposing it to a network.

Processes and sockets

Function	Arguments	Result or behavior
`open(target, strings…)`	Target plus optional strings	Asks the host’s default opener to open the target.
`exec(command, strings…)`	Command and optional strings	Runs a process and returns a process object with PID and captured output. Additional strings are currently combined into one argument.
`sh_exec(command, strings…)`	Shell command text	Executes through `sh -c`; input is executable shell code.
`cmd_exec(command, strings…)`	Command text	Executes through `cmd.exe /c` on Windows.
`run(command, strings…)`	Program name and strings	Uses the host process replacement call; it does not return on success.
`proc_out(process…)`, `proc_pid(process…)`	Process objects	Arrays of captured output or process IDs.
`proc_kill(process)`	Process object	Sends a kill request to the associated process.
`sock_send(socket, message)`	Socket object and string	Sends over the socket’s TCP/UDP connection and returns response text.
`sock_listen(socket, responses[, default, …])`	Socket, hash of response strings and optional values	Starts a blocking TCP/UDP listener.
`quit()`, `exit()`	No arguments	Terminates the process.

Process and shell APIs execute host commands. Do not run unreviewed source or project jobs.

Math, encoding and low-level calls

Function	Arguments	Result or limitation
`math_cos(x)`, `math_sin(x)`, `math_tan(x)`, `math_log(x)`	Integer or float	Result as a float.
`math_abs(x)`	Integer or float	Absolute value as a float.
`math_sum(start, end, value)`	Integer bounds and array or function	Source-level range helper; its reduction behavior differs by branch and should be checked before relying on a numeric result.
`encrypt(key, text)`, `decrypt(key, text)`	Two strings	Delegates to the runtime crypto helper. Review its implementation and format before using it for stored data.
`hash_encode(“base64”, text)`	Encoding name and string	Base64 text.
`hash_encode(“md5”, text)`	Encoding name and string	MD5 hex digest; not suitable for password storage.
`hash_decode(“base64”, text)`	Encoding name and string	Decoded Base64 text.
`hash_decode(“md5”, text)`	Encoding name and string	Unsupported by the current decoder.
`asm(instruction, destination, …)`	Assembly text and destination	Calls the native assembly helper; behavior is host- and implementation-dependent.

Database helpers

The interpreter provides database(type, connection), where the current type values are postgres, mysql, sqlite3 and internal. Create a model with model(database, name, columns), where columns is a hash.

Function	Role and current boundary
`migrate(model)`	Creates the SQL model schema; internal storage does not implement migration.
`fetch(model, criteria)`	Fetches matching rows/records.
`create(model, values)`	Creates a record from a hash.
`update(model, criteria, values)`	Updates matching records; argument-count validation is inconsistent in the SQL branch.
`delete(model, criteria)`	Deletes matching records.
`drop(model)`, `truncate(model)`	SQL operations; not implemented by the internal store.
`query(model, sql[, parameters])`	SQL query; raw queries are not supported by the internal store.
`search(model, criteria)`	Internal-store search; SQL backends do not support this branch.

The runtime’s package, evaluator and compiler source are the authoritative reference for backend-specific argument shapes. This API is source documentation, not a claim that all functions are interchangeable across execution paths.