Process API

Cross-platform process management — spawn child processes, capture output, manage I/O, environment variables, and PTY support.

Overview

The Process API provides flexible I/O control (pipe, inherit, null, pty), non-blocking reads, Buffer integration for efficient IPC, signal handling (Unix), PTY pseudo-terminal support (cross-platform), and full environment variable management.

Process Spawning

ProcessSpawn(command, args?, options?)

Spawns a new child process and returns a Process object.

Returns: Process object, or map with error field if spawn fails.

var proc = ProcessSpawn("ls", ["-la", "/tmp"])

var proc = ProcessSpawn("python3", ["script.py"], {
    cwd: "/home/user/project",
    stdin: "pipe",
    stdout: "pipe",
    stderr: "pipe"
})
ProcessExec(command, args?, options?)

Executes a command and waits for completion.

Returns: Map with stdout, stderr, exitCode, and optionally error.

var result = ProcessExec("git", ["status"])
print("Output: " + result.stdout)
print("Exit code: " + str(result.exitCode))

if (result.exitCode != 0) {
    print("Error: " + result.stderr)
}

I/O Operations

proc.write(data)

Writes a string to the process's stdin.

proc.writeBuffer(buffer)

Writes data from a Buffer to stdin. Returns number of bytes written.

proc.read()

Reads available data from stdout (blocking).

proc.readErr()

Reads available data from stderr (blocking).

proc.readNonBlock()

Reads available data from stdout without blocking. Returns empty string if no data.

proc.readToBuffer(buffer)

Reads stdout data directly into a Buffer. Returns number of bytes read.

proc.closeStdin()

Closes the stdin pipe, signaling EOF to the child process.

piping data
var proc = ProcessSpawn("sort", [])
proc.write("banana\n")
proc.write("apple\n")
proc.write("cherry\n")
proc.closeStdin()

var output = proc.read()
print(output)  // Sorted output

Process Control

proc.kill(signal?)

Sends a signal to the process (Unix) or terminates it (Windows). Default: "SIGTERM".

Unix signals: "SIGTERM", "SIGKILL", "SIGINT", "SIGHUP", "SIGQUIT", "SIGUSR1", "SIGUSR2", "SIGSTOP", "SIGCONT".

proc.wait()

Waits for the process to exit. Returns exit code.

proc.poll()

Checks if the process has exited without blocking. Returns exit code or null.

Process Information

proc.isRunning()

Returns true if the process is still running.

proc.getPid()

Returns the process ID (PID).

proc.getExitCode()

Returns the exit code if exited, null otherwise.

Static Utility Functions

Environment Variables

processEnv(key)

Gets an environment variable value. Returns null if not set.

processSetEnv(key, value)

Sets an environment variable for the current process and future children.

processEnvAll()

Gets all environment variables as a map.

Working Directory

processCwd()

Gets the current working directory.

processSetCwd(path)

Changes the current working directory.

Process Info

processPid()

Gets the PID of the current process.

processParentPid()

Gets the parent PID (Unix only, returns null on Windows).

processExit(code?)

Exits the current process with the specified exit code (default: 0).

PTY Mode

Use PTY mode for interactive applications that need terminal control. Cross-platform: native PTY on Unix, ConPTY on Windows 10+.

interactive shell
var shell = ProcessSpawn("bash", ["-i"], {
    stdin: "pty",
    stdout: "pty"
})

shell.write("ls --color=auto\n")
sleep(100)
var output = shell.readNonBlock()
print(output)

shell.write("exit\n")
shell.wait()

Examples

Git Wrapper

func git(args) {
    var result = ProcessExec("git", args)
    if (result.exitCode != 0) {
        print("Git error: " + result.stderr)
        return null
    }
    return result.stdout
}

var status = git(["status", "--short"])
print(status)

Non-Blocking Monitor

var proc = ProcessSpawn("./long_task", [])
print("Started PID: " + str(proc.getPid()))

while (proc.isRunning()) {
    var output = proc.readNonBlock()
    if (length(output) > 0) {
        print("[TASK] " + output)
    }
    sleep(100)
}

print("Exit code: " + str(proc.getExitCode()))

Platform Notes