lsh

• Index

Contents

• Functions
• Pipeline methods

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.pipeline

A pipeline builder, providing fine-grained control over how new piped processes should be spawned.

Functions

new ()	Constructs a new pipeline instance.
__call (_M)	Shorthand for new.

Pipeline methods

type ()	Returns the type of a instance.
clone (self)	Clones pipeline instance.
add (self, cmd)	Adds cmd instance into pipeline.
run (self)	Executes cmds in a pipeline as a children processes, waiting for it to finish and collecting its exit statuses.
output (self)	Executes the command as a child processes, waiting for it to finish and collecting all of its output.
spawn (self)	Executes the cmds in a pipeline as a children processes, returning a handle to it.
workdir (self, wd)	Sets or updates the working directory for the child processes.
stdin (self[, val])	Sets or unsets the pipeline standard input (stdin) handle.
stdout (self[, val])	Sets or unsets the pipeline standard output (stdout) handle.
stderr (self[, val])	Sets or unsets the pipeline standard error (stderr) handle.
__div (l, r)	Adds cmd instance to pipeline.

Functions

new ()

Constructs a new pipeline instance.

Returns:

lsh.pipeline new pipeline instance

Usage:

local sh = require 'lsh'

sh.pipeline.new():add('echo', 123)
                 :add('rev')
                 :run()

__call (_M)

Shorthand for new.

Parameters:

• _M table module table

Returns:

lsh.pipeline new pipeline struct

Usage:

local sh = require 'lsh'

sh.pipeline():add('echo', 123)
             :add('rev')
             :run()

Pipeline methods

type ()

Returns the type of a instance.

Returns:

the string "pipeline"

Usage:

local sh = require 'lsh'

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

clone (self)

Clones pipeline instance.

Parameters:

• self lsh.pipeline

Returns:

lsh.pipeline new pipeline struct, clone of self

Usage:

local sh = require 'lsh'

local p1 = sh.pipeline():add('ls')
local p2 = p1:clone()

add (self, cmd)

Adds cmd instance into pipeline.

cmd instance will be cloned before inserting into pipeline.

Parameters:

• self lsh.pipeline
• cmd lsh.cmd cmd instance

Returns:

lsh.pipeline self

Usage:

local sh = require 'lsh'

local echo1 = sh.cmd('echo', 1)
sh.pipeline():add(echo1)
             :run()

run (self)

Executes cmds in a pipeline as a children processes, waiting for it to finish and collecting its exit statuses.

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

Parameters:

• self lsh.pipeline

Returns:

lsh.pipeline.pstatus pipeline.pstatus

Usage:

local sh = require 'lsh'

local status = sh.pipeline():add('ls')
                            :add('tail')
                            :run()

output (self)

Executes the command as a child processes, 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.pipeline

Returns:

lsh.pipeline.children.output pipeline.children.output

spawn (self)

Executes the cmds in a pipeline as a children processes, returning a handle to it.

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

Parameters:

• self lsh.pipeline

Returns:

lsh.pipeline.children pipeline.children

Usage:

local sh = require 'lsh'

local children = sh.pipeline():add('ls')
                              :add('tail')
                              :spawn()
local status = children:wait()

workdir (self, wd)

Sets or updates the working directory for the child processes.

Parameters:

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

Returns:

lsh.pipeline self

Usage:

local sh = require 'lsh'

sh.pipeline():workdir('/bin')
             :add('ls')
             :add('tail')
             :run()

stdin (self[, val])

Sets or unsets the pipeline standard input (stdin) handle.

Parameters:

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

Returns:

lsh.pipeline self

Usage:

local sh = require 'lsh'

sh.pipeline():add('tail', '-n1')
             :add('rev')
             :stdin('/path/to/file')
             :run()

stdout (self[, val])

Sets or unsets the pipeline standard output (stdout) handle.

Parameters:

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

Returns:

lsh.pipeline self

Usage:

local sh = require 'lsh'

sh.pipeline():add('ls', '-l')
             :add('rev')
             :stdout('/dev/null')
             :run()

stderr (self[, val])

Sets or unsets the pipeline standard error (stderr) handle.

Parameters:

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

Returns:

lsh.pipeline self

Usage:

local sh = require 'lsh'

sh.pipeline():add('ls', 'nonexistentfile')
             :add('rev')
             :stderr(io.stdout)
             :run()

__div (l, r)

Adds cmd instance to pipeline.

Parameters:

• l lsh.pipeline left pipeline
• r lsh.cmd right cmd

Returns:

lsh.pipeline pipeline instance

Usage:

local sh = require 'lsh'

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