sammyette
/
Hilbish
mirror of https://github.com/Hilbis/Hilbish
2
2
Fork 0
Code Issues Releases Wiki Activity

refactor: update documentation for everything

pull/260/head
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
// 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 cmd string
func _hlalias() {}
// #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.
// --- @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) {
aliasesList := rt.NewTable()
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
// delete(name)
// Removes an alias.
// --- @param name string
// #param name string
func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -147,10 +155,10 @@ func (a *aliasModule) luaDelete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// #interface aliases
// resolve(alias) -> command (string)
// Tries to resolve an alias to its command.
// --- @param alias string
// --- @returns string
// resolve(alias) -> string?
// Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
// #param alias string
// #returns string
func (a *aliasModule) luaResolve(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err

135
api.go
View File

@ -190,12 +190,10 @@ func unsetVimMode() {
}
// run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)
// Runs `cmd` in Hilbish's sh 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
// Runs `cmd` in Hilbish's shell script interpreter.
// #param cmd string
// #param returnOut boolean If this is true, the function will return the standard output and error of the command instead of printing it.
// #returns number, string, string
func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -238,7 +236,7 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// cwd() -> string
// Returns the current directory of the shell
// --- @returns string
// #returns string
func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
cwd, _ := os.Getwd()
@ -249,9 +247,9 @@ func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// read(prompt) -> input (string)
// Read input from the user, using Hilbish's line editor/input reader.
// 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)
// --- @param prompt? string
// --- @returns string|nil
// Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).
// #param prompt? string
// #returns string|nil
func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
luaprompt := c.Arg(0)
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)
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.
These will be formatted and replaced with the appropriate values.
`%d` - Current working directory
`%u` - Name of current user
`%h` - Hostname of device
--- @param str string
--- @param typ? string Type of prompt, being left or right. Left by default.
#param str string
#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) {
err := c.Check1Arg()
@ -320,8 +325,28 @@ func hlprompt(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// multiprompt(str)
// Changes the continued line prompt to `str`
// --- @param str string
// Changes the text prompt when Hilbish asks for more input.
// 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) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -415,8 +440,9 @@ func appendPath(dir string) {
}
// exec(cmd)
// Replaces running hilbish with `cmd`
// --- @param cmd string
// Replaces the currently running Hilbish instance with the supplied command.
// This can be used to do an in-place restart.
// #param cmd string
func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -450,8 +476,10 @@ func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// goro(fn)
// Puts `fn` in a goroutine
// --- @param fn function
// 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.**
// #param fn function
func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -474,10 +502,10 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// timeout(cb, time) -> @Timer
// Runs the `cb` function after `time` in milliseconds.
// This creates a timer that starts immediately.
// --- @param cb function
// --- @param time number
// --- @returns Timer
// This creates a Timer that starts immediately.
// #param cb function
// #param time number
// #returns Timer
func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil {
return nil, err
@ -501,9 +529,9 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// interval(cb, time) -> @Timer
// Runs the `cb` function every `time` milliseconds.
// This creates a timer that starts immediately.
// --- @param cb function
// --- @param time number
// --- @return Timer
// #param cb function
// #param time number
// #return Timer
func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(2); err != nil {
return nil, err
@ -525,13 +553,13 @@ func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// 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>`,
// replacing <cmd> with the name of the command (for example `command.git`).
// `cb` must be a function that returns a table of "completion groups."
// Check `doc completions` for more information.
// --- @param scope string
// --- @param cb function
// The documentation for completions, under Features/Completions or `doc completions`
// provides more details.
// #param scope string
// #param cb function
func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
scope, cb, err := util.HandleStrCallback(t, c)
if err != nil {
@ -543,8 +571,8 @@ func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// prependPath(dir)
// Prepends `dir` to $PATH
// --- @param dir string
// Prepends `dir` to $PATH.
// #param dir string
func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -567,8 +595,8 @@ func hlprependPath(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// which(name) -> string
// Checks if `name` is a valid command.
// Will return the path of the binary, or a basename if it's a commander.
// --- @param name string
// --- @returns string
// #param name string
// #returns string
func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -598,8 +626,10 @@ func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// inputMode(mode)
// Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
// --- @param mode string
// 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.
// #param mode string
func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
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),
// sh, and lua. It also accepts a function, to which if it is passed one
// 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) {
if err := c.Check1Arg(); err != nil {
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
// as the text for the hint. This is by default a shim. To set hints,
// override this function with your custom handler.
// --- @param line string
// --- @param pos number
// #param line string
// #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) {
return c.Next(), nil
}
// highlighter(line)
// Line highlighter handler. This is mainly for syntax highlighting, but in
// reality could set the input of the prompt to *display* anything. The
// callback is passed the current line and is expected to return a line that
// will be used as the input display.
// Line highlighter handler.
// This is mainly for syntax highlighting, but in reality could set the input
// of the prompt to *display* anything. The callback is passed the current line
// 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.
// Example:
// ```
// #example
// --This code will highlight all double quoted strings in green.
// 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
// #example
// #param line string
func hlhighlighter(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
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="#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="#exec">exec(cmd)</a>|Replaces running hilbish with `cmd`|
|<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="#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="#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="#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="#multiprompt">multiprompt(str)</a>|Changes the continued line prompt to `str`|
|<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="#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="#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="#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="#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.|
@ -111,13 +111,18 @@ hilbish.complete(scope, cb)
</a>
</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>`,
replacing <cmd> with the name of the command (for example `command.git`).
`cb` must be a function that returns a table of "completion groups."
Check `doc completions` for more information.
The documentation for completions, under Features/Completions or `doc completions`
provides more details.
#### Parameters
This function has no parameters.
`string` **`scope`**
`function` **`cb`**
</div>
<hr><div id='cwd'>
@ -141,9 +146,12 @@ hilbish.exec(cmd)
</a>
</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
This function has no parameters.
`string` **`cmd`**
</div>
<hr><div id='goro'>
@ -154,9 +162,13 @@ hilbish.goro(fn)
</a>
</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
This function has no parameters.
`function` **`fn`**
</div>
<hr><div id='highlighter'>
@ -167,20 +179,23 @@ hilbish.highlighter(line)
</a>
</h4>
Line highlighter handler. This is mainly for syntax highlighting, but in
reality could set the input of the prompt to *display* anything. The
callback is passed the current line and is expected to return a line that
will be used as the input display.
Line highlighter handler.
This is mainly for syntax highlighting, but in reality could set the input
of the prompt to *display* anything. The callback is passed the current line
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.
Example:
```
#### Parameters
`string` **`line`**
#### Example
```lua
--This code will highlight all double quoted strings in green.
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.
#### Parameters
This function has no parameters.
````
</div>
<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
as the text for the hint. This is by default a shim. To set hints,
override this function with your custom handler.
#### 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>
<hr><div id='inputMode'>
@ -208,9 +237,13 @@ hilbish.inputMode(mode)
</a>
</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
This function has no parameters.
`string` **`mode`**
</div>
<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.
This creates a timer that starts immediately.
#### Parameters
This function has no parameters.
`function` **`cb`**
`number` **`time`**
</div>
<hr><div id='multiprompt'>
@ -235,9 +273,32 @@ hilbish.multiprompt(str)
</a>
</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
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>
<hr><div id='prependPath'>
@ -248,9 +309,11 @@ hilbish.prependPath(dir)
</a>
</h4>
Prepends `dir` to $PATH
Prepends `dir` to $PATH.
#### Parameters
This function has no parameters.
`string` **`dir`**
</div>
<hr><div id='prompt'>
@ -261,14 +324,28 @@ hilbish.prompt(str, typ)
</a>
</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.
These will be formatted and replaced with the appropriate values.
`%d` - Current working directory
`%u` - Name of current user
`%h` - Hostname of device
#### 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>
<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.
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
This function has no parameters.
`string` **`prompt?`**
</div>
<hr><div id='run'>
@ -294,11 +373,14 @@ hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (strin
</a>
</h4>
Runs `cmd` in Hilbish's sh 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.
Runs `cmd` in Hilbish's shell script interpreter.
#### 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>
<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
will call it to execute user input instead.
#### Parameters
This function has no parameters.
`string|function` **`mode`**
</div>
<hr><div id='timeout'>
@ -327,9 +411,14 @@ hilbish.timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#
</h4>
Runs the `cb` function after `time` in milliseconds.
This creates a timer that starts immediately.
This creates a Timer that starts immediately.
#### Parameters
This function has no parameters.
`function` **`cb`**
`number` **`time`**
</div>
<hr><div id='which'>
@ -343,7 +432,9 @@ hilbish.which(name) -> string
Checks if `name` is a valid command.
Will return the path of the binary, or a basename if it's a commander.
#### Parameters
This function has no parameters.
`string` **`name`**
</div>
## 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
|||
|----|----|
|<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.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.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) -> string?</a>|Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.|
<hr><div id='aliases.add'>
<h4 class='heading'>
@ -26,7 +26,7 @@ hilbish.aliases.add(alias, cmd)
</a>
</h4>
This is an alias (ha) for the `hilbish.alias` function.
This is an alias (ha) for the [hilbish.alias](../#alias) function.
#### Parameters
This function has no parameters.
</div>
@ -41,32 +41,45 @@ hilbish.aliases.delete(name)
Removes an alias.
#### Parameters
This function has no parameters.
`string` **`name`**
</div>
<hr><div id='aliases.list'>
<h4 class='heading'>
hilbish.aliases.list() -> table\<string, string>
hilbish.aliases.list() -> table[string, string]
<a href="#aliases.list" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Get a table of all aliases, with string keys as the alias and the value as the command.
#### Parameters
This function has no parameters.
#### Example
```lua
hilbish.aliases.add('hi', 'echo hi')
local aliases = hilbish.aliases.list()
-- -> {hi = 'echo hi'}
````
</div>
<hr><div id='aliases.resolve'>
<h4 class='heading'>
hilbish.aliases.resolve(alias) -> command (string)
hilbish.aliases.resolve(alias) -> string?
<a href="#aliases.resolve" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</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
This function has no parameters.
`string` **`alias`**
</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.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.getChar">getChar() -> string</a>|Reads a keystroke from the user. This is in a format|
|<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 of something like Ctrl-L.|
|<a href="#editor.setVimRegister">setVimRegister(register, text)</a>|Sets the vim register at `register` to hold the passed text.|
<hr><div id='editor.getLine'>
@ -43,7 +43,9 @@ hilbish.editor.getVimRegister(register) -> string
Returns the text that is at the register.
#### Parameters
This function has no parameters.
`string` **`register`**
</div>
<hr><div id='editor.insert'>
@ -54,9 +56,11 @@ hilbish.editor.insert(text)
</a>
</h4>
Inserts text into the line.
Inserts text into the Hilbish command line.
#### Parameters
This function has no parameters.
`string` **`text`**
</div>
<hr><div id='editor.getChar'>
@ -67,8 +71,7 @@ hilbish.editor.getChar() -> string
</a>
</h4>
Reads a keystroke from the user. This is in a format
of something like Ctrl-L..
Reads a keystroke from the user. This is in a format of something like Ctrl-L.
#### Parameters
This function has no parameters.
</div>
@ -83,6 +86,8 @@ hilbish.editor.setVimRegister(register, text)
Sets the vim register at `register` to hold the passed text.
#### Parameters
This function has no parameters.
`string` **`text`**
</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.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.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.|
<hr><div id='history.add'>
@ -31,7 +31,9 @@ hilbish.history.add(cmd)
Adds a command to the history.
#### Parameters
This function has no parameters.
`string` **`cmd`**
</div>
<hr><div id='history.all'>
@ -42,7 +44,7 @@ hilbish.history.all() -> table
</a>
</h4>
Retrieves all history.
Retrieves all history as a table.
#### Parameters
This function has no parameters.
</div>
@ -62,15 +64,17 @@ This function has no parameters.
<hr><div id='history.get'>
<h4 class='heading'>
hilbish.history.get(idx)
hilbish.history.get(index)
<a href="#history.get" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h4>
Retrieves a command from the history based on the `idx`.
Retrieves a command from the history based on the `index`.
#### Parameters
This function has no parameters.
`number` **`index`**
</div>
<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
|||
|----|----|
|<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.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.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.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.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'>
<h4 class='heading'>
@ -31,14 +31,29 @@ hilbish.jobs.add(cmdstr, args, execPath)
</a>
</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
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>
<hr><div id='jobs.all'>
<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'>
<i class="fas fa-paperclip"></i>
</a>
@ -57,9 +72,11 @@ hilbish.jobs.disown(id)
</a>
</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
This function has no parameters.
`number` **`id`**
</div>
<hr><div id='jobs.get'>
@ -83,7 +100,7 @@ hilbish.jobs.last() -> <a href="/Hilbish/docs/api/hilbish/hilbish.jobs/#job" sty
</a>
</h4>
Returns the last added job from the table.
Returns the last added job to the table.
#### Parameters
This function has no parameters.
</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`.
It will throw if any error occurs.
#### Parameters
This function has no parameters.
`string` **`path`**
</div>

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

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

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

@ -17,7 +17,7 @@ write command in Fennel.
## 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.sh">sh(cmd)</a>|Runs a command in Hilbish's shell script interpreter.|
@ -29,12 +29,14 @@ hilbish.runner.setMode(cb)
</a>
</h4>
This is the same as the `hilbish.runnerMode` function. It takes a callback,
which will be used to execute all interactive input.
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.
#### Parameters
This function has no parameters.
`function` **`cb`**
</div>
<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`
or `load`, but is appropriated for the runner interface.
#### Parameters
This function has no parameters.
`string` **`cmd`**
</div>
<hr><div id='runner.sh'>
@ -62,6 +66,8 @@ hilbish.runner.sh(cmd)
Runs a command in Hilbish's shell script interpreter.
This is the equivalent of using `source`.
#### Parameters
This function has no parameters.
`string` **`cmd`**
</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.
These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc
accessible with `doc hilbish`). But if you want slightly more control over
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.
accessible with `doc hilbish`, or `Module hilbish` on the Website).
An example of usage:
```
```lua
local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function()
print 'hello!'
end)
@ -33,7 +29,7 @@ print(t.running) // true
## 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.|
## Static module fields
@ -50,10 +46,17 @@ hilbish.timers.create(type, time, callback) -> <a href="/Hilbish/docs/api/hilbis
</a>
</h4>
Creates a timer that runs based on the specified `time` in milliseconds.
The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
Creates a timer that runs based on the specified `time`.
#### 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>
<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.
#### Parameters
This function has no parameters.
`number` **`id`**
</div>
## 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="#saveState">saveState()</a>|Saves the current state of the terminal|
|<a href="#setRaw">setRaw()</a>|Puts the terminal in raw mode|
|<a href="#saveState">saveState()</a>|Saves the current state of the terminal.|
|<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`|
<hr><div id='restoreState'>
@ -39,7 +39,7 @@ terminal.saveState()
</a>
</h4>
Saves the current state of the terminal
Saves the current state of the terminal.
#### Parameters
This function has no parameters.
</div>
@ -52,7 +52,7 @@ terminal.setRaw()
</a>
</h4>
Puts the terminal in raw mode
Puts the terminal into raw mode.
#### Parameters
This function has no parameters.
</div>
@ -66,7 +66,7 @@ terminal.size()
</h4>
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
This function has no parameters.
</div>

51
docs/runner-mode.md
View File

@ -1,7 +1,15 @@
Hilbish is *unique,* when interactive it first attempts to run input as
Lua and then tries shell script. But if you're normal, you wouldn't
really be using Hilbish anyway but you'd also not want this
(or maybe want Lua only in some cases.)
Hilbish allows you to change how interactive text can be interpreted.
This is mainly due to the fact that the default method Hilbish uses
is that it runs Lua first and then falls back to shell script.
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`,
which determines how Hilbish will run user input. By default, this is
@ -27,12 +35,20 @@ hilbish.runnerMode(function(input)
end)
The `hilbish.runner` interface is an alternative to using `hilbish.runnerMode`
and also provides the sh 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.
If you don't, just return the input passed to the runner function.
The exit code has to be a number, it will be 0 otherwise and the error can be
`nil` to indicate no error.
and also provides the shell script and Lua runner functions that Hilbish itself uses.
A runner function is expected to return a table with the following values:
- `exitCode` (number): Exit code of the command
- `input` (string): The text input of the user. This is used by Hilbish to append extra input, in case
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
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
+ 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.
+ setCurrent(mode) > The same as `setMode`, but works with runners managed
via the functions below.

13
editor.go
View File

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

138
emmyLuaDocs/hilbish.lua
View File

@ -2,35 +2,30 @@
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 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.
--- 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.
--- @param cb function
function hilbish.runner.setMode(cb) end
--- Returns the current input line.
function hilbish.editor.getLine() end
--- Returns the text that is at the register.
--- @param register string
function hilbish.editor.getVimRegister(register) end
--- Inserts text into the line.
--- Inserts text into the Hilbish command line.
function hilbish.editor.insert(text) end
--- Reads a keystroke from the user. This is in a format
--- of something like Ctrl-L..
--- Reads a keystroke from the user. This is in a format of something like Ctrl-L.
function hilbish.editor.getChar() end
--- Sets the vim register at `register` to hold the passed text.
--- @param register string
--- @param text string
function hilbish.editor.setVimRegister(register, text) end
--- Return binaries/executables based on the provided parameters.
@ -65,40 +60,31 @@ function hilbish.alias(cmd, orig) 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>`,
--- replacing <cmd> with the name of the command (for example `command.git`).
--- `cb` must be a function that returns a table of "completion groups."
--- Check `doc completions` for more information.
--- @param scope string
--- @param cb function
--- The documentation for completions, under Features/Completions or `doc completions`
--- provides more details.
function hilbish.complete(scope, cb) end
--- Returns the current directory of the shell
--- @returns string
function hilbish.cwd() end
--- Replaces running hilbish with `cmd`
--- @param cmd string
--- Replaces the currently running Hilbish instance with the supplied command.
--- This can be used to do an in-place restart.
function hilbish.exec(cmd) end
--- Puts `fn` in a goroutine
--- @param fn function
--- 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.**
function hilbish.goro(fn) end
--- Line highlighter handler. This is mainly for syntax highlighting, but in
--- reality could set the input of the prompt to *display* anything. The
--- callback is passed the current line and is expected to return a line that
--- will be used as the input display.
--- Line highlighter handler.
--- This is mainly for syntax highlighting, but in reality could set the input
--- of the prompt to *display* anything. The callback is passed the current line
--- 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.
--- 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
--- 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
--- as the text for the hint. This is by default a shim. To set hints,
--- override this function with your custom handler.
--- @param line string
--- @param pos number
---
---
function hilbish.hinter(line, pos) end
--- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
--- @param mode string
--- 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.
function hilbish.inputMode(mode) end
--- Runs the `cb` function every `time` milliseconds.
--- This creates a timer that starts immediately.
--- @param cb function
--- @param time number
--- @return Timer
function hilbish.interval(cb, time) end
--- Changes the continued line prompt to `str`
--- @param str string
--- Changes the text prompt when Hilbish asks for more input.
--- This will show up when text is incomplete, like a missing quote
---
---
function hilbish.multiprompt(str) end
--- Prepends `dir` to $PATH
--- @param dir string
--- Prepends `dir` to $PATH.
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.
--- These will be formatted and replaced with the appropriate values.
--- `%d` - Current working directory
--- `%u` - Name of current user
--- `%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
--- Read input from the user, using Hilbish's line editor/input reader.
--- 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)
--- @param prompt? string
--- @returns string|nil
--- Returns `input`, will be nil if ctrl + d is pressed, or an error occurs (which shouldn't happen).
function hilbish.read(prompt) end
--- Runs `cmd` in Hilbish's sh 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
--- Runs `cmd` in Hilbish's shell script interpreter.
function hilbish.run(cmd, returnOut) end
--- 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),
--- sh, and lua. It also accepts a function, to which if it is passed one
--- will call it to execute user input instead.
--- @param mode string|function
function hilbish.runnerMode(mode) end
--- Runs the `cb` function after `time` in milliseconds.
--- This creates a timer that starts immediately.
--- @param cb function
--- @param time number
--- @returns Timer
--- This creates a Timer that starts immediately.
function hilbish.timeout(cb, time) end
--- Checks if `name` is a valid command.
--- 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
--- 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`
--- or `load`, but is appropriated for the runner interface.
--- @param cmd string
function hilbish.runner.lua(cmd) end
--- 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.
--- This is the equivalent of using `source`.
--- @param cmd string
function hilbish.runner.sh(cmd) end
--- Starts a timer.
@ -231,30 +200,26 @@ function hilbish.timers:start() end
function hilbish.timers:stop() end
--- Removes an alias.
--- @param name string
function hilbish.aliases.delete(name) end
--- 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
--- Tries to resolve an alias to its command.
--- @param alias string
--- @returns string
--- Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.
function hilbish.aliases.resolve(alias) end
--- Adds a new job to the job table. Note that this does not immediately run it.
--- @param cmdstr string
--- @param args table
--- @param execPath string
--- 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.
---
---
function hilbish.jobs.add(cmdstr, args, execPath) end
--- Returns a table of all job objects.
--- @returns table<Job>
function hilbish.jobs.all() end
--- Disowns a job. This deletes it from the job table.
--- @param id number
--- Disowns a job. This simply deletes it from the list of jobs without stopping it.
function hilbish.jobs.disown(id) end
--- Get a job object via its ID.
@ -262,39 +227,28 @@ function hilbish.jobs.disown(id) end
--- @returns Job
function hilbish.jobs.get(id) end
--- Returns the last added job from the table.
--- @returns Job
--- Returns the last added job to the table.
function hilbish.jobs.last() end
--- Adds a command to the history.
--- @param cmd string
function hilbish.history.add(cmd) end
--- Retrieves all history.
--- @returns table
--- Retrieves all history as a table.
function hilbish.history.all() end
--- Deletes all commands from the history.
function hilbish.history.clear() end
--- Retrieves a command from the history based on the `idx`.
--- @param idx number
function hilbish.history.get(idx) end
--- Retrieves a command from the history based on the `index`.
function hilbish.history.get(index) end
--- Returns the amount of commands in the history.
--- @returns number
function hilbish.history.size() end
--- Creates a timer that runs based on the specified `time` in milliseconds.
--- The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
--- @param type number
--- @param time number
--- @param callback function
--- Creates a timer that runs based on the specified `time`.
function hilbish.timers.create(type, time, callback) end
--- Retrieves a timer via its ID.
--- @param id number
--- @returns Timer
function hilbish.timers.get(id) end
return hilbish

6
emmyLuaDocs/terminal.lua
View File

@ -5,14 +5,14 @@ local terminal = {}
--- Restores the last saved state of the terminal
function terminal.restoreState() end
--- Saves the current state of the terminal
--- Saves the current state of the terminal.
function terminal.saveState() end
--- Puts the terminal in raw mode
--- Puts the terminal into raw mode.
function terminal.setRaw() end
--- 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
return terminal

6
golibs/terminal/terminal.go
View File

@ -34,7 +34,7 @@ func loaderFunc(rtm *rt.Runtime) (rt.Value, func()) {
// size()
// 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) {
w, h, err := term.GetSize(int(os.Stdin.Fd()))
if err != nil {
@ -49,7 +49,7 @@ func termsize(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// 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) {
state, err := term.GetState(int(os.Stdin.Fd()))
if err != nil {
@ -72,7 +72,7 @@ func termrestoreState(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// setRaw()
// Puts the terminal in raw mode
// Puts the terminal into raw mode.
func termsetRaw(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
_, err := term.MakeRaw(int(os.Stdin.Fd()))
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
// add(cmdstr, args, execPath)
// Adds a new job to the job table. Note that this does not immediately run it.
// --- @param cmdstr string
// --- @param args table
// --- @param execPath string
// 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.
// #param cmdstr string String that a user would write for the job
// #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) {
if err := c.CheckNArgs(3); err != nil {
return nil, err
@ -448,9 +454,9 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// #interface jobs
// all() -> table<@Job>
// all() -> table[@Job]
// 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) {
j.mu.RLock()
defer j.mu.RUnlock()
@ -465,8 +471,8 @@ func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface jobs
// disown(id)
// Disowns a job. This deletes it from the job table.
// --- @param id number
// Disowns a job. This simply deletes it from the list of jobs without stopping it.
// #param id number
func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -486,8 +492,8 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface jobs
// last() -> @Job
// Returns the last added job from the table.
// --- @returns Job
// Returns the last added job to the table.
// #returns Job
func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
j.mu.RLock()
defer j.mu.RUnlock()

1
module.go
View File

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

7
os.go
View File

@ -8,10 +8,9 @@ import (
)
// #interface os
// OS Info
// The `os` interface provides simple text information properties about
// the current OS on the systen. This mainly includes the name and
// version.
// operating system info
// Provides simple text information properties about the current operating system.
// This mainly includes the name and version.
// #field family Family name of the current OS
// #field name Pretty name 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
// add(cmd)
// 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) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -284,15 +284,15 @@ func (lr *lineReader) luaAddHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
// #interface history
// size() -> number
// 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) {
return c.PushingNext1(t.Runtime, rt.IntValue(int64(lr.fileHist.Len()))), nil
}
// #interface history
// get(idx)
// Retrieves a command from the history based on the `idx`.
// --- @param idx number
// get(index)
// Retrieves a command from the history based on the `index`.
// #param index number
func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -309,8 +309,8 @@ func (lr *lineReader) luaGetHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error)
// #interface history
// all() -> table
// Retrieves all history.
// --- @returns table
// Retrieves all history as a table.
// #returns table
func (lr *lineReader) luaAllHistory(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
tbl := rt.NewTable()
size := lr.fileHist.Len()

10
runnermode.go
View File

@ -28,18 +28,18 @@ func runnerModeLoader(rtm *rt.Runtime) *rt.Table {
// #interface runner
// setMode(cb)
// This is the same as the `hilbish.runnerMode` function. It takes a callback,
// which will be used to execute all interactive input.
// 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.
// --- @param cb function
// #param cb function
func _runnerMode() {}
// #interface runner
// sh(cmd)
// Runs a command in Hilbish's shell script interpreter.
// This is the equivalent of using `source`.
// --- @param cmd string
// #param cmd string
func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
return nil, err
@ -67,7 +67,7 @@ func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// lua(cmd)
// Evaluates `cmd` as Lua input. This is the same as using `dofile`
// 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) {
if err := c.Check1Arg(); err != nil {
return nil, err

22
timerhandler.go
View File

@ -63,11 +63,10 @@ func (th *timersModule) get(id int) *timer {
// #interface timers
// create(type, time, callback) -> @Timer
// Creates a timer that runs based on the specified `time` in milliseconds.
// The `type` can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
// --- @param type number
// --- @param time number
// --- @param callback function
// Creates a timer that runs based on the specified `time`.
// #param type number What kind of timer to create, can either be `hilbish.timers.INTERVAL` or `hilbish.timers.TIMEOUT`
// #param time number The amount of time the function should run in milliseconds.
// #param callback function The function to run for the timer.
func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.CheckNArgs(3); err != nil {
return nil, err
@ -93,8 +92,8 @@ func (th *timersModule) luaCreate(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
// #interface timers
// get(id) -> @Timer
// Retrieves a timer via its ID.
// --- @param id number
// --- @returns Timer
// #param id number
// #returns Timer
func (th *timersModule) luaGet(thr *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
if err := c.Check1Arg(); err != nil {
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.
These are the simple functions `hilbish.interval` and `hilbish.timeout` (doc
accessible with `doc hilbish`). But if you want slightly more control over
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.
accessible with `doc hilbish`, or `Module hilbish` on the Website).
An example of usage:
```
```lua
local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function()
print 'hello!'
end)

1
website/config.toml
View File

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