Processes
The process API allows you to spawn processes, capture their output, and wait for them to exit.
Spawning
To spawn a process, create a Command
and spawn
it.
require("pinnacle.process").command({
cmd = "alacritty",
}):spawn()
-- Or
require("pinnacle.process").spawn("alacritty")
Command
s have the following properties:
Property | Type | Description |
---|---|---|
Command | String or String[] | The command and its arguments |
Shell command | String[] | A shell and arguments that gets prepended to the command above |
Envs | Map<String, String> | Environment variables to spawn the command with |
Unique | Bool | Causes the command to not spawn if an instance of it is already running |
Once | Bool | Causes the command to not spawn it has been spawned at any time during the current session |
Pipe std{in,out,err} | Bool | Sets up a pipe so that the config can interact with the process's stdio |
Special spawn options
Unique
To prevent multiple instances of a process from spawning, use the unique
flag.
require("pinnacle.process").command({
cmd = "alacritty",
unique = true,
}):spawn()
-- Or
require("pinnacle.process").spawn_unique("alacritty")
Once
To only spawn a process exactly once, use the once
flag. This is useful for startup programs that you close and don't want respawning when reloading the config.
require("pinnacle.process").command({
cmd = "alacritty",
once = true,
}):spawn()
-- Or
require("pinnacle.process").spawn_once("alacritty")
With shell
Sometimes you may want to spawn something using a shell, for example to enable piping. Using the shell command feature allows you to do this while also allowing once
and unique
to only process the actual command (if you pass the shell as the actual command it will trigger once
and unique
).
require("pinnacle.process").command({
cmd = "echo hello | cat",
shell_cmd = { "bash", "-c" },
}):spawn()
Capturing standard IO
To capture the process's standard IO, you must pipe the descriptors you want to capture:
local child = require("pinnacle.process").command({
cmd = "alacritty",
pipe_stdin = true,
pipe_stdout = true,
pipe_stderr = true,
}):spawn()
If the command spawns successfully and has standard IO, a Child
object will be returned with the process's stdin
, stdout
, and stderr
for those that were piped.
You can run a closure on every outputted line from stdout
and stderr
by calling the appropriate method:
local child = require("pinnacle.process").spawn("alacritty")
if child then
child:on_line_stdout(function(line)
print("stdout: " .. line)
end)
child:on_line_stderr(function(line)
print("stderr: " .. line)
end)
end
Waiting for the process
You can block and wait for the process to exit, additionally capturing its exit code and message.
local child = require("pinnacle.process").spawn("alacritty")
local exit_info = child:wait()