steel/process

child-stderr

Get a handle to the stderr handle of the child process. The process must have been started with the with-stderr-piped option for this to be available, otherwise stderr will be inherited. This will return false if the handle has already been consumed.

(child-stderr subprocess) -> (or input-port? #false)

subprocess : ChildProcess?

child-stdin

Get a handle to the stdin handle of the child process. The process must have been started with the with-stdin-piped option for this to be available, otherwise stdin will be inherited. This will return false if the handle has already been consumed.

(child-stdout subprocess) -> (or input-port? #false)

subprocess : ChildProcess?

child-stdout

Get a handle to the stdout handle of the child process. The process must have been started with the with-stdout-piped option for this to be available, otherwise stdout will be inherited. This will return false if the handle has already been consumed.

(child-stdout subprocess) -> (or output-port? #false)

subprocess : ChildProcess?

(define handle (~> (command "/bin/ls" '())
                   with-stdout-piped
                   spawn-process
                   unwrap-ok))
(read-port-to-string (child-stdout handle)) ;; The resulting string

command

Create a CommandBuilder from a command and a list of arguments. Used to spawn a subprocess.

(command cmd args) -> CommandBuilder?

• cmd : string?
• args : (listof string?)

> (spawn-process (command "echo" (list "hello" "world")))

kill

Terminate the subprocess.

(subprocess-kill subprocess)

subprocess : ChildProcess?

process-wait

Alias of wait.

set-current-dir!

Alias of with-current-dir.

set-env-var!

Alias of with-env-var.

set-piped-stdout!

Equivalent to set-stdout-piped!: connects the spawned child’s stdin, stdout, and stderr to pipes. Returns the command builder.

(set-piped-stdout! process) -> CommandBuilder?

• process : CommandBuilder?

set-stdout-piped!

Configures the command builder so that the spawned child’s stdin, stdout, and stderr are all connected to pipes, letting the parent process read from and write to them. Returns the command builder.

(set-stdout-piped! process) -> CommandBuilder?

• process : CommandBuilder?

spawn-process

Spawn the given process. Returns a result indicating whether the process was able to be spawned.

(spawn-process process) -> (Result? ChildProcess?)

• process : CommandBuilder?

> (require "steel/result")
> (define spawned (spawn-process (command "/bin/ls" '()))) ;; => (Ok #<steel::primitives::process::ChildProcess>)
> (define child (unwrap-ok spawned))

subprocess-kill

Alias of kill.

wait

Wait for the subprocess to finish. Returns a result with the status code of the awaited subprocess.

(wait process) -> (Result? int?)

• process : ChildProcess?

> (~> (command "echo" (list "hello"))
      spawn-process
      unwrap-ok
      wait)

wait->stdout

Wait for the subprocess to finish, capturing its stdout. Returns a result holding everything the process wrote to stdout, decoded as a UTF-8 string. The process must have been started with stdout piped (for example via with-stdout-piped) for this to capture any output.

(wait->stdout process) -> (Result? string?)

• process : ChildProcess?

> (~> (command "echo" (list "hello"))
      with-stdout-piped
      spawn-process
      unwrap-ok
      wait->stdout)

which

Searches the directories listed on the PATH environment variable for the given executable, returning its absolute path as a string, or #false if it cannot be found.

(which binary) -> (or string? #false)

• binary : string?

> (which "ls") ;; => "/bin/ls"
> (which "some-nonexistent-binary") ;; => #false

with-cleared-env-vars

Removes all environment variables for the child.

(with-cleared-env-vars process) -> CommandBuilder?

• process - CommandBuilder?

> (define pb (command "echo" (list "hello")))
> (~> (command "echo" (list "hello"))
      (with-cleared-env-vars "FOO")
      spawn-process
      unwrap-ok
      wait)

with-current-dir

Sets the current directory for the child. set-current-dir! is an alias.

(with-current-dir process dir) -> CommandBuilder?

• process - CommandBuilder?
• dir - string?

> (define pb (command "echo" (list "hello")))
> (with-current-dir pb "/home/foo")
> (~> (command "echo" (list "hello"))
      (with-current-dir "/home/foo")
      spawn-process
      unwrap-ok
      wait)

with-env-var

Sets an environment variable for the child. set-env-var! is an alias.

(with-env-var process key value) -> CommandBuilder?

• process - CommandBuilder?
• key - string?
• value - string?

> (define pb (command "echo" (list "hello")))
> (~> (command "echo" (list "hello"))
      (with-env-var "FOO" "BAR")
      spawn-process
      unwrap-ok
      wait)

with-stderr

Redirect stderr from the process to the given port

(with-stderr process port) -> CommandBuilder?

• process : CommandBuilder?
• port : (and output-port? file-port?)

> (define output (open-output-file "test.txt"))
> (~> (command "echo" (list "hello"))
      (with-stderr output)
      spawn-process
      unwrap-ok
      wait)

with-stderr-piped

Constructs a pipe to be arranged to connect to stderr.

(with-stderr-piped process) -> CommandBuilder?

• process : CommandBuilder?

> (~> (command "echo" (list "hello"))
      with-stderr-piped
      spawn-process
      unwrap-ok
      wait)

with-stdin

Redirect stdin from the process to the given port

(with-stdin process port) -> CommandBuilder?

• process : CommandBuilder?
• port : (and input-port? file-port?)

> (define output (open-input-file "test.txt"))
> (~> (command "echo" (list "hello"))
      (with-stdin output)
      spawn-process
      unwrap-ok
      wait)

with-stdin-piped

Constructs a pipe to be arranged to connect to stdin.

(with-stdin-piped process) -> CommandBuilder?

• process : CommandBuilder?

> (~> (command "echo" (list "hello"))
      with-stdin-piped
      spawn-process
      unwrap-ok
      wait)

with-stdout

Redirect stdout from the process to the given port

(with-stdout process port) -> CommandBuilder?

• process : CommandBuilder?
• port : (and output-port? file-port?)

> (define output (open-output-file "test.txt"))
> (~> (command "echo" (list "hello"))
      (with-stdout output)
      spawn-process
      unwrap-ok
      wait)

with-stdout-piped

Constructs a pipe to be arranged to connect to stdout.

(with-stdout-piped process) -> CommandBuilder?

• process : CommandBuilder?

> (~> (command "echo" (list "hello"))
      with-stdout-piped
      spawn-process
      unwrap-ok
      wait)

without-env-var

Removes an environment variable for the child.

(with-env-var process key) -> CommandBuilder?

• process - CommandBuilder?
• key - string?

> (define pb (command "echo" (list "hello")))
> (~> (command "echo" (list "hello"))
      (without-env-var "FOO")
      spawn-process
      unwrap-ok
      wait)

ChildProcess?

CommandBuilder?

command-builder?

subprocess?