Lite XL provides a process API to launch external applications. This API is meant to replace
lua's io.popen
and lite's pipe-to-a-file approach.
Advantages of this API includes:
process.start()
may throw errors if it cannot run the program.process.read*
and process.write
functions may throw errors if
To start a process, use process.start(args, options)
.
Here are some of the more useful arguments.
args
: The executable and any arguments, eg: { "sh", "-c", "echo hello world" }
options
: Options for process.start()
env
: A key-value table containing the env. Note that if this is provided,
environment variables will not be inherited.stdin
: Specify where to redirect stdinstdout
: Specify where to redirect stdoutstderr
: Specify where to redirect stderrfor options.std{in,out,err}
, valid values are:
process.REDIRECT_PIPE
(Make it available to subprocess API for reading / writing)process.REDIRECT_DISCARD
(Discard the output. Use this to prevent buffering)process.REDIRECT_STDOUT
(stderr
only, for redirecting stderr
to stdout
)To read from stdout
or stderr
of a process, use process:read_stdout()
and
process:read_stderr()
respectively.
You can specify a numeric argument to them, which will change the size of internal buffer used to read the output.
Alternatively, you could use process:read()
with process.STREAM_STDERR
and process.STREAM_STDOUT
.
Example:
local proc = process.start { "sh", "-c", "echo hello world!" } -- do not use `while proc:running()` if you care about output. -- The process could die and leave data in the buffer -- You should just read until `proc:read_stdout()` returns nil while true do local rdbuf = proc:read_stdout() if not rdbuf then break end -- yay, output end
You can use process:write(data)
to write a string to stdin
.
process:running()
returns a boolean to indicate whether if the process is running.process:wait(time)
also does the same thing, but you specify how long it should wait (or 0 to return immediately).process:terminate()
sends SIGTERM (or Windows equivalent) to the process.process:kill()
sends SIGKILL (or Windows equivalent) to the progress.
Use this only if process:terminate()
cannot kill the process, as it can cause issues.process:pid()
returns the PID of the process.
There are no guarantees for this PID to be correct if the process terminated early.process:returncode()
returns the exit code of the process, if anyprocess:close_stream()
closes stdin
, stdout
or stderr
stream of the process.