Conkeror has the ability to launch, and even interact with, external programs.

To call external programs from Conkeror, in most cases, you will need to have ConkerorSpawnHelper set up.

1. Spawn Functions

The high level api to launch shell commands consists of four functions, well, actually two functions and two coroutines. They all accept the two keyword arguments $cwd and $fds, which we will get back to. The ones named with the word "blind" are non-blocking. That is, they launch the process and don't wait for it to return.

1.3. shell_command_blind

If neither of the keyword arguments $cwd or $fds is given, then the call is made without using conkeror-spawn-helper.

1.4. shell_command_with_argument_blind

Variant of shell_command_blind which takes a second positional parameter, "arg", which will be substituted into the command wherever there is a "{}".

2. Keyword Arguments

2.1. $cwd

$cwd is an nsIFile giving the working directory for the shell command.

2.2. $fds

$fds is structure giving file descriptor readers and writers. This is the tricky bit. The fds structure is an object whose keys are the numbered file descriptors. FD 0 will be attached to the program's stdin, FD 1 to its stdout, and FD 2 to its stderr. In the typical case $fds will be an array of two or three elements. What those elements are, we will come to presently.

Each element of $fds is a javascript object that contains one or both of the properties input and output. If you are sending something to the program, that's an output. If you're reading something from the program, that's an input.

The values of these input and output properties are readers and writers, respectively. So let's have some pseudocode of what we know so far: