sammyette/Hilbish
2
3
Fork 0
mirror of https://github.com/sammy-ette/Hilbish synced 2025-08-10 02:52:03 +00:00
Code Issues Releases Wiki Activity

refactor: update documentation for everything

Browse Source
This commit is contained in:
sammyette 2023-12-03 20:54:00 -04:00
parent 7cd1170e41
commit 90ef8f7a9c
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
24 changed files with 480 additions and 336 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
aliases.go
View File

@ -111,15 +111,23 @@ func (a *aliasModule) Loader(rtm *rt.Runtime) *rt.Table {
// #interface aliases // #interface aliases
// add(alias, cmd) // add(alias, cmd)
// This is an alias (ha) for the `hilbish.alias` function. // This is an alias (ha) for the [hilbish.alias](../#alias) function.
// --- @param alias string // --- @param alias string
// --- @param cmd string // --- @param cmd string
func _hlalias() {} func _hlalias() {}
// #interface aliases // #interface aliases
// list() -> table<string, string> // list() -> table[string, string]
// Get a table of all aliases, with string keys as the alias and the value as the command. // Get a table of all aliases, with string keys as the alias and the value as the command.
// --- @returns table<string, string> // #returns table[string, string]
/*
#example
hilbish.aliases.add('hi', 'echo hi')
local aliases = hilbish.aliases.list()
-- -> {hi = 'echo hi'}
#example
*/
func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
aliasesList := rt.NewTable() aliasesList := rt.NewTable()
for k, v := range a.All() { for k, v := range a.All() {
@ -132,7 +140,7 @@ func (a *aliasModule) luaList(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface aliases // #interface aliases
// delete(name) // delete(name)
// Removes an alias. // Removes an alias.
// --- @param name string // #param name string
func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -147,10 +155,10 @@ func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// #interface aliases // #interface aliases
// resolve(alias) -> command (string) // resolve(alias) -> string?
// Tries to resolve an alias to its command. // Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
// --- @param alias string // #param alias string
// --- @returns string // #returns string
func (a *aliasModule) luaResolve(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (a *aliasModule) luaResolve(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err

135
api.go
View File

@ -190,12 +190,10 @@ func unsetVimMode() {
} }
// run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string) // run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
// Runs `cmd` in Hilbish's sh interpreter. // Runs `cmd` in Hilbish's shell script interpreter.
// If returnOut is true, the outputs of `cmd` will be returned as the 2nd and // #param cmd string
// 3rd values instead of being outputted to the terminal. // #param returnOut boolean If this is true, the function will return the standard output and error of the command instead of printing it.
// --- @param cmd string // #returns number, string, string
// --- @param returnOut boolean
// --- @returns number, string, string
func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -238,7 +236,7 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// cwd() -> string // cwd() -> string
// Returns the current directory of the shell // Returns the current directory of the shell
// --- @returns string // #returns string
func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
cwd, _ := os.Getwd() cwd, _ := os.Getwd()
@ -249,9 +247,9 @@ func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// read(prompt) -> input (string) // read(prompt) -> input (string)
// Read input from the user, using Hilbish's line editor/input reader. // Read input from the user, using Hilbish's line editor/input reader.
// This is a separate instance from the one Hilbish actually uses. // This is a separate instance from the one Hilbish actually uses.
// Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen) // Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).
// --- @param prompt? string // #param prompt? string
// --- @returns string|nil // #returns string|nil
func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
luaprompt := c.Arg(0) luaprompt := c.Arg(0)
if typ := luaprompt.Type(); typ != rt.StringType && typ != rt.NilType { if typ := luaprompt.Type(); typ != rt.StringType && typ != rt.NilType {
@ -279,14 +277,21 @@ func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
/* /*
prompt(str, typ) prompt(str, typ)
Changes the shell prompt to `str` Changes the shell prompt to the provided string.
There are a few verbs that can be used in the prompt text. There are a few verbs that can be used in the prompt text.
These will be formatted and replaced with the appropriate values. These will be formatted and replaced with the appropriate values.
`%d` - Current working directory `%d` - Current working directory
`%u` - Name of current user `%u` - Name of current user
`%h` - Hostname of device `%h` - Hostname of device
--- @param str string #param str string
--- @param typ? string Type of prompt, being left or right. Left by default. #param typ? string Type of prompt, being left or right. Left by default.
#example
-- the default hilbish prompt without color
hilbish.prompt '%u %d ∆'
-- or something of old:
hilbish.prompt '%u@%h :%d $'
-- prompt: user@hostname: ~/directory $
#example
*/ */
func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
err := c.Check1Arg() err := c.Check1Arg()
@ -320,8 +325,28 @@ func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// multiprompt(str) // multiprompt(str)
// Changes the continued line prompt to `str` // Changes the text prompt when Hilbish asks for more input.
// --- @param str string // This will show up when text is incomplete, like a missing quote
// #param str string
/*
#example
--[[
imagine this is your text input:
user ~ ∆ echo "hey
but there's a missing quote! hilbish will now prompt you so the terminal
will look like:
user ~ ∆ echo "hey
--> ...!"
so then you get
user ~ ∆ echo "hey
--> ...!"
hey ...!
]]--
hilbish.multiprompt '-->'
#example
*/
func hlmultiprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlmultiprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -415,8 +440,9 @@ func appendPath(dir string) {
} }
// exec(cmd) // exec(cmd)
// Replaces running hilbish with `cmd` // Replaces the currently running Hilbish instance with the supplied command.
// --- @param cmd string // This can be used to do an in-place restart.
// #param cmd string
func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -450,8 +476,10 @@ func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// goro(fn) // goro(fn)
// Puts `fn` in a goroutine // Puts `fn` in a Goroutine.
// --- @param fn function // This can be used to run any function in another thread.
// **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
// #param fn function
func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -474,10 +502,10 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// timeout(cb, time) -> @Timer // timeout(cb, time) -> @Timer
// Runs the `cb` function after `time` in milliseconds. // Runs the `cb` function after `time` in milliseconds.
// This creates a timer that starts immediately. // This creates a Timer that starts immediately.
// --- @param cb function // #param cb function
// --- @param time number // #param time number
// --- @returns Timer // #returns Timer
func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
return nil, err return nil, err
@ -501,9 +529,9 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// interval(cb, time) -> @Timer // interval(cb, time) -> @Timer
// Runs the `cb` function every `time` milliseconds. // Runs the `cb` function every `time` milliseconds.
// This creates a timer that starts immediately. // This creates a timer that starts immediately.
// --- @param cb function // #param cb function
// --- @param time number // #param time number
// --- @return Timer // #return Timer
func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil { if err := c.CheckNArgs(2); err != nil {
return nil, err return nil, err
@ -525,13 +553,13 @@ func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// complete(scope, cb) // complete(scope, cb)
// Registers a completion handler for `scope`. // Registers a completion handler for the specified scope.
// A `scope` is currently only expected to be `command.<cmd>`, // A `scope` is currently only expected to be `command.<cmd>`,
// replacing <cmd> with the name of the command (for example `command.git`). // replacing <cmd> with the name of the command (for example `command.git`).
// `cb` must be a function that returns a table of "completion groups." // The documentation for completions, under Features/Completions or `doc completions`
// Check `doc completions` for more information. // provides more details.
// --- @param scope string // #param scope string
// --- @param cb function // #param cb function
func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
scope, cb, err := util.HandleStrCallback(t, c) scope, cb, err := util.HandleStrCallback(t, c)
if err != nil { if err != nil {
@ -543,8 +571,8 @@ func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// prependPath(dir) // prependPath(dir)
// Prepends `dir` to $PATH // Prepends `dir` to $PATH.
// --- @param dir string // #param dir string
func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -567,8 +595,8 @@ func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// which(name) -> string // which(name) -> string
// Checks if `name` is a valid command. // Checks if `name` is a valid command.
// Will return the path of the binary, or a basename if it's a commander. // Will return the path of the binary, or a basename if it's a commander.
// --- @param name string // #param name string
// --- @returns string // #returns string
func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -598,8 +626,10 @@ func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// inputMode(mode) // inputMode(mode)
// Sets the input mode for Hilbish's line reader. Accepts either emacs or vim // Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
// --- @param mode string // `emacs` is the default. Setting it to `vim` changes behavior of input to be
// Vim-like with modes and Vim keybinds.
// #param mode string
func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -629,7 +659,7 @@ func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), // 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 // sh, and lua. It also accepts a function, to which if it is passed one
// will call it to execute user input instead. // will call it to execute user input instead.
// --- @param mode string|function // #param mode string|function
func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -655,26 +685,33 @@ func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// line and cursor position. It is expected to return a string which is used // line and cursor position. It is expected to return a string which is used
// as the text for the hint. This is by default a shim. To set hints, // as the text for the hint. This is by default a shim. To set hints,
// override this function with your custom handler. // override this function with your custom handler.
// --- @param line string // #param line string
// --- @param pos number // #param pos number
/*
#example
-- this will display "hi" after the cursor in a dimmed color.
function hilbish.hinter(line, pos)
return 'hi'
end
#example
*/
func hlhinter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlhinter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), nil return c.Next(), nil
} }
// highlighter(line) // highlighter(line)
// Line highlighter handler. This is mainly for syntax highlighting, but in // Line highlighter handler.
// reality could set the input of the prompt to *display* anything. The // This is mainly for syntax highlighting, but in reality could set the input
// callback is passed the current line and is expected to return a line that // of the prompt to *display* anything. The callback is passed the current line
// will be used as the input display. // and is expected to return a line that will be used as the input display.
// Note that to set a highlighter, one has to override this function. // Note that to set a highlighter, one has to override this function.
// Example: // #example
// ``` // --This code will highlight all double quoted strings in green.
// function hilbish.highlighter(line) // function hilbish.highlighter(line)
// return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) // return line:gsub('"%w+"', function(c) return lunacolors.green(c) end)
// end // end
// ``` // #example
// This code will highlight all double quoted strings in green. // #param line string
// --- @param line string
func hlhighlighter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func hlhighlighter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.Next(), nil return c.Next(), nil
} }

185
docs/api/hilbish/_index.md
View File

@ -16,19 +16,19 @@ interfaces and functions which directly relate to shell functionality.
|----|----| |----|----|
|<a href="#alias">alias(cmd, orig)</a>|Sets an alias, with a name of `cmd` to another command.| |<a href="#alias">alias(cmd, orig)</a>|Sets an alias, with a name of `cmd` to another command.|
|<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)| |<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)|
|<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for `scope`.| |<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for the specified scope.|
|<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell| |<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell|
|<a href="#exec">exec(cmd)</a>|Replaces running hilbish with `cmd`| |<a href="#exec">exec(cmd)</a>|Replaces the currently running Hilbish instance with the supplied command.|
|<a href="#goro">goro(fn)</a>|Puts `fn` in a goroutine| |<a href="#goro">goro(fn)</a>|Puts `fn` in a Goroutine.|
|<a href="#highlighter">highlighter(line)</a>|Line highlighter handler. This is mainly for syntax highlighting, but in| |<a href="#highlighter">highlighter(line)</a>|Line highlighter handler.|
|<a href="#hinter">hinter(line, pos)</a>|The command line hint handler. It gets called on every key insert to| |<a href="#hinter">hinter(line, pos)</a>|The command line hint handler. It gets called on every key insert to|
|<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim| |<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.|
|<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every `time` milliseconds.| |<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every `time` milliseconds.|
|<a href="#multiprompt">multiprompt(str)</a>|Changes the continued line prompt to `str`| |<a href="#multiprompt">multiprompt(str)</a>|Changes the text prompt when Hilbish asks for more input.|
|<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH| |<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH.|
|<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to `str`| |<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to the provided string.|
|<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.| |<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.|
|<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's sh interpreter.| |<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
|<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish. This determines whether| |<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish. This determines whether|
|<a href="#timeout">timeout(cb, time) -> @Timer</a>|Runs the `cb` function after `time` in milliseconds.| |<a href="#timeout">timeout(cb, time) -> @Timer</a>|Runs the `cb` function after `time` in milliseconds.|
|<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.| |<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.|
@ -111,13 +111,18 @@ hilbish.complete(scope, cb)
</a> </a>
</h4> </h4>
Registers a completion handler for `scope`. Registers a completion handler for the specified scope.
A `scope` is currently only expected to be `command.<cmd>`, A `scope` is currently only expected to be `command.<cmd>`,
replacing <cmd> with the name of the command (for example `command.git`). replacing <cmd> with the name of the command (for example `command.git`).
`cb` must be a function that returns a table of "completion groups." The documentation for completions, under Features/Completions or `doc completions`
Check `doc completions` for more information. provides more details.
#### Parameters #### Parameters
This function has no parameters. `string` **`scope`**
`function` **`cb`**
</div> </div>
<hr><div id='cwd'> <hr><div id='cwd'>
@ -141,9 +146,12 @@ hilbish.exec(cmd)
</a> </a>
</h4> </h4>
Replaces running hilbish with `cmd` Replaces the currently running Hilbish instance with the supplied command.
This can be used to do an in-place restart.
#### Parameters #### Parameters
This function has no parameters. `string` **`cmd`**
</div> </div>
<hr><div id='goro'> <hr><div id='goro'>
@ -154,9 +162,13 @@ hilbish.goro(fn)
</a> </a>
</h4> </h4>
Puts `fn` in a goroutine Puts `fn` in a Goroutine.
This can be used to run any function in another thread.
**NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
#### Parameters #### Parameters
This function has no parameters. `function` **`fn`**
</div> </div>
<hr><div id='highlighter'> <hr><div id='highlighter'>
@ -167,20 +179,23 @@ hilbish.highlighter(line)
</a> </a>
</h4> </h4>
Line highlighter handler. This is mainly for syntax highlighting, but in Line highlighter handler.
reality could set the input of the prompt to *display* anything. The This is mainly for syntax highlighting, but in reality could set the input
callback is passed the current line and is expected to return a line that of the prompt to *display* anything. The callback is passed the current line
will be used as the input display. and is expected to return a line that will be used as the input display.
Note that to set a highlighter, one has to override this function. Note that to set a highlighter, one has to override this function.
Example:
``` #### Parameters
`string` **`line`**
#### Example
```lua
--This code will highlight all double quoted strings in green.
function hilbish.highlighter(line) function hilbish.highlighter(line)
return line:gsub('"%w+"', function(c) return lunacolors.green(c) end) return line:gsub('"%w+"', function(c) return lunacolors.green(c) end)
end end
``` ````
This code will highlight all double quoted strings in green.
#### Parameters
This function has no parameters.
</div> </div>
<hr><div id='hinter'> <hr><div id='hinter'>
@ -196,8 +211,22 @@ determine what text to use as an inline hint. It is passed the current
line and cursor position. It is expected to return a string which is used line and cursor position. It is expected to return a string which is used
as the text for the hint. This is by default a shim. To set hints, as the text for the hint. This is by default a shim. To set hints,
override this function with your custom handler. override this function with your custom handler.
#### Parameters #### Parameters
This function has no parameters. `string` **`line`**
`number` **`pos`**
#### Example
```lua
-- this will display "hi" after the cursor in a dimmed color.
function hilbish.hinter(line, pos)
return 'hi'
end
````
</div> </div>
<hr><div id='inputMode'> <hr><div id='inputMode'>
@ -208,9 +237,13 @@ hilbish.inputMode(mode)
</a> </a>
</h4> </h4>
Sets the input mode for Hilbish's line reader. Accepts either emacs or vim Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
`emacs` is the default. Setting it to `vim` changes behavior of input to be
Vim-like with modes and Vim keybinds.
#### Parameters #### Parameters
This function has no parameters. `string` **`mode`**
</div> </div>
<hr><div id='interval'> <hr><div id='interval'>
@ -224,7 +257,12 @@ hilbish.interval(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/
Runs the `cb` function every `time` milliseconds. Runs the `cb` function every `time` milliseconds.
This creates a timer that starts immediately. This creates a timer that starts immediately.
#### Parameters #### Parameters
This function has no parameters. `function` **`cb`**
`number` **`time`**
</div> </div>
<hr><div id='multiprompt'> <hr><div id='multiprompt'>
@ -235,9 +273,32 @@ hilbish.multiprompt(str)
</a> </a>
</h4> </h4>
Changes the continued line prompt to `str` Changes the text prompt when Hilbish asks for more input.
This will show up when text is incomplete, like a missing quote
#### Parameters #### Parameters
This function has no parameters. `string` **`str`**
#### Example
```lua
--[[
imagine this is your text input:
user ~ ∆ echo "hey
but there's a missing quote! hilbish will now prompt you so the terminal
will look like:
user ~ ∆ echo "hey
--> ...!"
so then you get
user ~ ∆ echo "hey
--> ...!"
hey ...!
]]--
hilbish.multiprompt '-->'
````
</div> </div>
<hr><div id='prependPath'> <hr><div id='prependPath'>
@ -248,9 +309,11 @@ hilbish.prependPath(dir)
</a> </a>
</h4> </h4>
Prepends `dir` to $PATH Prepends `dir` to $PATH.
#### Parameters #### Parameters
This function has no parameters. `string` **`dir`**
</div> </div>
<hr><div id='prompt'> <hr><div id='prompt'>
@ -261,14 +324,28 @@ hilbish.prompt(str, typ)
</a> </a>
</h4> </h4>
Changes the shell prompt to `str` Changes the shell prompt to the provided string.
There are a few verbs that can be used in the prompt text. There are a few verbs that can be used in the prompt text.
These will be formatted and replaced with the appropriate values. These will be formatted and replaced with the appropriate values.
`%d` - Current working directory `%d` - Current working directory
`%u` - Name of current user `%u` - Name of current user
`%h` - Hostname of device `%h` - Hostname of device
#### Parameters #### Parameters
This function has no parameters. `string` **`str`**
`string` **`typ?`**
Type of prompt, being left or right. Left by default.
#### Example
```lua
-- the default hilbish prompt without color
hilbish.prompt '%u %d ∆'
-- or something of old:
hilbish.prompt '%u@%h :%d $'
-- prompt: user@hostname: ~/directory $
````
</div> </div>
<hr><div id='read'> <hr><div id='read'>
@ -281,9 +358,11 @@ hilbish.read(prompt) -> input (string)
Read input from the user, using Hilbish's line editor/input reader. Read input from the user, using Hilbish's line editor/input reader.
This is a separate instance from the one Hilbish actually uses. This is a separate instance from the one Hilbish actually uses.
Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen) Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).
#### Parameters #### Parameters
This function has no parameters. `string` **`prompt?`**
</div> </div>
<hr><div id='run'> <hr><div id='run'>
@ -294,11 +373,14 @@ hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (strin
</a> </a>
</h4> </h4>
Runs `cmd` in Hilbish's sh interpreter. Runs `cmd` in Hilbish's shell script interpreter.
If returnOut is true, the outputs of `cmd` will be returned as the 2nd and
3rd values instead of being outputted to the terminal.
#### Parameters #### Parameters
This function has no parameters. `string` **`cmd`**
`boolean` **`returnOut`**
If this is true, the function will return the standard output and error of the command instead of printing it.
</div> </div>
<hr><div id='runnerMode'> <hr><div id='runnerMode'>
@ -315,7 +397,9 @@ 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 sh, and lua. It also accepts a function, to which if it is passed one
will call it to execute user input instead. will call it to execute user input instead.
#### Parameters #### Parameters
This function has no parameters. `string|function` **`mode`**
</div> </div>
<hr><div id='timeout'> <hr><div id='timeout'>
@ -327,9 +411,14 @@ hilbish.timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#
</h4> </h4>
Runs the `cb` function after `time` in milliseconds. Runs the `cb` function after `time` in milliseconds.
This creates a timer that starts immediately. This creates a Timer that starts immediately.
#### Parameters #### Parameters
This function has no parameters. `function` **`cb`**
`number` **`time`**
</div> </div>
<hr><div id='which'> <hr><div id='which'>
@ -343,7 +432,9 @@ hilbish.which(name) -> string
Checks if `name` is a valid command. Checks if `name` is a valid command.
Will return the path of the binary, or a basename if it's a commander. Will return the path of the binary, or a basename if it's a commander.
#### Parameters #### Parameters
This function has no parameters. `string` **`name`**
</div> </div>
## Types ## Types

31
docs/api/hilbish/hilbish.aliases.md
View File

@ -13,10 +13,10 @@ The alias interface deals with all command aliases in Hilbish.
## Functions ## Functions
||| |||
|----|----| |----|----|
|<a href="#aliases.add">add(alias, cmd)</a>|This is an alias (ha) for the `hilbish.alias` function.| |<a href="#aliases.add">add(alias, cmd)</a>|This is an alias (ha) for the [hilbish.alias](../#alias) function.|
|<a href="#aliases.delete">delete(name)</a>|Removes an alias.| |<a href="#aliases.delete">delete(name)</a>|Removes an alias.|
|<a href="#aliases.list">list() -> table<string, string></a>|Get a table of all aliases, with string keys as the alias and the value as the command.| |<a href="#aliases.list">list() -> table[string, string]</a>|Get a table of all aliases, with string keys as the alias and the value as the command.|
|<a href="#aliases.resolve">resolve(alias) -> command (string)</a>|Tries to resolve an alias to its command.| |<a href="#aliases.resolve">resolve(alias) -> string?</a>|Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.|
<hr><div id='aliases.add'> <hr><div id='aliases.add'>
<h4 class='heading'> <h4 class='heading'>
@ -26,7 +26,7 @@ hilbish.aliases.add(alias, cmd)
</a> </a>
</h4> </h4>
This is an alias (ha) for the `hilbish.alias` function. This is an alias (ha) for the [hilbish.alias](../#alias) function.
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
</div> </div>
@ -41,32 +41,45 @@ hilbish.aliases.delete(name)
Removes an alias. Removes an alias.
#### Parameters #### Parameters
This function has no parameters. `string` **`name`**
</div> </div>
<hr><div id='aliases.list'> <hr><div id='aliases.list'>
<h4 class='heading'> <h4 class='heading'>
hilbish.aliases.list() -> table\<string, string> hilbish.aliases.list() -> table[string, string]
<a href="#aliases.list" class='heading-link'> <a href="#aliases.list" class='heading-link'>
<i class="fas fa-paperclip"></i> <i class="fas fa-paperclip"></i>
</a> </a>
</h4> </h4>
Get a table of all aliases, with string keys as the alias and the value as the command. Get a table of all aliases, with string keys as the alias and the value as the command.
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
#### Example
```lua
hilbish.aliases.add('hi', 'echo hi')
local aliases = hilbish.aliases.list()
-- -> {hi = 'echo hi'}
````
</div> </div>
<hr><div id='aliases.resolve'> <hr><div id='aliases.resolve'>
<h4 class='heading'> <h4 class='heading'>
hilbish.aliases.resolve(alias) -> command (string) hilbish.aliases.resolve(alias) -> string?
<a href="#aliases.resolve" class='heading-link'> <a href="#aliases.resolve" class='heading-link'>
<i class="fas fa-paperclip"></i> <i class="fas fa-paperclip"></i>
</a> </a>
</h4> </h4>
Tries to resolve an alias to its command. Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
#### Parameters #### Parameters
This function has no parameters. `string` **`alias`**
</div> </div>

21
docs/api/hilbish/hilbish.editor.md
View File

@ -16,8 +16,8 @@ directly interact with the line editor in use.
|----|----| |----|----|
|<a href="#editor.getLine">getLine() -> string</a>|Returns the current input line.| |<a href="#editor.getLine">getLine() -> string</a>|Returns the current input line.|
|<a href="#editor.getVimRegister">getVimRegister(register) -> string</a>|Returns the text that is at the register.| |<a href="#editor.getVimRegister">getVimRegister(register) -> string</a>|Returns the text that is at the register.|
|<a href="#editor.insert">insert(text)</a>|Inserts text into the line.| |<a href="#editor.insert">insert(text)</a>|Inserts text into the Hilbish command line.|
|<a href="#editor.getChar">getChar() -> string</a>|Reads a keystroke from the user. This is in a format| |<a href="#editor.getChar">getChar() -> string</a>|Reads a keystroke from the user. This is in a format of something like Ctrl-L.|
|<a href="#editor.setVimRegister">setVimRegister(register, text)</a>|Sets the vim register at `register` to hold the passed text.| |<a href="#editor.setVimRegister">setVimRegister(register, text)</a>|Sets the vim register at `register` to hold the passed text.|
<hr><div id='editor.getLine'> <hr><div id='editor.getLine'>
@ -43,7 +43,9 @@ hilbish.editor.getVimRegister(register) -> string
Returns the text that is at the register. Returns the text that is at the register.
#### Parameters #### Parameters
This function has no parameters. `string` **`register`**
</div> </div>
<hr><div id='editor.insert'> <hr><div id='editor.insert'>
@ -54,9 +56,11 @@ hilbish.editor.insert(text)
</a> </a>
</h4> </h4>
Inserts text into the line. Inserts text into the Hilbish command line.
#### Parameters #### Parameters
This function has no parameters. `string` **`text`**
</div> </div>
<hr><div id='editor.getChar'> <hr><div id='editor.getChar'>
@ -67,8 +71,7 @@ hilbish.editor.getChar() -> string
</a> </a>
</h4> </h4>
Reads a keystroke from the user. This is in a format Reads a keystroke from the user. This is in a format of something like Ctrl-L.
of something like Ctrl-L..
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
</div> </div>
@ -83,6 +86,8 @@ hilbish.editor.setVimRegister(register, text)
Sets the vim register at `register` to hold the passed text. Sets the vim register at `register` to hold the passed text.
#### Parameters #### Parameters
This function has no parameters. `string` **`text`**
</div> </div>

18
docs/api/hilbish/hilbish.history.md
View File

@ -16,9 +16,9 @@ method of saving history.
||| |||
|----|----| |----|----|
|<a href="#history.add">add(cmd)</a>|Adds a command to the history.| |<a href="#history.add">add(cmd)</a>|Adds a command to the history.|
|<a href="#history.all">all() -> table</a>|Retrieves all history.| |<a href="#history.all">all() -> table</a>|Retrieves all history as a table.|
|<a href="#history.clear">clear()</a>|Deletes all commands from the history.| |<a href="#history.clear">clear()</a>|Deletes all commands from the history.|
|<a href="#history.get">get(idx)</a>|Retrieves a command from the history based on the `idx`.| |<a href="#history.get">get(index)</a>|Retrieves a command from the history based on the `index`.|
|<a href="#history.size">size() -> number</a>|Returns the amount of commands in the history.| |<a href="#history.size">size() -> number</a>|Returns the amount of commands in the history.|
<hr><div id='history.add'> <hr><div id='history.add'>
@ -31,7 +31,9 @@ hilbish.history.add(cmd)
Adds a command to the history. Adds a command to the history.
#### Parameters #### Parameters
This function has no parameters. `string` **`cmd`**
</div> </div>
<hr><div id='history.all'> <hr><div id='history.all'>
@ -42,7 +44,7 @@ hilbish.history.all() -> table
</a> </a>
</h4> </h4>
Retrieves all history. Retrieves all history as a table.
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
</div> </div>
@ -62,15 +64,17 @@ This function has no parameters.
<hr><div id='history.get'> <hr><div id='history.get'>
<h4 class='heading'> <h4 class='heading'>
hilbish.history.get(idx) hilbish.history.get(index)
<a href="#history.get" class='heading-link'> <a href="#history.get" class='heading-link'>
<i class="fas fa-paperclip"></i> <i class="fas fa-paperclip"></i>
</a> </a>
</h4> </h4>
Retrieves a command from the history based on the `idx`. Retrieves a command from the history based on the `index`.
#### Parameters #### Parameters
This function has no parameters. `number` **`index`**
</div> </div>
<hr><div id='history.size'> <hr><div id='history.size'>

37
docs/api/hilbish/hilbish.jobs.md
View File

@ -17,11 +17,11 @@ interactive usage or with the functions defined below for use in external runner
## Functions ## Functions
||| |||
|----|----| |----|----|
|<a href="#jobs.add">add(cmdstr, args, execPath)</a>|Adds a new job to the job table. Note that this does not immediately run it.| |<a href="#jobs.add">add(cmdstr, args, execPath)</a>|Creates a new job. This function does not run the job. This function is intended to be|
|<a href="#jobs.all">all() -> table<@Job></a>|Returns a table of all job objects.| |<a href="#jobs.all">all() -> table[@Job]</a>|Returns a table of all job objects.|
|<a href="#jobs.disown">disown(id)</a>|Disowns a job. This deletes it from the job table.| |<a href="#jobs.disown">disown(id)</a>|Disowns a job. This simply deletes it from the list of jobs without stopping it.|
|<a href="#jobs.get">get(id) -> @Job</a>|Get a job object via its ID.| |<a href="#jobs.get">get(id) -> @Job</a>|Get a job object via its ID.|
|<a href="#jobs.last">last() -> @Job</a>|Returns the last added job from the table.| |<a href="#jobs.last">last() -> @Job</a>|Returns the last added job to the table.|
<hr><div id='jobs.add'> <hr><div id='jobs.add'>
<h4 class='heading'> <h4 class='heading'>
@ -31,14 +31,29 @@ hilbish.jobs.add(cmdstr, args, execPath)
</a> </a>
</h4> </h4>
Adds a new job to the job table. Note that this does not immediately run it. Creates a new job. This function does not run the job. This function is intended to be
used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
#### Parameters #### Parameters
This function has no parameters. `string` **`cmdstr`**
String that a user would write for the job
`table` **`args`**
Arguments for the commands. Has to include the name of the command.
`string` **`execPath`**
Binary to use to run the command. Does not
#### Example
```lua
hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')
````
</div> </div>
<hr><div id='jobs.all'> <hr><div id='jobs.all'>
<h4 class='heading'> <h4 class='heading'>
hilbish.jobs.all() -> table\<<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>> hilbish.jobs.all() -> table[<a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" style="text-decoration: none;" id="lol">Job</a>]
<a href="#jobs.all" class='heading-link'> <a href="#jobs.all" class='heading-link'>
<i class="fas fa-paperclip"></i> <i class="fas fa-paperclip"></i>
</a> </a>
@ -57,9 +72,11 @@ hilbish.jobs.disown(id)
</a> </a>
</h4> </h4>
Disowns a job. This deletes it from the job table. Disowns a job. This simply deletes it from the list of jobs without stopping it.
#### Parameters #### Parameters
This function has no parameters. `number` **`id`**
</div> </div>
<hr><div id='jobs.get'> <hr><div id='jobs.get'>
@ -83,7 +100,7 @@ hilbish.jobs.last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" sty
</a> </a>
</h4> </h4>
Returns the last added job from the table. Returns the last added job to the table.
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
</div> </div>

4
docs/api/hilbish/hilbish.module.md
View File

@ -64,6 +64,8 @@ hilbish.module.load(path)
Loads a module at the designated `path`. Loads a module at the designated `path`.
It will throw if any error occurs. It will throw if any error occurs.
#### Parameters #### Parameters
This function has no parameters. `string` **`path`**
</div> </div>

7
docs/api/hilbish/hilbish.os.md
View File

@ -1,6 +1,6 @@
--- ---
title: Module hilbish.os title: Module hilbish.os
description: OS Info description: operating system info
layout: doc layout: doc
menu: menu:
docs: docs:
@ -8,9 +8,8 @@ menu:
--- ---
## Introduction ## Introduction
The `os` interface provides simple text information properties about Provides simple text information properties about the current operating system.
the current OS on the systen. This mainly includes the name and This mainly includes the name and version.
version.
## Static module fields ## Static module fields
||| |||

18
docs/api/hilbish/hilbish.runner.md
View File

@ -17,7 +17,7 @@ write command in Fennel.
## Functions ## Functions
||| |||
|----|----| |----|----|
|<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function. It takes a callback,| |<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function.|
|<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`|
|<a href="#runner.sh">sh(cmd)</a>|Runs a command in Hilbish's shell script interpreter.| |<a href="#runner.sh">sh(cmd)</a>|Runs a command in Hilbish's shell script interpreter.|
@ -29,12 +29,14 @@ hilbish.runner.setMode(cb)
</a> </a>
</h4> </h4>
This is the same as the `hilbish.runnerMode` function. It takes a callback, This is the same as the `hilbish.runnerMode` function.
which will be used to execute all interactive input. It takes a callback, which will be used to execute all interactive input.
In normal cases, neither callbacks should be overrided by the user, In normal cases, neither callbacks should be overrided by the user,
as the higher level functions listed below this will handle it. as the higher level functions listed below this will handle it.
#### Parameters #### Parameters
This function has no parameters. `function` **`cb`**
</div> </div>
<hr><div id='runner.lua'> <hr><div id='runner.lua'>
@ -48,7 +50,9 @@ hilbish.runner.lua(cmd)
Evaluates `cmd` as Lua input. This is the same as using `dofile` Evaluates `cmd` as Lua input. This is the same as using `dofile`
or `load`, but is appropriated for the runner interface. or `load`, but is appropriated for the runner interface.
#### Parameters #### Parameters
This function has no parameters. `string` **`cmd`**
</div> </div>
<hr><div id='runner.sh'> <hr><div id='runner.sh'>
@ -62,6 +66,8 @@ hilbish.runner.sh(cmd)
Runs a command in Hilbish's shell script interpreter. Runs a command in Hilbish's shell script interpreter.
This is the equivalent of using `source`. This is the equivalent of using `source`.
#### Parameters #### Parameters
This function has no parameters. `string` **`cmd`**
</div> </div>

27
docs/api/hilbish/hilbish.timers.md
View File

@ -14,14 +14,10 @@ a few seconds, you don't have to rely on timing tricks, as Hilbish has a
timer API to set intervals and timeouts. timer API to set intervals and timeouts.
These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc
accessible with `doc hilbish`). But if you want slightly more control over accessible with `doc hilbish`, or `Module hilbish` on the Website).
them, there is the `hilbish.timers` interface. It allows you to get
a timer via ID and control them.
All functions documented with the `Timer` type refer to a Timer object.
An example of usage: An example of usage:
``` ```lua
local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function() local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function()
print 'hello!' print 'hello!'
end) end)
@ -33,7 +29,7 @@ print(t.running) // true
## Functions ## Functions
||| |||
|----|----| |----|----|
|<a href="#timers.create">create(type, time, callback) -> @Timer</a>|Creates a timer that runs based on the specified `time` in milliseconds.| |<a href="#timers.create">create(type, time, callback) -> @Timer</a>|Creates a timer that runs based on the specified `time`.|
|<a href="#timers.get">get(id) -> @Timer</a>|Retrieves a timer via its ID.| |<a href="#timers.get">get(id) -> @Timer</a>|Retrieves a timer via its ID.|
## Static module fields ## Static module fields
@ -50,10 +46,17 @@ hilbish.timers.create(type, time, callback) -> <a href="/Hilbish/docs/api/hilbis
</a> </a>
</h4> </h4>
Creates a timer that runs based on the specified `time` in milliseconds. Creates a timer that runs based on the specified `time`.
The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
#### Parameters #### Parameters
This function has no parameters. `number` **`type`**
What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
`number` **`time`**
The amount of time the function should run in milliseconds.
`function` **`callback`**
The function to run for the timer.
</div> </div>
<hr><div id='timers.get'> <hr><div id='timers.get'>
@ -66,7 +69,9 @@ hilbish.timers.get(id) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#tim
Retrieves a timer via its ID. Retrieves a timer via its ID.
#### Parameters #### Parameters
This function has no parameters. `number` **`id`**
</div> </div>
## Types ## Types

10
docs/api/terminal.md
View File

@ -14,8 +14,8 @@ The terminal library is a simple and lower level library for certain terminal in
||| |||
|----|----| |----|----|
|<a href="#restoreState">restoreState()</a>|Restores the last saved state of the terminal| |<a href="#restoreState">restoreState()</a>|Restores the last saved state of the terminal|
|<a href="#saveState">saveState()</a>|Saves the current state of the terminal| |<a href="#saveState">saveState()</a>|Saves the current state of the terminal.|
|<a href="#setRaw">setRaw()</a>|Puts the terminal in raw mode| |<a href="#setRaw">setRaw()</a>|Puts the terminal into raw mode.|
|<a href="#size">size()</a>|Gets the dimensions of the terminal. Returns a table with `width` and `height`| |<a href="#size">size()</a>|Gets the dimensions of the terminal. Returns a table with `width` and `height`|
<hr><div id='restoreState'> <hr><div id='restoreState'>
@ -39,7 +39,7 @@ terminal.saveState()
</a> </a>
</h4> </h4>
Saves the current state of the terminal Saves the current state of the terminal.
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
</div> </div>
@ -52,7 +52,7 @@ terminal.setRaw()
</a> </a>
</h4> </h4>
Puts the terminal in raw mode Puts the terminal into raw mode.
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
</div> </div>
@ -66,7 +66,7 @@ terminal.size()
</h4> </h4>
Gets the dimensions of the terminal. Returns a table with `width` and `height` Gets the dimensions of the terminal. Returns a table with `width` and `height`
Note: this is not the size in relation to the dimensions of the display NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.
#### Parameters #### Parameters
This function has no parameters. This function has no parameters.
</div> </div>

51
docs/runner-mode.md
View File

@ -1,7 +1,15 @@
Hilbish is *unique,* when interactive it first attempts to run input as Hilbish allows you to change how interactive text can be interpreted.
Lua and then tries shell script. But if you're normal, you wouldn't This is mainly due to the fact that the default method Hilbish uses
really be using Hilbish anyway but you'd also not want this is that it runs Lua first and then falls back to shell script.
(or maybe want Lua only in some cases.)
In some cases, someone might want to switch to just shell script to avoid
it while interactive but still have a Lua config, or go full Lua to use
Hilbish as a REPL. This also allows users to add alternative languages like
Fennel as the interactive script runner.
Runner mode can also be used to handle specific kinds of input before
evaluating like normal, which is how [Link.hsh](https://github.com/TorchedSammy/Link.hsh)
handles links.
The "runner mode" of Hilbish is customizable via `hilbish.runnerMode`, The "runner mode" of Hilbish is customizable via `hilbish.runnerMode`,
which determines how Hilbish will run user input. By default, this is which determines how Hilbish will run user input. By default, this is
@ -27,12 +35,20 @@ hilbish.runnerMode(function(input)
end) end)
The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode` The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode`
and also provides the sh and Lua runner functions that Hilbish itself uses. and also provides the shell script and Lua runner functions that Hilbish itself uses.
A runner function is expected to return 3 values: the input, exit code, and an error.
The input return is there incase you need to prompt for more input. A runner function is expected to return a table with the following values:
If you don't, just return the input passed to the runner function. - `exitCode` (number): Exit code of the command
The exit code has to be a number, it will be 0 otherwise and the error can be - `input` (string): The text input of the user. This is used by Hilbish to append extra input, in case
`nil` to indicate no error. more is requested.
- `err` (string): A string that represents an error from the runner.
This should only be set when, for example, there is a syntax error.
It can be set to a few special values for Hilbish to throw the right
hooks and have a better looking message.
- `<command>: not-found` will throw a `command.not-found` hook
based on what `<command>` is.
- `<command>: not-executable` will throw a `command.not-executable` hook.
- `continue` (boolean): Whether Hilbish should prompt the user for no input
## Functions ## Functions
These are the "low level" functions for the `hilbish.runner` interface. These are the "low level" functions for the `hilbish.runner` interface.
@ -41,21 +57,6 @@ These are the "low level" functions for the `hilbish.runner` interface.
+ sh(input) -> table > Runs `input` in Hilbish's sh interpreter + sh(input) -> table > Runs `input` in Hilbish's sh interpreter
+ lua(input) -> table > Evals `input` as Lua code + lua(input) -> table > Evals `input` as Lua code
The table value that runners return can have at least 4 values:
+ input (string): The full input text.
+ exitCode (number): Exit code (usually from a command)
+ continue (boolean): Whether to prompt the user for more input
(in the case of incomplete syntax)
+ err (string): A string that represents an error from the runner.
This should only be set when, for example, there is a syntax error.
It can be set to a few special values for Hilbish to throw the right
hooks and have a better looking message.
+ `<command>: not-found` will throw a `command.not-found` hook
based on what `<command>` is.
+ `<command>: not-executable` will throw a `command.not-executable` hook.
The others here are defined in Lua and have EmmyLua documentation.
These functions should be preferred over the previous ones. These functions should be preferred over the previous ones.
+ setCurrent(mode) > The same as `setMode`, but works with runners managed + setCurrent(mode) > The same as `setMode`, but works with runners managed
via the functions below. via the functions below.

13
editor.go
View File

@ -27,7 +27,8 @@ func editorLoader(rtm *rt.Runtime) *rt.Table {
// #interface editor // #interface editor
// insert(text) // insert(text)
// Inserts text into the line. // Inserts text into the Hilbish command line.
// #param text string
func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -46,8 +47,8 @@ func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface editor // #interface editor
// setVimRegister(register, text) // setVimRegister(register, text)
// Sets the vim register at `register` to hold the passed text. // Sets the vim register at `register` to hold the passed text.
// --- @param register string // #aram register string
// --- @param text string // #param text string
func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -71,7 +72,7 @@ func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface editor // #interface editor
// getVimRegister(register) -> string // getVimRegister(register) -> string
// Returns the text that is at the register. // Returns the text that is at the register.
// --- @param register string // #param register string
func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -90,6 +91,7 @@ func editorGetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface editor // #interface editor
// getLine() -> string // getLine() -> string
// Returns the current input line. // Returns the current input line.
// #returns string
func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
buf := lr.rl.GetLine() buf := lr.rl.GetLine()
@ -98,8 +100,7 @@ func editorGetLine(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface editor // #interface editor
// getChar() -> string // getChar() -> string
// Reads a keystroke from the user. This is in a format // Reads a keystroke from the user. This is in a format of something like Ctrl-L.
// of something like Ctrl-L..
func editorReadChar(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func editorReadChar(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
buf := lr.rl.ReadChar() buf := lr.rl.ReadChar()

138
emmyLuaDocs/hilbish.lua
View File

@ -2,35 +2,30 @@
local hilbish = {} local hilbish = {}
--- This is an alias (ha) for the `hilbish.alias` function. --- This is an alias (ha) for the [hilbish.alias](../#alias) function.
--- @param alias string --- @param alias string
--- @param cmd string --- @param cmd string
function hilbish.aliases.add(alias, cmd) end function hilbish.aliases.add(alias, cmd) end
--- This is the same as the `hilbish.runnerMode` function. It takes a callback, --- This is the same as the `hilbish.runnerMode` function.
--- which will be used to execute all interactive input. --- It takes a callback, which will be used to execute all interactive input.
--- In normal cases, neither callbacks should be overrided by the user, --- In normal cases, neither callbacks should be overrided by the user,
--- as the higher level functions listed below this will handle it. --- as the higher level functions listed below this will handle it.
--- @param cb function
function hilbish.runner.setMode(cb) end function hilbish.runner.setMode(cb) end
--- Returns the current input line. --- Returns the current input line.
function hilbish.editor.getLine() end function hilbish.editor.getLine() end
--- Returns the text that is at the register. --- Returns the text that is at the register.
--- @param register string
function hilbish.editor.getVimRegister(register) end function hilbish.editor.getVimRegister(register) end
--- Inserts text into the line. --- Inserts text into the Hilbish command line.
function hilbish.editor.insert(text) end function hilbish.editor.insert(text) end
--- Reads a keystroke from the user. This is in a format --- Reads a keystroke from the user. This is in a format of something like Ctrl-L.
--- of something like Ctrl-L..
function hilbish.editor.getChar() end function hilbish.editor.getChar() end
--- Sets the vim register at `register` to hold the passed text. --- Sets the vim register at `register` to hold the passed text.
--- @param register string
--- @param text string
function hilbish.editor.setVimRegister(register, text) end function hilbish.editor.setVimRegister(register, text) end
--- Return binaries/executables based on the provided parameters. --- Return binaries/executables based on the provided parameters.
@ -65,40 +60,31 @@ function hilbish.alias(cmd, orig) end
--- ---
function hilbish.appendPath(dir) end function hilbish.appendPath(dir) end
--- Registers a completion handler for `scope`. --- Registers a completion handler for the specified scope.
--- A `scope` is currently only expected to be `command.<cmd>`, --- A `scope` is currently only expected to be `command.<cmd>`,
--- replacing <cmd> with the name of the command (for example `command.git`). --- replacing <cmd> with the name of the command (for example `command.git`).
--- `cb` must be a function that returns a table of "completion groups." --- The documentation for completions, under Features/Completions or `doc completions`
--- Check `doc completions` for more information. --- provides more details.
--- @param scope string
--- @param cb function
function hilbish.complete(scope, cb) end function hilbish.complete(scope, cb) end
--- Returns the current directory of the shell --- Returns the current directory of the shell
--- @returns string
function hilbish.cwd() end function hilbish.cwd() end
--- Replaces running hilbish with `cmd` --- Replaces the currently running Hilbish instance with the supplied command.
--- @param cmd string --- This can be used to do an in-place restart.
function hilbish.exec(cmd) end function hilbish.exec(cmd) end
--- Puts `fn` in a goroutine --- Puts `fn` in a Goroutine.
--- @param fn function --- This can be used to run any function in another thread.
--- **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.**
function hilbish.goro(fn) end function hilbish.goro(fn) end
--- Line highlighter handler. This is mainly for syntax highlighting, but in --- Line highlighter handler.
--- reality could set the input of the prompt to *display* anything. The --- This is mainly for syntax highlighting, but in reality could set the input
--- callback is passed the current line and is expected to return a line that --- of the prompt to *display* anything. The callback is passed the current line
--- will be used as the input display. --- and is expected to return a line that will be used as the input display.
--- Note that to set a highlighter, one has to override this function. --- Note that to set a highlighter, one has to override this function.
--- Example: ---
--- ```
--- function hilbish.highlighter(line)
--- return line:gsub('"%w+"', function(c) return lunacolors.green(c) end)
--- end
--- ```
--- This code will highlight all double quoted strings in green.
--- @param line string
function hilbish.highlighter(line) end function hilbish.highlighter(line) end
--- The command line hint handler. It gets called on every key insert to --- The command line hint handler. It gets called on every key insert to
@ -106,52 +92,43 @@ function hilbish.highlighter(line) end
--- line and cursor position. It is expected to return a string which is used --- line and cursor position. It is expected to return a string which is used
--- as the text for the hint. This is by default a shim. To set hints, --- as the text for the hint. This is by default a shim. To set hints,
--- override this function with your custom handler. --- override this function with your custom handler.
--- @param line string ---
--- @param pos number ---
function hilbish.hinter(line, pos) end function hilbish.hinter(line, pos) end
--- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim --- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
--- @param mode string --- `emacs` is the default. Setting it to `vim` changes behavior of input to be
--- Vim-like with modes and Vim keybinds.
function hilbish.inputMode(mode) end function hilbish.inputMode(mode) end
--- Runs the `cb` function every `time` milliseconds. --- Runs the `cb` function every `time` milliseconds.
--- This creates a timer that starts immediately. --- This creates a timer that starts immediately.
--- @param cb function
--- @param time number
--- @return Timer
function hilbish.interval(cb, time) end function hilbish.interval(cb, time) end
--- Changes the continued line prompt to `str` --- Changes the text prompt when Hilbish asks for more input.
--- @param str string --- This will show up when text is incomplete, like a missing quote
---
---
function hilbish.multiprompt(str) end function hilbish.multiprompt(str) end
--- Prepends `dir` to $PATH --- Prepends `dir` to $PATH.
--- @param dir string
function hilbish.prependPath(dir) end function hilbish.prependPath(dir) end
--- Changes the shell prompt to `str` --- Changes the shell prompt to the provided string.
--- There are a few verbs that can be used in the prompt text. --- There are a few verbs that can be used in the prompt text.
--- These will be formatted and replaced with the appropriate values. --- These will be formatted and replaced with the appropriate values.
--- `%d` - Current working directory --- `%d` - Current working directory
--- `%u` - Name of current user --- `%u` - Name of current user
--- `%h` - Hostname of device --- `%h` - Hostname of device
--- @param str string ---
--- @param typ? string Type of prompt, being left or right. Left by default.
function hilbish.prompt(str, typ) end function hilbish.prompt(str, typ) end
--- Read input from the user, using Hilbish's line editor/input reader. --- Read input from the user, using Hilbish's line editor/input reader.
--- This is a separate instance from the one Hilbish actually uses. --- This is a separate instance from the one Hilbish actually uses.
--- Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen) --- Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).
--- @param prompt? string
--- @returns string|nil
function hilbish.read(prompt) end function hilbish.read(prompt) end
--- Runs `cmd` in Hilbish's sh interpreter. --- Runs `cmd` in Hilbish's shell script interpreter.
--- If returnOut is true, the outputs of `cmd` will be returned as the 2nd and
--- 3rd values instead of being outputted to the terminal.
--- @param cmd string
--- @param returnOut boolean
--- @returns number, string, string
function hilbish.run(cmd, returnOut) end function hilbish.run(cmd, returnOut) end
--- Sets the execution/runner mode for interactive Hilbish. This determines whether --- Sets the execution/runner mode for interactive Hilbish. This determines whether
@ -159,20 +136,14 @@ function hilbish.run(cmd, returnOut) end
--- Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua), --- 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 --- sh, and lua. It also accepts a function, to which if it is passed one
--- will call it to execute user input instead. --- will call it to execute user input instead.
--- @param mode string|function
function hilbish.runnerMode(mode) end function hilbish.runnerMode(mode) end
--- Runs the `cb` function after `time` in milliseconds. --- Runs the `cb` function after `time` in milliseconds.
--- This creates a timer that starts immediately. --- This creates a Timer that starts immediately.
--- @param cb function
--- @param time number
--- @returns Timer
function hilbish.timeout(cb, time) end function hilbish.timeout(cb, time) end
--- Checks if `name` is a valid command. --- Checks if `name` is a valid command.
--- Will return the path of the binary, or a basename if it's a commander. --- Will return the path of the binary, or a basename if it's a commander.
--- @param name string
--- @returns string
function hilbish.which(name) end function hilbish.which(name) end
--- Puts a job in the background. This acts the same as initially running a job. --- Puts a job in the background. This acts the same as initially running a job.
@ -184,7 +155,6 @@ function hilbish.jobs:foreground() end
--- Evaluates `cmd` as Lua input. This is the same as using `dofile` --- Evaluates `cmd` as Lua input. This is the same as using `dofile`
--- or `load`, but is appropriated for the runner interface. --- or `load`, but is appropriated for the runner interface.
--- @param cmd string
function hilbish.runner.lua(cmd) end function hilbish.runner.lua(cmd) end
--- Sets/toggles the option of automatically flushing output. --- Sets/toggles the option of automatically flushing output.
@ -221,7 +191,6 @@ function hilbish.module.load(path) end
--- Runs a command in Hilbish's shell script interpreter. --- Runs a command in Hilbish's shell script interpreter.
--- This is the equivalent of using `source`. --- This is the equivalent of using `source`.
--- @param cmd string
function hilbish.runner.sh(cmd) end function hilbish.runner.sh(cmd) end
--- Starts a timer. --- Starts a timer.
@ -231,30 +200,26 @@ function hilbish.timers:start() end
function hilbish.timers:stop() end function hilbish.timers:stop() end
--- Removes an alias. --- Removes an alias.
--- @param name string
function hilbish.aliases.delete(name) end function hilbish.aliases.delete(name) end
--- Get a table of all aliases, with string keys as the alias and the value as the command. --- Get a table of all aliases, with string keys as the alias and the value as the command.
--- @returns table<string, string> ---
---
function hilbish.aliases.list() end function hilbish.aliases.list() end
--- Tries to resolve an alias to its command. --- Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
--- @param alias string
--- @returns string
function hilbish.aliases.resolve(alias) end function hilbish.aliases.resolve(alias) end
--- Adds a new job to the job table. Note that this does not immediately run it. --- Creates a new job. This function does not run the job. This function is intended to be
--- @param cmdstr string --- used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
--- @param args table ---
--- @param execPath string ---
function hilbish.jobs.add(cmdstr, args, execPath) end function hilbish.jobs.add(cmdstr, args, execPath) end
--- Returns a table of all job objects. --- Returns a table of all job objects.
--- @returns table<Job>
function hilbish.jobs.all() end function hilbish.jobs.all() end
--- Disowns a job. This deletes it from the job table. --- Disowns a job. This simply deletes it from the list of jobs without stopping it.
--- @param id number
function hilbish.jobs.disown(id) end function hilbish.jobs.disown(id) end
--- Get a job object via its ID. --- Get a job object via its ID.
@ -262,39 +227,28 @@ function hilbish.jobs.disown(id) end
--- @returns Job --- @returns Job
function hilbish.jobs.get(id) end function hilbish.jobs.get(id) end
--- Returns the last added job from the table. --- Returns the last added job to the table.
--- @returns Job
function hilbish.jobs.last() end function hilbish.jobs.last() end
--- Adds a command to the history. --- Adds a command to the history.
--- @param cmd string
function hilbish.history.add(cmd) end function hilbish.history.add(cmd) end
--- Retrieves all history. --- Retrieves all history as a table.
--- @returns table
function hilbish.history.all() end function hilbish.history.all() end
--- Deletes all commands from the history. --- Deletes all commands from the history.
function hilbish.history.clear() end function hilbish.history.clear() end
--- Retrieves a command from the history based on the `idx`. --- Retrieves a command from the history based on the `index`.
--- @param idx number function hilbish.history.get(index) end
function hilbish.history.get(idx) end
--- Returns the amount of commands in the history. --- Returns the amount of commands in the history.
--- @returns number
function hilbish.history.size() end function hilbish.history.size() end
--- Creates a timer that runs based on the specified `time` in milliseconds. --- Creates a timer that runs based on the specified `time`.
--- The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
--- @param type number
--- @param time number
--- @param callback function
function hilbish.timers.create(type, time, callback) end function hilbish.timers.create(type, time, callback) end
--- Retrieves a timer via its ID. --- Retrieves a timer via its ID.
--- @param id number
--- @returns Timer
function hilbish.timers.get(id) end function hilbish.timers.get(id) end
return hilbish return hilbish

6
emmyLuaDocs/terminal.lua
View File

@ -5,14 +5,14 @@ local terminal = {}
--- Restores the last saved state of the terminal --- Restores the last saved state of the terminal
function terminal.restoreState() end function terminal.restoreState() end
--- Saves the current state of the terminal --- Saves the current state of the terminal.
function terminal.saveState() end function terminal.saveState() end
--- Puts the terminal in raw mode --- Puts the terminal into raw mode.
function terminal.setRaw() end function terminal.setRaw() end
--- Gets the dimensions of the terminal. Returns a table with `width` and `height` --- Gets the dimensions of the terminal. Returns a table with `width` and `height`
--- Note: this is not the size in relation to the dimensions of the display --- NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.
function terminal.size() end function terminal.size() end
return terminal return terminal

6
golibs/terminal/terminal.go
View File

@ -34,7 +34,7 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
// size() // size()
// Gets the dimensions of the terminal. Returns a table with `width` and `height` // Gets the dimensions of the terminal. Returns a table with `width` and `height`
// Note: this is not the size in relation to the dimensions of the display // NOTE: The size refers to the amount of columns and rows of text that can fit in the terminal.
func termsize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func termsize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
w, h, err := term.GetSize(int(os.Stdin.Fd())) w, h, err := term.GetSize(int(os.Stdin.Fd()))
if err != nil { if err != nil {
@ -49,7 +49,7 @@ func termsize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// saveState() // saveState()
// Saves the current state of the terminal // Saves the current state of the terminal.
func termsaveState(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func termsaveState(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
state, err := term.GetState(int(os.Stdin.Fd())) state, err := term.GetState(int(os.Stdin.Fd()))
if err != nil { if err != nil {
@ -72,7 +72,7 @@ func termrestoreState(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// setRaw() // setRaw()
// Puts the terminal in raw mode // Puts the terminal into raw mode.
func termsetRaw(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func termsetRaw(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
_, err := term.MakeRaw(int(os.Stdin.Fd())) _, err := term.MakeRaw(int(os.Stdin.Fd()))
if err != nil { if err != nil {

26
job.go
View File

@ -414,10 +414,16 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface jobs // #interface jobs
// add(cmdstr, args, execPath) // add(cmdstr, args, execPath)
// Adds a new job to the job table. Note that this does not immediately run it. // Creates a new job. This function does not run the job. This function is intended to be
// --- @param cmdstr string // used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
// --- @param args table // #param cmdstr string String that a user would write for the job
// --- @param execPath string // #param args table Arguments for the commands. Has to include the name of the command.
// #param execPath string Binary to use to run the command. Does not
/*
#example
hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')
#example
*/
func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(3); err != nil { if err := c.CheckNArgs(3); err != nil {
return nil, err return nil, err
@ -448,9 +454,9 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
} }
// #interface jobs // #interface jobs
// all() -> table<@Job> // all() -> table[@Job]
// Returns a table of all job objects. // Returns a table of all job objects.
// --- @returns table<Job> // #returns table[Job]
func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
j.mu.RLock() j.mu.RLock()
defer j.mu.RUnlock() defer j.mu.RUnlock()
@ -465,8 +471,8 @@ func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface jobs // #interface jobs
// disown(id) // disown(id)
// Disowns a job. This deletes it from the job table. // Disowns a job. This simply deletes it from the list of jobs without stopping it.
// --- @param id number // #param id number
func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -486,8 +492,8 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface jobs // #interface jobs
// last() -> @Job // last() -> @Job
// Returns the last added job from the table. // Returns the last added job to the table.
// --- @returns Job // #returns Job
func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
j.mu.RLock() j.mu.RLock()
defer j.mu.RUnlock() defer j.mu.RUnlock()

1
module.go
View File

@ -61,6 +61,7 @@ func moduleLoader(rtm *rt.Runtime) *rt.Table {
// load(path) // load(path)
// Loads a module at the designated `path`. // Loads a module at the designated `path`.
// It will throw if any error occurs. // It will throw if any error occurs.
// #param path string
func moduleLoad(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func moduleLoad(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(1); err != nil { if err := c.CheckNArgs(1); err != nil {
return nil, err return nil, err

7
os.go
View File

@ -8,10 +8,9 @@ import (
) )
// #interface os // #interface os
// OS Info // operating system info
// The `os` interface provides simple text information properties about // Provides simple text information properties about the current operating system.
// the current OS on the systen. This mainly includes the name and // This mainly includes the name and version.
// version.
// #field family Family name of the current OS // #field family Family name of the current OS
// #field name Pretty name of the current OS // #field name Pretty name of the current OS
// #field version Version of the current OS // #field version Version of the current OS

14
rl.go
View File

@ -267,7 +267,7 @@ func (lr *lineReader) Loader(rtm *rt.Runtime) *rt.Table {
// #interface history // #interface history
// add(cmd) // add(cmd)
// Adds a command to the history. // Adds a command to the history.
// --- @param cmd string // #param cmd string
func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -284,15 +284,15 @@ func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
// #interface history // #interface history
// size() -> number // size() -> number
// Returns the amount of commands in the history. // Returns the amount of commands in the history.
// --- @returns number // #eturns number
func (lr *lineReader) luaSize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (lr *lineReader) luaSize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
return c.PushingNext1(t.Runtime, rt.IntValue(int64(lr.fileHist.Len()))), nil return c.PushingNext1(t.Runtime, rt.IntValue(int64(lr.fileHist.Len()))), nil
} }
// #interface history // #interface history
// get(idx) // get(index)
// Retrieves a command from the history based on the `idx`. // Retrieves a command from the history based on the `index`.
// --- @param idx number // #param index number
func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -309,8 +309,8 @@ func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
// #interface history // #interface history
// all() -> table // all() -> table
// Retrieves all history. // Retrieves all history as a table.
// --- @returns table // #returns table
func (lr *lineReader) luaAllHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (lr *lineReader) luaAllHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
tbl := rt.NewTable() tbl := rt.NewTable()
size := lr.fileHist.Len() size := lr.fileHist.Len()

10
runnermode.go
View File

@ -28,18 +28,18 @@ func runnerModeLoader(rtm *rt.Runtime) *rt.Table {
// #interface runner // #interface runner
// setMode(cb) // setMode(cb)
// This is the same as the `hilbish.runnerMode` function. It takes a callback, // This is the same as the `hilbish.runnerMode` function.
// which will be used to execute all interactive input. // It takes a callback, which will be used to execute all interactive input.
// In normal cases, neither callbacks should be overrided by the user, // In normal cases, neither callbacks should be overrided by the user,
// as the higher level functions listed below this will handle it. // as the higher level functions listed below this will handle it.
// --- @param cb function // #param cb function
func _runnerMode() {} func _runnerMode() {}
// #interface runner // #interface runner
// sh(cmd) // sh(cmd)
// Runs a command in Hilbish's shell script interpreter. // Runs a command in Hilbish's shell script interpreter.
// This is the equivalent of using `source`. // This is the equivalent of using `source`.
// --- @param cmd string // #param cmd string
func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -67,7 +67,7 @@ func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// lua(cmd) // lua(cmd)
// Evaluates `cmd` as Lua input. This is the same as using `dofile` // Evaluates `cmd` as Lua input. This is the same as using `dofile`
// or `load`, but is appropriated for the runner interface. // or `load`, but is appropriated for the runner interface.
// --- @param cmd string // #param cmd string
func luaRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func luaRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err

22
timerhandler.go
View File

@ -63,11 +63,10 @@ func (th *timersModule) get(id int) *timer {
// #interface timers // #interface timers
// create(type, time, callback) -> @Timer // create(type, time, callback) -> @Timer
// Creates a timer that runs based on the specified `time` in milliseconds. // Creates a timer that runs based on the specified `time`.
// The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT` // #param type number What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
// --- @param type number // #param time number The amount of time the function should run in milliseconds.
// --- @param time number // #param callback function The function to run for the timer.
// --- @param callback function
func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(3); err != nil { if err := c.CheckNArgs(3); err != nil {
return nil, err return nil, err
@ -93,8 +92,8 @@ func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface timers // #interface timers
// get(id) -> @Timer // get(id) -> @Timer
// Retrieves a timer via its ID. // Retrieves a timer via its ID.
// --- @param id number // #param id number
// --- @returns Timer // #returns Timer
func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) { func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil { if err := c.Check1Arg(); err != nil {
return nil, err return nil, err
@ -122,15 +121,10 @@ a few seconds, you don't have to rely on timing tricks, as Hilbish has a
timer API to set intervals and timeouts. timer API to set intervals and timeouts.
These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc
accessible with `doc hilbish`). But if you want slightly more control over accessible with `doc hilbish`, or `Module hilbish` on the Website).
them, there is the `hilbish.timers` interface. It allows you to get
a timer via ID and control them.
## Timer Object
All functions documented with the `Timer` type refer to a Timer object.
An example of usage: An example of usage:
``` ```lua
local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function() local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function()
print 'hello!' print 'hello!'
end) end)

1
website/config.toml
View File

@ -35,6 +35,7 @@ lineNumbersInTable = false
noClasses = false noClasses = false
codeFences = true codeFences = true
guessSyntax = true guessSyntax = true
tabWidth = 4
[author] [author]
[author.sammyette] [author.sammyette]