Module snail

shell script interpreter library

Introduction#

The snail library houses Hilbish's Lua wrapper of its shell script interpreter. hilbish.run and hilbish.runner.sh both run scripts through Hilbish's shared, global Snail instance (available at hilbish.snail), which is what you should be using almost all the time.

Reach for an independent snail instance directly only when you need an isolated interpreter with its own working directory.

local snail = require 'snail'

local interp = snail.new()
local result = interp:run 'echo hello from an isolated snail'
print(result.stdout)

Functions#

snail.new() -> Snail: Creates a new Snail shell interpreter instance.
snail.validate(input) -> boolean: Checks if the input shell script is syntactically incomplete (e.g. unclosed quotes

new#

snail.new() -> Snail

Since: 3.0.0

Creates a new Snail shell interpreter instance.

Returns#

Snail The new Snail instance.

validate#

snail.validate(input) -> boolean

Since: 3.0.0

Checks if the input shell script is syntactically incomplete (e.g. unclosed quotes or blocks). Returns true if the input is incomplete, false otherwise.

Parameters#

string input The shell script string to check.

Returns#

boolean True if more input is needed to complete the statement.

Types#

Snail#

A Snail is a shell script interpreter instance.

Methods#

dir#

snail:dir(path)

Since: 3.0.0

Changes the working directory of this Snail instance. The interpreter keeps its own directory state. In Hilbish usage, this is called when hilbish.cd is emitted.

Parameters#

string path The new working directory. Must be an absolute path.

run#

snail:run(command, streams) -> table

Since: 3.0.0

Runs a shell script command. Works like hilbish.run but operates on this Snail instance.

Parameters#

string command The shell command or script to run.

table streams OptionalOptional table of I/O streams with keys out, err, input (each a Sink).

Returns#

table The result of running the command.

number exitCode The exit code of the command.

string stdout Standard output of the command, if not streamed.

string stderr Standard error output of the command, if not streamed.

string err Error message, if one occurred.

boolean bg Whether the command was run in the background.