NAME

porch — Lua library for porch(1)

SYNOPSIS

local porch = require('porch')

porch.env[‘PROGNAME’] = ‘bc’

 

ok, err = porch.run_script(scriptfile[, config])

 

porch.reset()

 

porch.signals

 

porch.sleep(seconds)

 

porch.tty.iflag

 

porch.tty.oflag

 

porch.tty.cflag

 

porch.tty.lflag

 

porch.tty.cc

 

process = porch.spawn(argv0[,argv...])

 

process:match(pattern[, matcher])

 

process:eof(timeout)

 

process:cfg(cfg)

 

process:chdir(dir)

 

process:close()

 

process:flush(timeout)

 

process:log(logfile)

 

process:pipe(commandstr, linefilter)

 

process:raw(bool)

 

process:release()

 

process:sigblock(signo, ...)

 

process:sigcatch(signo, ...)

 

process:sigclear()

 

process:sigignore(signo, ...)

 

process:sigisblocked(signo, ...)

 

process:sigiscaught(signo, ...)

 

process:sigisignored(signo, ...)

 

process:sigisunblocked(signo, ...)

 

process:signal(signo)

 

process:sigreset(preserve_sigmask)

 

process:sigunblock(signo, ...)

 

process:stty(field[, set[, unset]])

 

process:term()

 

process:write(text[, cfg])

 

process:clearenv([local])

 

process:getenv(key)

 

process:setenv(key, value[, local])

 

DESCRIPTION

The porch module is the lua interface to the porch(1) program. The porch module exposes the following members directly:

porch.env[‘PROGNAME’] = ‘bc’

Sets the global PROGNAME in the scripted environment. There is no limitation to what the caller may provide in the environment, it is expected that its main use will be to offer targeted methods to break out of the limited “sandbox” that the script runs in.

porch.run_script(scriptfile[, config])

Run the script described by scriptfile. The caller may pass either a filename or an already-opened file stream. The porch.run_script function will return true if the script ran to completion without error, nil and an error if the script encountered a fatal error, or the value passed to the exit function that is provided in the scripted environment.

porch.reset()

Completely resets the scripter state. This closes any process that may still be open, removes all actions specified by the current script, and resets the global timeout. The script file is only open long enough to read the script, so it does not need to be closed at reset time.

This happens at the beginning of the porch.run_script call, but one may want to release all resources held by porch after completion if it is not expected to be used again.

porch.sleep(seconds)

Sleep for at least the requested number of seconds. This is only exported because it is implemented for internal use, and some users could find it helpful to not need to import it from elsewhere.

process = porch.spawn(argv0[,argv...])

Spawns a new process described by the argument vector provided. This is an alternative to using porch.run_script, as most of the same functionality available to orch(5) scripts is also exposed via the process object. The argv0 name is subject to a standard PATH search, unless the name contains a “/” character.

See the below table for a description of the methods available for the process.

The porch.signals table maps signal names to their corresponding values. The keys to this table are signal names with a SIG prefix.

The porch.tty table exposes various tty options for the current system:

• porch.tty.iflag
• porch.tty.oflag
• porch.tty.cflag
• porch.tty.lflag
• porch.tty.cc

All of these are tables that map names to values that may be provided to the stty() function of a process: See your platform's termios documentation for more information on what the values represent. Only the lflag and cc tables are populated at the moment.

The following process operations are available on the object returned by porch.spawn:

process:match(pattern[, matcher])

Attempts to match pattern with the given matcher, which defaults to the Lua pattern matcher. Other matchers can be pulled from the porch.matchers.available table, which has the following keys:

• lua (default)
• plain
• posix (EREs)

process:eof(timeout)

The eof function behaves the same as it does in orch(5), except it does not take a callback as the second argument. Instead, it returns up to two values: a boolean to indicate whether the process has closed its end of the terminal device, and a wait status object if the process has terminated. The returned wait status object matches the object passed to the callback described for eof in orch(5). porch has no default timeout, so an omitted or nil timeout will result in the eof function waiting indefinitely for both EOF and the process to exit.

process:cfg(cfg)

 

process:chdir(dir)

 

process:close()

 

process:flush(timeout)

 

process:log(logfile)

 

process:pipe(commandstr, linefilter)

 

process:raw(bool)

 

process:release()

 

process:sigblock(...)

 

process:sigcatch(...)

 

process:sigclear()

 

process:sigignore(...)

 

process:sigisblocked(signo, ...)

Returns true if every signo specified is currently blocked.

process:sigiscaught(signo, ...)

Returns true if every signo specified is currently caught.

process:sigisignored(signo, ...)

Returns true if every signo specified is currently ignored.

process:sigisunblocked(signo, ...)

Returns true if every signo specified is currently unblocked.

process:signal(signo)

 

process:sigreset(preserve_sigmask)

 

process:sigunblock(signo, ...)

 

process:stty(field[, set[, unset]])

The process:stty function is provided for convenience, but there is some overlap with fuctionality provided by the process' process:term as described below.

process:term()

This returns an object that represents the process terminal. The terminal object has the following method and properties:

term:fetch(field, ...)

Fetches the associated property from the terminal. The “field” requested may be one of:

• “cc”
• “cflag”
• “iflag”
• “lflag”
• “oflag”

The requested values are returned in the same order that they are passed to term:fetch().

term:update(fields)

Updates the terminal with values specified in the table “fields”. The keys of the field table are expected to match the names of the fields that may be fetched above in term:fetch(). The values are the new value to assign the associated field. The process:stty() function described above may be more convenient to use when needing to simply enable or disable a single flag, as the fetch/update are done for you.

term:size([width, height])

Get or set the size of the terminal. If both “width” and “height” are omitted or nil, the width and height are returned in that order. Otherwise, the specified elements are of the size are updated unless specified as nil.

process:write(text[, cfg])

 

process:clearenv([local])

 

process:getenv(key)

 

process:setenv(key, value[, local])

 

All of these functions operate as described in orch(5), unless otherwise-indicated inline above.

SEE ALSO

porch(1), orch(5)

AUTHORS

Kyle Evans ⟨kevans@FreeBSD.org⟩