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

Module lsh.pipeline

A pipeline builder.

It controls how lsh spawns processes that are connected with pipes.

Functions

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

Pipeline methods

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

Functions

new ()

Constructs a new pipeline instance.

Returns:

lsh.pipeline new pipeline instance

Usage:

local sh = require 'lsh'

sh.pipeline.new():add(sh.cmd('echo', 123))
                 :add(sh.cmd('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(sh.cmd('echo', 123))
             :add(sh.cmd('rev'))
             :run()

Pipeline methods

type ()

Returns the type of the instance.

Returns:

the string "pipeline"

Usage:

local sh = require 'lsh'

assert(sh.pipeline():type() == 'pipeline')

clone (self)

Clones the 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(sh.cmd('ls'))
local p2 = p1:clone()

add (self, cmd)

Adds a cmd instance to the pipeline.

The pipeline stores a clone of the cmd instance.

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 the cmds in the pipeline as children processes, waiting for them to finish and collecting their 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(sh.cmd('ls'))
                            :add(sh.cmd('tail'))
                            :run()

output (self)

Executes the cmds in the pipeline as children processes, waiting for them to finish and collecting all of their output.

By default, the output captures stdout and stderr in memfd instances.

Parameters:

• self lsh.pipeline

Returns:

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

spawn (self)

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

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(sh.cmd('ls'))
                              :add(sh.cmd('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(sh.cmd('ls'))
             :add(sh.cmd('tail'))
             :run()

stdin (self[, val])

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

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(sh.cmd('tail', '-n1'))
             :add(sh.cmd('rev'))
             :stdin('/path/to/file')
             :run()

stdout (self[, val])

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

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(sh.cmd('ls', '-l'))
             :add(sh.cmd('rev'))
             :stdout('/dev/null')
             :run()

stderr (self[, val])

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

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(sh.cmd('ls', 'nonexistentfile'))
             :add(sh.cmd('rev'))
             :stderr(io.stdout)
             :run()

__div (l, r)

Adds a cmd instance to the 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()