shell

Shell context: standard streams, environment, working directory, invocation identity, and the VFS the whole lot is routed through.

For how byte streams are divided into values when communicating with external programs, see Output mode.

Types

Type	Description
`@Args`	The type of `args`, an immutable sequence.
`@Env`	The type of `env`, which reads, writes, iterates, spreads, and destructures like a `Dict` of variable names and values.
`Stderr`	The process's standard error.
`Stdin`	The process's standard input.
`Stdout`	The process's standard output.
`Vfs`	An execution context: another machine, container, or privilege level.

Functions

`cd() -> fs.Path`

Returns the current strand's working directory.

echo $ cd()

`cd path`

Changes the current strand's working directory.

cd /tmp

Parameters

Name	Type	Description
`path`	`(Str \| fs.Path)`	Directory to change to, resolved against the current one.

`cd[R] path func -> R`

Runs a function with the working directory changed for the duration of the call. The change is undone however the call exits.

cd /var/log do
  run ls

Parameters

Name	Type	Description
`path`	`(Str \| fs.Path)`	Directory to change to, resolved against the current one.
`func`	`(() -> R)`	Function to run in the new directory.

`exec program *args`

Replaces the interpreter with an external program, after shell cleanup.

The program is resolved using the scoped working directory and PATH before execution unwinds, and inherits standard input, output, and error. Arguments use verbatim string conversion.

Available only in the host VFS; use with_host to select it explicitly.

Parameters

Name	Type	Description
`program`	`(Str \| fs.Path)`	Program to execute.
`*args`	`Value`	Program arguments.

Returns

Never returns.

`exit …`

Exits the shell.

Parameters

Name	Type	Description
`code?`	`Int`	Exit status. Defaults to `0`.

Returns

Never returns; raises an interrupt error that unwinds the interpreter.

`line_ending() -> Str`

Returns the line ending native to the current Vfs target: "\r\n" on Windows, "\n" elsewhere.

This is a function rather than a value because the answer follows the VFS target, so it is a question about the current context rather than a constant of the module. Values are never terminated implicitly, so a script that wants native endings asks for them by name.

Example

run cmd stdout: (lines.precrimp(shell.line_ending()))

`vfs_exe() -> (fs.Path | nil)`

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

`with_host[R] func -> R`

Runs a function in the interpreter's original host context, whatever VFS contexts are currently entered.

Parameters

Name	Type	Description
`func`	`(() -> R)`	Function to run.

`with_override[R] func … -> R`

Runs a function with a scoped command-line arguments or program identity.

The two are independent, and an omitted one keeps its current value, so nested calls can override just one part of the invocation identity. Strands created within the call inherit the overrides. Previous values are restored when func returns, however it exits.

Parameters

Name	Type	Description
`func`	`(() -> R)`	Function to run.
`:args?`	`Iterable[Value]`	Arguments seen as `shell.args`, converted with `verbatim`.
`:program?`	`(Str \| fs.Path)`	Identity seen as `shell.program`.

Errors

Exception	Condition
`TypeError`	`args` is not iterable
`TypeError`	`program` is not a string or path

Values

`args`

The command-line arguments of the current invocation.

Example

if shell.args
  echo "first: $(shell.args[0])"

let first ...rest = shell.args
run tool ...rest

`env`

The environment of the current context.

Example

echo $env["HOME"]
env["MY_VAR"] = hello
for name value = env
  echo "$name=$value"

`exe`

The path the host reports for the running dolang executable, as an fs.Path.

Not canonicalized.

`program`

What dolang is executing.

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

`stderr`

A Stderr handle for the process's standard error.

`stdin`

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

`stdout`

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

`VERSION`

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