The most flexible way to start a process is with either the run-process procedure or the &`{command} syntax for process literals.

Procedure: run-process process-keyword-argument* command

We discuss process-redirect-argument and process-environment-argument later. The process-misc-argument options are just the following:

A simple process literal is a kind of named literal that uses the backtick character (`) as the cname. For example:

&`{date --utc}

This is equivalent to:

(run-process "date --utc")

In general the following are roughly equivalent (using string quasi-literals):

&`[args...]{command}
(run-process args... &{command})

The reason for the “roughly” is if command contains escaped sub-expressions; in that case &` may process the resulting values differently from plain string-substitution, as discussed below.

If you use &sh instead of &` then a shell is used:

&sh{rm *.class}

which is equivalent to:

&`{/bin/sh -c "rm *.class"}

In general, the following are equivalent:

&sh[args...]{command}
&`[shell: #t args...]{command}

The value returned from a call to run-process or a process literal is an instance of gnu.kawa.functions.LProcess. This class extends java.lang.Process, so you can treat it as any other Process object.

#|kawa:1|# (define p1 &`{date --utc})
#|kawa:2|# (p1:toString)
gnu.kawa.functions.LProcess@377dca04
#|kawa:3|# (write p1)
gnu.kawa.functions.LProcess@377dca04

What makes an LProcess interesting is that it is also a blob, which is automatically converted to a string (or bytevector) in a context that requires it. The contents of the blob comes from the standard output of the process. The blob is evaluated lazily, so data it is only collected when requested.

#|kawa:4|# (define s1 ::string p1)
#|kawa:5|# (write s1)
"Wed Jan  1 01:18:21 UTC 2014\n"
#|kawa:6|# (define b1 ::bytevector p1)
(write b1)
#u8(87 101 100 32 74 97 110 ... 52 10)

The display procedure prints it in “human” form, as a string:

#|kawa:7|# (display p1)
Wed Jan  1 01:18:21 UTC 2014

This is also the default REPL formatting:

#|kawa:8|# &`{date --utc}
Wed Jan  1 01:18:22 UTC 2014

When you type a command to a shell, its output goes to the console, Similarly, in a REPL the output from the process is copied to the console output - which can sometimes by optimized by letting the process inherit its standard output from the Kawa process.

To substitute the variable or the result of an expression in the command line use the usual syntax for quasi literals:

(define filename (make-temporary-file))
&sh{run-experiment >&[filename]}

Since a process is convertible a string, we need no special syntax for command substitution:

`{echo The directory is: &[&`{pwd}]}

or equivalently:

`{echo The directory is: &`{pwd}}

Things get more interesting when considering the interaction between substitution and tokenization. This is not simple string interpolation. For example, if an interpolated value contains a quote character, we want to treat it as a literal quote, rather than a token delimiter. This matches the behavior of traditional shells. There are multiple cases, depending on whether the interpolation result is a string or a vector/list, and depending on whether the interpolation is inside quotes.

Smart tokenization only happens when using the quasi-literal forms such as &`{command}. You can of course use string templates with run-process:

(run-process &{echo The directory is: &`{pwd}})

However, in that case there is no smart tokenization: The template is evaluated to a string, and then the resulting string is tokenized, with no knowledge of where expressions were substituted.

You can use various keyword arguments to specify standard input, output, and error streams. For example to lower-case the text in in.txt, writing the result to out.txt, you can do:

&`[in-from: "in.txt" out-to: "out.txt"]{tr A-Z a-z}

or:

(run-process in-from: "in.txt" out-to: "out.txt" "tr A-Z a-z")

A process-redirect-argument can be one of the following:

The default for the error stream (if neither err-to or err-append-to is specified) is equivalent to err-to: 'current.

Note: Writing to a port is implemented by copying the output or error stream of the process. This is done in a thread, which means we don’t have any guarantees when the copying is finished. (In the future we might change process-exit-wait (discussed later) wait for not only the process to finish, but also for these helper threads to finish.)

A here document is a form a literal string, typically multi-line, and commonly used in shells for the standard input of a process. You can use string literals or string quasi-literals for this. For example, this passes the string "line1\nline2\nline3\n" to the standard input of command:

(run-process [in: &{
    &|line1
    &|line2
    &|line3
    }] "command")

Note the use of &| to mark the end of ignored indentation.

Piping the output of one process as the input of another is in principle easy - just use the in: process argument. However, writing a multi-stage pipe-line quickly gets ugly:

&`[in: &`[in: "My text\n"]{tr a-z A-Z}]{wc}

The convenience macro pipe-process makes this much nicer:

(pipe-process
  "My text\n"
  &`{tr a-z A-Z}
  &`{wc})

Syntax: pipe-process input process*

By default the new process inherits the system environment of the current (JVM) process as returned by System.getenv(), but you can override it. A process-environment-argument can be one of the following:

When a process finishes, it returns an integer exit code. The code is traditionally 0 on successful completion, while a non-zero code indicates some kind of failure or error.

Procedure: process-exit-wait process

Procedure: process-exit-ok? process

Procedure: exit [code]

Procedure: emergency-exit [code]

Procedure: make-process command envp

Procedure: system command

Variable: command-parse

Procedure: tokenize-string-to-string-array command