shell

The shell module provides shell-context values and functions.

Types

Name	Description
`Vfs`	Execution context handle
`Stdin`	Handle for the process's standard input
`Stdout`	Handle for the process's standard output
`Stderr`	Handle for the process's standard error

Functions

`with_io_mode mode func ...`

Runs a callable with the current strand's adapter I/O mode set for the duration of the call. This controls behavior when using Iter or Sink adapters for anonymous byte/character-stream interfaces, such strand input or outputs connected to stdio or an external program.

In :LINE: mode, iterator adapters decode UTF-8, split input on line boundaries, and yield Str values with either an LF or CRLF line ending removed. Sink adapters append the target platform's line ending to the string form of each value. Interpreter stdin/stdout/stderr always use the host's native line ending. This is the default mode.

In :CHUNK: mode, iterator adapters yield arbitrary-sized Bin values. Sink adapters write the string form of each value without adding a newline.

Sink adapters always write Bin values verbatim with no line ending regardless of mode.

The I/O mode is only used when translation between a byte stream and discrete Do values is required. For example, adjacent external processes in a pipeline communicate directly in raw bytes.

Opened file handles always use line/chunk mode according to whether the b mode was specified during open, not the strand-local mode.

Parameters:

Name	Type	Description
`mode`	`sym`	`:LINE:` or `:CHUNK:`
`func`	callable	Block to run
`...`		Additional arguments passed to `func`

Returns: Return value of func.

let chunks = []
with_io_mode :CHUNK: do run gzip -c stdin: ["hello world"] stdout: $chunks

assert (chunks[0].starts_with b"\x1f\x8b")

`exit code?`

Exits the current shell with the given status code.

Parameters

Name	Type	Description
`code`	`Int`	exit status (default: 0)

Returns

never returns; raises an interrupt error

`cd path? func?`

With no arguments, returns the current working directory. With a path, changes the current working directory. If a callable is also provided, the directory is changed only for the duration of that call, then restored.

Parameters

Name	Type	Description
`path`	`Str`\|`Path`	directory path
`func`		callable to run in the new directory

Returns

Current working directory (no arguments), or result of func.

`with_host func ...args`

Executes a callable in the interpreter's original host context, regardless of the current or nested VFS contexts.

Parameters

Name	Type	Description
`func`	func	Block to execute in fresh host context
`args`		Additional arguments to pass to `func`

Returns

Return value of the executed callable

`with_override func :args? :program?`

Runs func with scoped command-line arguments or program identity. Strands created within the call inherit the overrides.

Parameters:

Name	Type	Description
`func`	callable	Block to execute
`args`	`Iterable`?	Values converted with `arg`
`program`	`Str`?\|`Path`?	Program identity

Returns: Return value of func.

args: and program: are independent. An omitted argument retains its current value, so nested calls can override only one part of the invocation identity. The previous values are restored when func returns or raises an error.

Errors:

Raises TypeError if args is not iterable.
Raises TypeError if program is not a string or path.

`vfs_exe()`

Returns the current executable reported by the active VFS context, or nil when running on the host.

Returns

fs.Path or nil.

`env overrides func`

Runs func with scoped environment overrides. Keys may be strings or symbols. nil unsets a variable and :INHERIT: captures its current strand value.

Parameters:

Name	Type	Description
`overrides`	`Dict`	Environment overrides
`func`	callable	Block to run

Values

`stdin`

A Stdin handle for the process's standard input, and initial input for the main strand.

`stdout`

A Stdout handle for the process's standard output, and initial output for the main strand.

`stderr`

A Stderr handle for the process's standard error output.

`env`

An object for accessing environment variables.

`args`

An immutable Args sequence containing the command-line arguments for the current invocation.

`program`

Identifies what dolang is executing.

For dolang script.dol, this is an fs.Path for script.dol.
For dolang -m foo.bar, this is the string "foo.bar".
In the REPL, this is nil.

`exe`

An fs.Path containing the path returned by the host for the current dolang executable. The path is not automatically canonicalized.

`VERSION`

A (major, minor, patch) Tuple with the version of the running dolang build.