process

local process = require("@lute/process")

WARNING

These APIs are still open to future evolution. In new major versions, they may change in backwards incompatible ways.

Summary

Entry	Description
ProcessResult	The result of a completed process, including exit code and captured stdout/stderr.
ProcessRunOptions	Options for process.run:
ProcessSystemOptions	Options for process.system:
Signal	An operating system signal name.
SignalHandle	A handle returned by process.signal. Call :close() to deregister the handler.
StdioKind	How a child process's standard streams should be handled:
args	Command-line arguments passed to the current script, as an array of strings.
cwd	Returns the current working directory as a string.
env	A table of environment variables for the current process.
execPath	Returns the path of the currently running lute executable as a string.
exit	Exits the current process with the given exitcode.
homedir	Returns the current user's home directory as a string.
onSignal	Registers callback to be called whenever signal is delivered to this process.
pid	Returns the PID of the current process.
run	Runs the program given by args[1] with the remaining entries as arguments. Returns the process result including exit code and any captured output.
system	Runs command through the system shell. Returns the process result.

---

Types

ProcessResult

The result of a completed process, including exit code and captured stdout/stderr.

type ProcessResult = {
	stdout: string,
	stderr: string,

	ok: boolean,
	exitcode: number,
	signal: string?,
	timedOut: boolean?,
}

---

ProcessRunOptions

Options for process.run:

• cwd: The working directory for the child process. Defaults to the current working directory.

• stdio: How to handle the child's stdio streams. Defaults to "default".

• env: Environment variables for the child process. If omitted, inherits the parent's environment.

• timeout: Maximum time in seconds to wait for the process. If exceeded, the process group is killed.

type ProcessRunOptions = {
	cwd: string?,
	stdio: StdioKind?,

	env: { [string]: string }?,
	timeout: number?,
}

---

ProcessSystemOptions

Options for process.system:

• system: The shell executable to use. If omitted, uses the platform default ($SHELL on Unix, %COMSPEC% on Windows).

• cwd: The working directory for the child process. Defaults to the current working directory.

• stdio: How to handle the child's stdio streams. Defaults to "default".

• env: Environment variables for the child process. If omitted, inherits the parent's environment.

• timeout: Maximum time in seconds to wait for the process. If exceeded, the process group is killed.

type ProcessSystemOptions = {
	system: string?,
	cwd: string?,
	stdio: StdioKind?,

	env: { [string]: string }?,
	timeout: number?,
}

---

Signal

An operating system signal name.

Only SIGINT and SIGTERM are guaranteed to be supported on all platforms.

Other signals may be unsupported, but will result in no-op behavior when used.

type Signal =

---

SignalHandle

A handle returned by process.signal. Call :close() to deregister the handler.

type SignalHandle = {
	close: (self: SignalHandle) -> (),
}

---

StdioKind

How a child process's standard streams should be handled:

• "default": Capture stdout and stderr to pipes, accessible via ProcessResult.

• "inherit": Pass the parent process's stdio streams through to the child.

• "none": Discard the child's stdio streams.

type StdioKind = "default" | "inherit" | "none"

---

Functions and Properties

process.args

Command-line arguments passed to the current script, as an array of strings.

{ string }

---

process.cwd

Returns the current working directory as a string.

() -> string

---

process.env

A table of environment variables for the current process.

{ [string]: string }

---

process.execPath

Returns the path of the currently running lute executable as a string.

() -> string

---

process.exit

Exits the current process with the given exitcode.

(exitcode: number) -> never

---

process.homedir

Returns the current user's home directory as a string.

() -> string

---

process.onSignal

Registers callback to be called whenever signal is delivered to this process.

Suppresses the default OS behavior (e.g. "SIGINT" will no longer terminate the process).

Returns a handle; call handle:close() to deregister.

(signal: Signal, callback: () -> ()) -> SignalHandle

---

process.pid

Returns the PID of the current process.

() -> number

---

process.run

Runs the program given by args[1] with the remaining entries as arguments. Returns the process result including exit code and any captured output.

(args: { string }, options: ProcessRunOptions?) -> ProcessResult

---

process.system

Runs command through the system shell. Returns the process result.

(command: string, options: ProcessSystemOptions?) -> ProcessResult

---