lsh

• Index

Contents

• Cmd methods
• Functions

Modules

• lsh
• lsh.cmd
• lsh.cmd.child
• lsh.cmd.status
• lsh.fio
• lsh.fio.fh
• lsh.memfd
• lsh.path
• lsh.pipeline
• lsh.pipeline.children
• lsh.pipeline.pstatus
• lsh.stringx
• lsh.time

Topics

• README

Examples

• cmd.lua
• libc.lua
• memfd.lua
• path.lua
• pipeline.lua
• stringx.lua
• test.lua

Module lsh.cmd

A process builder, providing fine-grained control over how a new process should be spawned.

A default configuration can be generated using cmd.new(program), where program gives a path to the program to be executed. Additional builder methods allow the configuration to be changed (for example, by adding arguments) prior to spawning:

local cmd = require 'lsh.cmd'

local output, err = cmd('sh'):arg('-c')
                             :arg('echo hello')
                             :output()
if err then error('failed to execute process') end

local hello = tostring(output.stdout)

Command can be reused to spawn multiple processes. The builder methods change the command without needing to immediately spawn the process.

local cmd = require 'lsh.cmd'

local echo_hello = cmd('sh')
echo_hello:arg('-c')
          :arg('echo hello')

local hello_1, err = echo_hello:output()
if err then error('failed to execute process') end

local hello_2, err = echo_hello:output()
if err then error('failed to execute process') end

Similarly, you can call builder methods after spawning a process and then spawn a new process with the modified settings.

local cmd = require 'lsh.cmd'

local list_dir = cmd('ls')

-- Execute ls in the current directory of the program.
local status, err = list_dir:run()
if err then error('failed to execute process') end

-- Change ls to execute in the root directory.
list_dir:workdir('/')

-- And then execute ls again but in the root directory.
local status, err = list_dir:run()
if err then error('failed to execute process') end

Commands can be easily chained into pipelines by using slash (/) symbol.

local cmd = require 'lsh.cmd'

local ls = cmd('ls'):workdir('/')
local tail = cmd('tail')

local pl = ls / tail:arg('-n1')
local status, err = pl:run()
if err then error('failed to execute pipeline processes') end

Cmd methods

type (self)	Returns the type of a object.
clone (self)	Clones cmd instance.
run (self)	Executes a command as a child process, waiting for it to finish and collecting its exit status.
spawn (self)	Executes the command as a child process, returning a handle to it.
output (self)	Executes the command as a child process, waiting for it to finish and collecting all of its output.
arg (self, arg)	Adds an argument to pass to the program.
args (self, args)	Adds multiple arguments to pass to the program.
workdir (self, wd)	Sets or updates the working directory for the child process.
env (self, envs)	Adds or updates multiple environment variable mappings.
env_remove (self, env)	Removes an environment variable mapping.
env_clear (self)	Clears the entire environment map for the child process.
stdin (self[, val])	Sets or unsets the child process's standard input (stdin) handle.
stdout (self[, val])	Sets or unsets the child process's standard output (stdout) handle.
stderr (self[, val])	Sets or unsets the child process's standard error (stderr) handle.
__div (l, r)	Construct pipeline between two cmd instances.

Functions

new (program[, ...])	Constructs a new cmd for launching the program with optionial arguments.
__call (_M, program[, ...])	Shorthand for new.

Cmd methods

type (self)

Returns the type of a object.

Parameters:

• self lsh.cmd

Returns:

the string "cmd"

Usage:

local sh = require 'lsh'

assert(sh.cmd('ls'):type() == 'cmd')

clone (self)

Clones cmd instance.

Parameters:

• self lsh.cmd

Returns:

lsh.cmd new cmd instance, clone of self

Usage:

local sh = require 'lsh'

local c1 = sh.cmd('ls')
local c2 = c1:clone()

run (self)

Executes a command as a child process, waiting for it to finish and collecting its exit status.

By default, stdin, stdout and stderr are inherited from the parent.

Parameters:

• self lsh.cmd

Returns:

lsh.cmd.status cmd.status

Usage:

local sh = require 'lsh'

local status = sh.cmd('ls'):run()

spawn (self)

Executes the command as a child process, returning a handle to it.

By default, stdin, stdout and stderr are inherited from the parent.

Parameters:

• self lsh.cmd

Returns:

lsh.cmd.child child

Usage:

local sh = require 'lsh'

local child = sh.cmd('ls'):spawn()
local status = child:wait()

output (self)

Executes the command as a child process, waiting for it to finish and collecting all of its output.

By default, stdout and stderr are captured using memfd (and used to provide the resulting output)

Parameters:

• self lsh.cmd

Returns:

lsh.cmd.child.output cmd.child.output

Usage:

local sh = require 'lsh'

local output, err = sh.cmd('cat'):arg('file.txt')
                                 :output()
if not output then error(err) end
print(("status: %s", output.status)
for line in output.stdout:lines() do
  io.stdout:write(line)
end
for line in output.stderr:lines() do
  io.stderr:write(line)
end

assert(output.status:success())

arg (self, arg)

Adds an argument to pass to the program.

Only one argument can be passed per use.

To pass multiple arguments see args.

Parameters:

• self lsh.cmd
• arg string, number or lsh.path program argument

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('ls'):arg('-a')
            :run()

args (self, args)

Adds multiple arguments to pass to the program.

To pass a single argument see arg.

Parameters:

• self lsh.cmd
• args table array of program arguments

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('ls'):args({'-a', '-l'})
            :run()

workdir (self, wd)

Sets or updates the working directory for the child process.

Parameters:

• self lsh.cmd
• wd string or lsh.path working directory

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('ls'):workdir('/bin')
            :run()

env (self, envs)

Adds or updates multiple environment variable mappings.

Parameters:

• self lsh.cmd
• envs table env/value pairs of environment variables

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('ls'):env({PATH = '/bin'})
            :run()

env_remove (self, env)

Removes an environment variable mapping.

Parameters:

• self lsh.cmd
• env string environment variable

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('ls'):env_remove('PATH')
            :run()

env_clear (self)

Clears the entire environment map for the child process.

Parameters:

• self lsh.cmd

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('ls'):env_clear()
            :run()

stdin (self[, val])

Sets or unsets the child process's standard input (stdin) handle.

Parameters:

• self cmd
• val string, userdata, lsh.fio.fh or lsh.path handle value (optional)

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('tail'):stdin('/path/to/file')
              :run()

stdout (self[, val])

Sets or unsets the child process's standard output (stdout) handle.

Parameters:

• self cmd
• val string, userdata, lsh.fio.fh or lsh.path handle value (optional)

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('echo', 1):stdout('/dev/null')
                 :run()

stderr (self[, val])

Sets or unsets the child process's standard error (stderr) handle.

Parameters:

• self cmd
• val string, userdata, lsh.fio.fh or lsh.path handle value (optional)

Returns:

lsh.cmd self

Usage:

local sh = require 'lsh'

sh.cmd('echo', 1):stderr(io.stdout)
                 :run()

__div (l, r)

Construct pipeline between two cmd instances.

Parameters:

• l lsh.cmd left cmd
• r lsh.cmd righ cmd

Returns:

lsh.pipeline new pipeline instance

Usage:

local sh = require 'lsh'

local p = sh.cmd('ls') /
          sh.cmd('rev')
p:run()

Functions

new (program[, ...])

Constructs a new cmd for launching the program with optionial arguments.

Following default configuration will be used:

• inherit the current process's environment
• inherit the current process's working directory
• inherit stdin/stdout/stderr

If program is not an absolute path, the PATH will be searched in an OS-defined way.

Parameters:

• program string program name or path to program
• ... string, number or lsh.path program arguments (optional)

Returns:

lsh.cmd new cmd instance

Usage:

local sh = require 'lsh'

sh.cmd.new('echo', 1):run()

__call (_M, program[, ...])

Shorthand for new.

Parameters:

• _M table module table
• program string program name or path to program
• ... string, number or lsh.path program arguments (optional)

Returns:

lsh.cmd new cmd instance

Usage:

local sh = require 'lsh'

sh.cmd('echo', 1):run()