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_spec.lua
• helper.lua
• libc_spec.lua
• memfd_spec.lua
• nofile_spec.lua
• path_spec.lua
• pipeline_spec.lua
• stringx_spec.lua

Module lsh.cmd

A process builder.

It controls how lsh spawns a new process.

cmd.new(program) makes a default configuration, where program is the name or path of the program to run. Use the builder methods to change the configuration (for example, to add arguments) before you spawn the process:

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)

You can use one command to spawn multiple processes. The builder methods change the command, but they do not spawn a 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

You can also call builder methods after you spawn a process, and then spawn a new process with the changed configuration.

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

Use the slash (/) operator to chain commands into a pipeline.

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 the object.
clone (self)	Clones the 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.
arg_len (self)	Returns the number of arguments passed 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)	Constructs a pipeline from two cmd instances.

Functions

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

Cmd methods

type (self)

Returns the type of the object.

Parameters:

• self lsh.cmd

Returns:

the string "cmd"

Usage:

local sh = require 'lsh'

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

clone (self)

Clones the 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, the output captures stdout and stderr in memfd instances.

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"):format(output.status))
for line in output.stdout:lines() do
  print(line)
end
for line in output.stderr:lines() do
  io.stderr:write(line, '\n')
end

assert(output.status:success())

arg (self, arg)

Adds an argument to pass to the program.

Pass one argument per call.

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 one 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()

arg_len (self)

Returns the number of arguments passed to the program.

The program name is not counted.

Parameters:

• self lsh.cmd

Returns:

number number of arguments

Usage:

local sh = require 'lsh'

assert(sh.cmd('find'):arg_len() == 0)
assert(sh.cmd('find', '.'):arg_len() == 1)

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 name/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)

Constructs a pipeline from two cmd instances.

Parameters:

• l lsh.cmd left cmd
• r lsh.cmd right 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 optional arguments.

The new cmd uses this default configuration:

• Inherit the environment of the current process.
• Inherit the working directory of the current process.
• Inherit stdin, stdout and stderr.

If program does not contain a slash, lsh searches PATH for it.

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()