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[T]	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 ^{overload 1 of 3}

Returns the current strand's working directory.

echo $ cd()

cd path ^{overload 2 of 3}

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 ^{overload 3 of 3}

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 -> Never

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 … -> Never

Exits the shell.

Parameters

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

Returns

Never returns. The exit unwinds the interpreter, and catch cannot stop it.

line_ending() -> Str

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

Example

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

render_error error … -> term.Text

Formats an error the way the shell reports an uncaught one.

The error's message is followed by its backtrace: a line for each call, showing the code the call was running, with that code marked. Code already shown for an earlier call isn't shown again.

Parameters

Name	Type	Description
error	Value	Error to format.
:backtrace?	(inspect.Backtrace | nil)	Backtrace to show. By default, that of the exception being handled, and none when there isn't one; nil shows none.

sub[R] block … -> Str

Captures the output of a block as a string.

Everything written is captured as a byte stream, without line decoding or normalization -- including values put into the strand's output, which contribute exactly their own bytes. For the console counterpart, which captures echo and print instead, use term.sub.

Parameters

Name	Type	Description
block	((>std.Sink[std.Value]) -> R)	Block whose output to capture.
:chomp?	Bool	Remove one trailing LF or CRLF. True by default. This is a whole-capture strip, not a per-value one: it removes at most one line ending, from the end of the finished string.

Errors

DataError if the output is not valid UTF-8.

Example

let output = sub do run echo hello
assert_eq $output "hello"

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. Passing program: nil clears the program 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 | nil)	Identity seen as shell.program.

Errors

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

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.

Not canonicalized.

program

What dolang is executing.

• For dolang script.dol, the path of script.dol
• For dolang -m foo.bar, the string "foo.bar"
• In the REPL, nil

stderr

A handle for the process's standard error.

stdin

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

stdout

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

VERSION

The (major, minor, patch) version of the running dolang build.