diff options
author | mitchell <70453897+667e-11@users.noreply.github.com> | 2018-10-14 19:50:17 -0400 |
---|---|---|
committer | mitchell <70453897+667e-11@users.noreply.github.com> | 2018-10-14 19:50:17 -0400 |
commit | 5e86b286cf366e0db1a361d36dba4dac6d6dd843 (patch) | |
tree | 94a27c66408588e218e965e5ec55528f2671f372 /core/.os.luadoc | |
parent | fca69ee9e7b7593005d6692911dfa2d081759762 (diff) |
Experimentally move external lspawn module into Lua os module as a patch.
Diffstat (limited to 'core/.os.luadoc')
-rw-r--r-- | core/.os.luadoc | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/core/.os.luadoc b/core/.os.luadoc new file mode 100644 index 00000000..4dd473fa --- /dev/null +++ b/core/.os.luadoc @@ -0,0 +1,86 @@ +-- Copyright 2007-2018 Mitchell mitchell.att.foicica.com. 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 *argv* in a separate thread, returning +-- a handle to that process. +-- On Windows, *argv* is passed to `cmd.exe`: `%COMSPEC% /c [argv]`. +-- At the moment, only the Windows terminal version spawns processes in the same +-- thread. +-- @param argv A command line string that contains the program's name followed +-- by arguments to pass to it. `PATH` is searched for program names. +-- @param cwd Optional current working directory (cwd) for the child +-- process. The default value is `nil`, which inherits the parent's cwd. +-- @param env Optional list of environment variables for the child process. +-- Each element in the list is a 'KEY=VALUE' string. The default value is +-- `nil`, which inherits the parent's environment. +-- This parameter should be omitted completely instead of specifying `nil`. +-- @param 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. +-- At the moment, only the Win32 terminal version sends all output, whether it +-- be stdout or stderr, to this callback after the process finishes. +-- @param 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 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', nil, print) +-- @usage proc = os.spawn('lua -e "print(io.read())"', nil, print) +-- proc:write('foo\n') +-- @class function +-- @name os.spawn +local spawn + +--- +-- 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. +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 arg Optional argument similar to those in Lua's `io.read()`, but "n" +-- is not supported. The default value is "l", which reads 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, 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). +-- @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 signal Optional Unix signal to send to *spawn_proc*. The default value +-- is 9 (`SIGKILL`), which kills the process. +function spawn_proc:kill() end +]] |