+
-Runs a command in Hilbish's shell script interpreter.
-This is the equivalent of using `source`.
#### Parameters
-`string` **`cmd`**
+This function has no parameters.
+
+
+
+
+
+hilbish.runner.run(input, priv)
+
+
+
+
+
+Runs `input` with the currently set Hilbish runner.
+This method is how Hilbish executes commands.
+`priv` is an optional boolean used to state if the input should be saved to history.
+#### Parameters
+`input` **`string`**
+
+
+`priv` **`bool`**
+
+
+
+
+
+
+
+hilbish.runner.getCurrent()
+
+
+
+
+
+Returns the current runner by name.
+#### Parameters
+This function has no parameters.
+
+
+
+
+
+hilbish.runner.setCurrent(name)
+
+
+
+
+
+Sets Hilbish's runner mode by name.
+#### Parameters
+`name` **`string`**
+
+
+
+
+
+
+
+hilbish.runner.add(name, runner)
+
+
+
+
+
+Adds a runner to the table of available runners.
+If runner is a table, it must have the run function in it.
+#### Parameters
+`name` **`string`**
+ Name of the runner
+
+`runner` **`function|table`**
+
+
+
+
+
+
+
+hilbish.runner.get(name)
+
+
+
+
+
+Get a runner by name.
+#### Parameters
+`name` **`string`**
+ Name of the runner to retrieve.
+
+
+
+
+
+
+hilbish.runner.set(name, runner)
+
+
+
+
+
+*Sets* a runner by name. The difference between this function and
+add, is set will *not* check if the named runner exists.
+The runner table must have the run function in it.
+#### Parameters
+`name` **`string`**
+
+
+`runner` **`table`**
+
+
+
+
+
+
+
+hilbish.runner.exec(cmd, runnerName)
+
+
+
+
+
+Executes `cmd` with a runner.
+If `runnerName` is not specified, it uses the default Hilbish runner.
+#### Parameters
+`cmd` **`string`**
+
+
+`runnerName` **`string?`**
diff --git a/docs/api/snail.md b/docs/api/snail.md
new file mode 100644
index 0000000..44847a9
--- /dev/null
+++ b/docs/api/snail.md
@@ -0,0 +1,120 @@
+---
+title: Module snail
+description: shell script interpreter library
+layout: doc
+menu:
+ docs:
+ parent: "API"
+---
+
+## Introduction
+
+ The snail library houses Hilbish's Lua wrapper of its shell script interpreter.
+ It's not very useful other than running shell scripts, which can be done with other
+ Hilbish functions.
+
+## Functions
+|||
+|----|----|
+|
||
+|
||
+|
||
+|
new() -> @Snail|Creates a new Snail instance.|
+|
||
+|
||
+
+
+
+
+snail.
+
+
+
+
+
+
+#### Parameters
+This function has no parameters.
+
+
+
+
+
+snail.
+
+
+
+
+
+
+#### Parameters
+This function has no parameters.
+
+
+
+
+
+snail.
+
+
+
+
+
+
+#### Parameters
+This function has no parameters.
+
+
+
+
+
+snail.new() -> Snail
+
+
+
+
+
+Creates a new Snail instance.
+
+#### Parameters
+This function has no parameters.
+
+
+
+
+
+
+
+
+snail.
+
+
+
+
+
+
+#### Parameters
+This function has no parameters.
+
+
+## Types
+
+
+## Snail
+A Snail is a shell script interpreter instance.
+
+### Methods
+#### run(command, streams)
+Runs a shell command. Works the same as `hilbish.run`.
+
diff --git a/docs/nature/hilbish.md b/docs/nature/hilbish.md
new file mode 100644
index 0000000..830e241
--- /dev/null
+++ b/docs/nature/hilbish.md
@@ -0,0 +1,53 @@
+---
+title: Module hilbish
+description: No description.
+layout: doc
+menu:
+ docs:
+ parent: "Nature"
+---
+
+
+
+
+hilbish.runner(mode)
+
+
+
+
+
+**NOTE: This function is deprecated and will be removed in 3.0**
+Use `hilbish.runner.setCurrent` instead.
+This is the same as the `hilbish.runnerMode` function.
+It takes a callback, which will be used to execute all interactive input.
+Or a string which names the runner mode to use.
+#### Parameters
+`mode` **`string|function`**
+
+
+
+
+
+
+
+hilbish.runnerMode(mode)
+
+
+
+
+
+**NOTE: This function is deprecated and will be removed in 3.0**
+Use `hilbish.runner.setCurrent` instead.
+Sets the execution/runner mode for interactive Hilbish.
+This determines whether Hilbish wll try to run input as Lua
+and/or sh or only do one of either.
+Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
+sh, and lua. It also accepts a function, to which if it is passed one
+will call it to execute user input instead.
+Read [about runner mode](../features/runner-mode) for more information.
+#### Parameters
+`mode` **`string|function`**
+
+
+
+
diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua
index b80a660..e1ff9f2 100644
--- a/emmyLuaDocs/hilbish.lua
+++ b/emmyLuaDocs/hilbish.lua
@@ -2,17 +2,33 @@
local hilbish = {}
+--- Sets/toggles the option of automatically flushing output.
+--- A call with no argument will toggle the value.
+--- @param auto boolean|nil
+function hilbish:autoFlush(auto) end
+
+--- Flush writes all buffered input to the sink.
+function hilbish:flush() end
+
+--- Reads a liine of input from the sink.
+--- @returns string
+function hilbish:read() end
+
+--- Reads all input from the sink.
+--- @returns string
+function hilbish:readAll() end
+
+--- Writes data to a sink.
+function hilbish:write(str) end
+
+--- Writes data to a sink with a newline at the end.
+function hilbish:writeln(str) end
+
--- This is an alias (ha) for the [hilbish.alias](../#alias) function.
--- @param alias string
--- @param cmd string
function hilbish.aliases.add(alias, cmd) end
---- This is the same as the `hilbish.runnerMode` function.
---- It takes a callback, which will be used to execute all interactive input.
---- In normal cases, neither callbacks should be overrided by the user,
---- as the higher level functions listed below this will handle it.
-function hilbish.runner.setMode(cb) end
-
--- Returns the current input line.
function hilbish.editor.getLine() end
@@ -131,24 +147,6 @@ function hilbish.prompt(str, typ) end
--- Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
function hilbish.read(prompt) end
---- Runs `cmd` in Hilbish's shell script interpreter.
---- The `streams` parameter specifies the output and input streams the command should use.
---- For example, to write command output to a sink.
---- As a table, the caller can directly specify the standard output, error, and input
---- streams of the command with the table keys `out`, `err`, and `input` respectively.
---- As a boolean, it specifies whether the command should use standard output or return its output streams.
----
-function hilbish.run(cmd, streams) end
-
---- Sets the execution/runner mode for interactive Hilbish.
---- This determines whether Hilbish wll try to run input as Lua
---- and/or sh or only do one of either.
---- Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
---- sh, and lua. It also accepts a function, to which if it is passed one
---- will call it to execute user input instead.
---- Read [about runner mode](../features/runner-mode) for more information.
-function hilbish.runnerMode(mode) end
-
--- Executed the `cb` function after a period of `time`.
--- This creates a Timer that starts ticking immediately.
function hilbish.timeout(cb, time) end
@@ -168,28 +166,6 @@ function hilbish.jobs:foreground() end
--- or `load`, but is appropriated for the runner interface.
function hilbish.runner.lua(cmd) end
---- Sets/toggles the option of automatically flushing output.
---- A call with no argument will toggle the value.
---- @param auto boolean|nil
-function hilbish:autoFlush(auto) end
-
---- Flush writes all buffered input to the sink.
-function hilbish:flush() end
-
---- Reads a liine of input from the sink.
---- @returns string
-function hilbish:read() end
-
---- Reads all input from the sink.
---- @returns string
-function hilbish:readAll() end
-
---- Writes data to a sink.
-function hilbish:write(str) end
-
---- Writes data to a sink with a newline at the end.
-function hilbish:writeln(str) end
-
--- Starts running the job.
function hilbish.jobs:start() end
@@ -200,10 +176,6 @@ function hilbish.jobs:stop() end
--- It will throw if any error occurs.
function hilbish.module.load(path) end
---- Runs a command in Hilbish's shell script interpreter.
---- This is the equivalent of using `source`.
-function hilbish.runner.sh(cmd) end
-
--- Starts a timer.
function hilbish.timers:start() end
diff --git a/emmyLuaDocs/snail.lua b/emmyLuaDocs/snail.lua
new file mode 100644
index 0000000..f06a2e1
--- /dev/null
+++ b/emmyLuaDocs/snail.lua
@@ -0,0 +1,26 @@
+--- @meta
+
+local snail = {}
+
+---
+function snail. end
+
+---
+function snail. end
+
+---
+function snail. end
+
+--- Creates a new Snail instance.
+function snail.new() end
+
+---
+function snail. end
+
+--- Runs a shell command. Works the same as `hilbish.run`.
+function snail:run(command, streams) end
+
+---
+function snail. end
+
+return snail
diff --git a/emmyLuaDocs/util.lua b/emmyLuaDocs/util.lua
new file mode 100644
index 0000000..9f8d634
--- /dev/null
+++ b/emmyLuaDocs/util.lua
@@ -0,0 +1,83 @@
+--- @meta
+
+local util = {}
+
+---
+function util.AbbrevHome changes the user's home directory in the path string to ~ (tilde) end
+
+---
+function util. end
+
+---
+function util.DoFile runs the contents of the file in the Lua runtime. end
+
+---
+function util.DoString runs the code string in the Lua runtime. end
+
+--- directory.
+function util.ExpandHome expands ~ (tilde) in the path, changing it to the user home end
+
+---
+function util. end
+
+---
+function util.ForEach loops through a Lua table. end
+
+---
+function util. end
+
+--- a string and a closure.
+function util.HandleStrCallback handles function parameters for Go functions which take end
+
+---
+function util. end
+
+---
+function util. end
+
+---
+function util.SetExports puts the Lua function exports in the table. end
+
+--- It is accessible via the __docProp metatable. It is a table of the names of the fields.
+function util.SetField sets a field in a table, adding docs for it. end
+
+--- is one which has a metatable proxy to ensure no overrides happen to it.
+--- It sets the field in the table and sets the __docProp metatable on the
+--- user facing table.
+function util.SetFieldProtected sets a field in a protected table. A protected table end
+
+--- Sets/toggles the option of automatically flushing output.
+--- A call with no argument will toggle the value.
+--- @param auto boolean|nil
+function util:autoFlush(auto) end
+
+--- Flush writes all buffered input to the sink.
+function util:flush() end
+
+---
+function util. end
+
+--- Reads a liine of input from the sink.
+--- @returns string
+function util:read() end
+
+--- Reads all input from the sink.
+--- @returns string
+function util:readAll() end
+
+--- Writes data to a sink.
+function util:write(str) end
+
+--- Writes data to a sink with a newline at the end.
+function util:writeln(str) end
+
+---
+function util. end
+
+---
+function util. end
+
+---
+function util. end
+
+return util
diff --git a/golibs/snail/lua.go b/golibs/snail/lua.go
index 0095198..37357e5 100644
--- a/golibs/snail/lua.go
+++ b/golibs/snail/lua.go
@@ -1,3 +1,9 @@
+// shell script interpreter library
+/*
+ The snail library houses Hilbish's Lua wrapper of its shell script interpreter.
+ It's not very useful other than running shell scripts, which can be done with other
+ Hilbish functions.
+*/
package snail
import (
@@ -48,11 +54,16 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
return rt.TableValue(mod), nil
}
+// new() -> @Snail
+// Creates a new Snail instance.
func snew(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
s := New(t.Runtime)
return c.PushingNext1(t.Runtime, rt.UserDataValue(snailUserData(s))), nil
}
+// #member
+// run(command, streams)
+// Runs a shell command. Works the same as `hilbish.run`.
func srun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil {
return nil, err
@@ -157,7 +168,7 @@ func handleStream(v rt.Value, strms *util.Streams, errStream, inStream bool) err
return nil
}
-func snailArg(c *rt.GoCont, arg int) (*snail, error) {
+func snailArg(c *rt.GoCont, arg int) (*Snail, error) {
s, ok := valueToSnail(c.Arg(arg))
if !ok {
return nil, fmt.Errorf("#%d must be a snail", arg + 1)
@@ -166,17 +177,17 @@ func snailArg(c *rt.GoCont, arg int) (*snail, error) {
return s, nil
}
-func valueToSnail(val rt.Value) (*snail, bool) {
+func valueToSnail(val rt.Value) (*Snail, bool) {
u, ok := val.TryUserData()
if !ok {
return nil, false
}
- s, ok := u.Value().(*snail)
+ s, ok := u.Value().(*Snail)
return s, ok
}
-func snailUserData(s *snail) *rt.UserData {
+func snailUserData(s *Snail) *rt.UserData {
snailMeta := s.runtime.Registry(snailMetaKey)
return rt.NewUserData(s, snailMeta.AsTable())
}
diff --git a/golibs/snail/snail.go b/golibs/snail/snail.go
index b09af3b..3ca1d12 100644
--- a/golibs/snail/snail.go
+++ b/golibs/snail/snail.go
@@ -1,4 +1,3 @@
-// shell script interpreter library
package snail
import (
@@ -23,21 +22,23 @@ import (
"mvdan.cc/sh/v3/expand"
)
-type snail struct{
+// #type
+// A Snail is a shell script interpreter instance.
+type Snail struct{
runner *interp.Runner
runtime *rt.Runtime
}
-func New(rtm *rt.Runtime) *snail {
+func New(rtm *rt.Runtime) *Snail {
runner, _ := interp.New()
- return &snail{
+ return &Snail{
runner: runner,
runtime: rtm,
}
}
-func (s *snail) Run(cmd string, strms *util.Streams) (bool, io.Writer, io.Writer, error){
+func (s *Snail) Run(cmd string, strms *util.Streams) (bool, io.Writer, io.Writer, error){
file, err := syntax.NewParser().Parse(strings.NewReader(cmd), "")
if err != nil {
return false, nil, nil, err
diff --git a/nature/snail.lua b/nature/snail.lua
index 2a9ce19..1ac1827 100644
--- a/nature/snail.lua
+++ b/nature/snail.lua
@@ -3,7 +3,6 @@ local snail = require 'snail'
hilbish.snail = snail.new()
---- run(cmd, streams) -> exitCode (number), stdout (string), stderr (string)
--- Runs `cmd` in Hilbish's shell script interpreter.
--- The `streams` parameter specifies the output and input streams the command should use.
--- For example, to write command output to a sink.