-- Copyright 2007-2025 Mitchell. See LICENSE.
-- This is a DUMMY FILE used for making LuaDoc for built-in functions in the os table.

--- Extends Lua's `os` library to provide process spawning capabilities.
-- @module os

--- Spawns an interactive child process *cmd* in a separate thread, returning a handle to that
-- process.
-- On Windows, *cmd* is passed to `cmd.exe`: `%COMSPEC% /c [cmd]`.
-- @param cmd A command line string that contains the program's name followed by arguments to
--	pass to it. `PATH` is searched for program names.
-- @param[opt] cwd Optional current working directory (cwd) for the child process. When omitted,
--	the parent's cwd is used.
-- @param[opt] env Optional map of environment variables for the child process. When omitted,
--	Textadept's environment is used. In order to create a new environment that inherits
--	from Textadept's, you can spawn 'env' on macOS and Linux, or 'set' on Windows, and
--	iterate over output matches of "key=value" pairs (one per line), assigning them to the
--	new environment table.
-- @param[opt] stdout_cb Optional Lua function that accepts a string parameter for a block of
--	standard output read from the child. Stdout is read asynchronously in 1KB or 0.5KB
--	blocks (depending on the platform), or however much data is available at the time.
-- @param[optchain] stderr_cb Optional Lua function that accepts a string parameter for a block
--	of standard error read from the child. Stderr is read asynchronously in 1KB or 0.5kB
--	blocks (depending on the platform), or however much data is available at the time.
-- @param[optchain] exit_cb Optional Lua function that is called when the child process
--	finishes. The child's exit status is passed.
-- @return proc or nil plus an error message on failure
-- @usage os.spawn('lua ' .. buffer.filename, print)
-- @usage proc = os.spawn('lua -e "print(io.read())"', print)
--	proc:write('foo\n')
-- @function spawn

--- A spawned process.
-- @type spawn_proc

--- Returns the status of process *spawn_proc*, which is either "running" or "terminated".
-- @return "running" or "terminated"
function spawn_proc:status() end

--- Blocks until process *spawn_proc* finishes (if it has not already done so) and returns its
-- status code.
-- @return integer status code
function spawn_proc:wait() end

--- Reads and returns stdout from process *spawn_proc*, according to string format or number *arg*.
-- Similar to Lua's `io.read()` and blocks for input. *spawn_proc* must still be running. If
-- an error occurs while reading, returns `nil`, an error code, and an error message.
-- Ensure any read operations read all stdout available, as the stdout callback function passed
-- to `os.spawn()` will not be called until the stdout buffer is clear.
-- @param[opt='l'] arg Optional argument similar to those in Lua's `io.read()`. The default is
--	to read a line.
-- @return string of bytes read
function spawn_proc:read(arg) end

--- Writes string input to the stdin of process *spawn_proc*.
-- Note: On Linux when using the GTK or terminal version, if more than 65536 bytes (64K) are
-- to be written, it is possible those bytes need to be written in 65536-byte (64K) chunks,
-- or the process may not receive all input. However, it is also possible that there is a limit
-- on how many bytes can be written in a short period of time, perhaps 196608 bytes (192K). The
-- Qt version does not appear to have this limitation.
-- @param ... Standard input for *spawn_proc*.
function spawn_proc:write(...) end

--- Closes standard input for process *spawn_proc*, effectively sending an EOF (end of file) to it.
function spawn_proc:close() end

--- Kills running process *spawn_proc*, or sends it Unix signal *signal*.
-- @param[opt=9] signal Optional Unix signal to send to *spawn_proc*. The default is to kill
--	the process (`SIGKILL`).
function spawn_proc:kill() end
