ilusm.dev

host

Host syscall bridge - a clean, stable API over raw __sys_*, __jsn_*, and __io_* dunder names. Every function delegates to exactly one host syscall. Programs should use host rather than calling dunders directly.

Load with: use host

What this module does

host is the thin abstraction layer between pure ilusm code and the C stub that embeds the ilusm runtime. It gives every syscall a stable, readable name under the host namespace. Higher-level modules like fs, env, and daem are built on top of host.

Quick example

use host

# File I/O
src = host.read("input.txt")
host.write("output.txt", src)
host.append("log.txt", "started\n")

# Process info
prn(host.getcwd())
prn(host.getpid())
prn(host.args())
prn(host.platform())  # "linux" / "darwin" / "windows"

# Time
t = host.time()   # milliseconds since epoch
host.sleep(500)   # sleep 500 ms

# JSON
j = host.json_enc({x: 1})
prn(host.json_dec(j))

# Channels
ch = host.chan_new(10)
host.chan_send(ch, "hello")
prn(host.chan_recv(ch))

Functions

File I/O

host.read(path)

Read file contents as a string.

host.write(path, data)

Write (overwrite) a file.

host.append(path, data)

Append to a file.

host.exists(path)

Returns tru if the path exists.

host.stat(path)

Returns file stat metadata.

host.isdir(path)

Returns tru if the path is a directory.

host.readdir(path)

Returns a list of directory entries.

host.mkdir(path)

Creates a directory.

host.remove(path)

Removes a file or directory.

host.realpath(path)

Resolves a path to its canonical absolute form.

Process and environment

host.time()

Current time in milliseconds since epoch.

host.sleep(ms)

Sleep for ms milliseconds.

host.args()

Command-line arguments list. Checks host context first, then __sys_args.

host.getenv(k)

Gets environment variable k. Checks host context first.

host.setenv(k, v)

Sets environment variable k to v.

host.getcwd()

Current working directory.

host.chdir(path)

Change the current working directory.

host.getpid()

Current process ID.

host.exit(code)

Exits the process with code.

host.spawn(thunk)

Spawns a concurrent task.

host.wait(handle)

Waits for a spawned task to complete.

host.platform()

Platform string from ILUSM_PLATFORM env var, or "unknown".

host.arch()

Architecture string from ILUSM_ARCH env var, or "unknown".

JSON, I/O, HTTP, and crypto

host.json_enc(v)

Encodes v to a JSON string.

host.json_dec(s)

Parses a JSON string to an ilusm value.

host.stdout(s)

Writes s directly to stdout.

host.readline()

Reads one line from stdin.

host.http_get(url)

Issues an HTTP GET request (optional - stub may error if not supported).

host.http_post(url, body)

Issues an HTTP POST request.

host.random(n)

Returns n cryptographically random bytes.

host.sha256(data)

Returns the SHA-256 digest of data.

Channels

host.chan_new(cap)

Creates a buffered channel with capacity cap.

host.chan_send(ch, v)

Sends value v to channel ch.

host.chan_recv(ch)

Receives from channel ch.

host.chan_close(ch)

Closes channel ch.

Notes

  • HTTP and crypto functions are optional - the host stub may return errors if not compiled in.
  • Requires host_run_ctx.