Program

Function proxy for an external program.

Inherits from: Func

Constructor

Program value

Creates a program proxy.

Parameters

Name	Type	Description
value	(Str | fs.Path)	Program name or path.

Example

let clang = Program "clang++"
clang --version

Methods

(call) *args … -> nil ^{overload 1 of 8}

Runs the program with the supplied command-line arguments.

Output is written to the configured streams. See External Programs for lookup, stream handling and pipeline behavior.

Parameters

Name	Type	Description
:stderr?	(fs.Path | Str | Sinkable[Str] | :STDOUT:)	Destination for standard error, or :STDOUT: to merge it with standard output.
:policy?	BaseDict[{?signal: Signal | Int, ?grace: time.Duration | Int | Float, ?force: Bool}]	Per-launch termination overrides: signal, grace and force, as with_policy takes them.
:mode?	:LINE:	Output framing: Str lines by default, or Bin chunks with :CHUNK:.
*args	Value	Command-line arguments.
<	Iter[Value]
>	Sink[Str]

Errors

Exception	Condition
Error	The program exited unsuccessfully

Example

let git = Program git
git status --short

(call) :mode *args … -> nil ^{overload 2 of 8}

Runs the program, reading the strand's input and writing the strand's output as chunks.

Parameters

Name	Type	Description
:stderr?	(fs.Path | Str | Sinkable[Bin] | :STDOUT:)
:policy?	BaseDict[{?signal: Signal | Int, ?grace: time.Duration | Int | Float, ?force: Bool}]
:mode	:CHUNK:
*args	Value
<	Iter[Value]
>	Sink[Bin]

(call) :stdout *args … -> nil ^{overload 3 of 8}

Runs the program, reading the strand's input and writing stdout: as lines.

Parameters

Name	Type	Description
:stdout	(fs.Path | Str | Sinkable[Str])	Destination for standard output.
:stderr?	(fs.Path | Str | Sinkable[Str] | :STDOUT:)
:policy?	BaseDict[{?signal: Signal | Int, ?grace: time.Duration | Int | Float, ?force: Bool}]
:mode?	:LINE:
*args	Value
<	Iter[Value]

:stdout

A stream receives the bytes as they are, whatever the mode:.

(call) :stdout :mode *args … -> nil ^{overload 4 of 8}

Runs the program, reading the strand's input and writing stdout: as chunks.

Parameters

Name	Type	Description
:stdout	(fs.Path | Str | Sinkable[Bin])
:stderr?	(fs.Path | Str | Sinkable[Bin] | :STDOUT:)
:policy?	BaseDict[{?signal: Signal | Int, ?grace: time.Duration | Int | Float, ?force: Bool}]
:mode	:CHUNK:
*args	Value
<	Iter[Value]

(call) :stdin *args … -> nil ^{overload 5 of 8}

Runs the program, reading stdin: and writing the strand's output as lines.

Parameters

Name	Type	Description
:stdin	(fs.Path | Str | io.Io | Iterable[Value])	Source for standard input.
:stderr?	(fs.Path | Str | Sinkable[Str] | :STDOUT:)
:policy?	BaseDict[{?signal: Signal | Int, ?grace: time.Duration | Int | Float, ?force: Bool}]
:mode?	:LINE:
*args	Value
>	Sink[Str]

:stdin

A stream is read as bytes, even when it is also iterable.

(call) :stdin :mode *args … -> nil ^{overload 6 of 8}

Runs the program, reading stdin: and writing the strand's output as chunks.

Parameters

Name	Type	Description
:stdin	(fs.Path | Str | io.Io | Iterable[Value])
:stderr?	(fs.Path | Str | Sinkable[Bin] | :STDOUT:)
:policy?	BaseDict[{?signal: Signal | Int, ?grace: time.Duration | Int | Float, ?force: Bool}]
:mode	:CHUNK:
*args	Value
>	Sink[Bin]

(call) :stdin :stdout *args … -> nil ^{overload 7 of 8}

Runs the program, reading stdin: and writing stdout: as lines.

Parameters

Name	Type	Description
:stdin	(fs.Path | Str | io.Io | Iterable[Value])
:stdout	(fs.Path | Str | Sinkable[Str])
:stderr?	(fs.Path | Str | Sinkable[Str] | :STDOUT:)
:policy?	BaseDict[{?signal: Signal | Int, ?grace: time.Duration | Int | Float, ?force: Bool}]
:mode?	:LINE:
*args	Value

(call) :stdin :stdout :mode … -> nil ^{overload 8 of 8}

Runs the program, reading stdin: and writing stdout: as chunks.

Parameters

Name	Type	Description
:stdin	(fs.Path | Str | io.Io | Iterable[Value])
:stdout	(fs.Path | Str | Sinkable[Bin])
:stderr?	(fs.Path | Str | Sinkable[Bin] | :STDOUT:)
:policy?	BaseDict[{?signal: Signal | Int, ?grace: time.Duration | Int | Float, ?force: Bool}]
:mode	:CHUNK:
*args	Value

which() -> (fs.Path | nil)

Resolves the program without running it.

Returns

nil when the program is not found.

Example

let git = Program "git"
echo $git.which()