From 90ef8f7a9c87c9710c54e0c82fe425c6fcb8db2e Mon Sep 17 00:00:00 2001 From: sammyette Date: Sun, 3 Dec 2023 20:54:00 -0400 Subject: [PATCH] refactor: update documentation for everything --- aliases.go | 24 ++-- api.go | 135 ++++++++++++-------- docs/api/hilbish/_index.md | 189 ++++++++++++++++++++-------- docs/api/hilbish/hilbish.aliases.md | 31 +++-- docs/api/hilbish/hilbish.editor.md | 21 ++-- docs/api/hilbish/hilbish.history.md | 18 +-- docs/api/hilbish/hilbish.jobs.md | 37 ++++-- docs/api/hilbish/hilbish.module.md | 4 +- docs/api/hilbish/hilbish.os.md | 7 +- docs/api/hilbish/hilbish.runner.md | 18 ++- docs/api/hilbish/hilbish.timers.md | 27 ++-- docs/api/terminal.md | 10 +- docs/runner-mode.md | 51 ++++---- editor.go | 13 +- emmyLuaDocs/hilbish.lua | 138 +++++++------------- emmyLuaDocs/terminal.lua | 6 +- golibs/terminal/terminal.go | 6 +- job.go | 26 ++-- module.go | 1 + os.go | 7 +- rl.go | 14 +-- runnermode.go | 10 +- timerhandler.go | 22 ++-- website/config.toml | 1 + 24 files changed, 480 insertions(+), 336 deletions(-) diff --git a/aliases.go b/aliases.go index 8b815b3..8c90fe5 100644 --- a/aliases.go +++ b/aliases.go @@ -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 +// list() -> table[string, string] // Get a table of all aliases, with string keys as the alias and the value as the command. -// --- @returns table +// #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 diff --git a/api.go b/api.go index 71a4b7b..b4c4496 100644 --- a/api.go +++ b/api.go @@ -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.`, // replacing 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 } diff --git a/docs/api/hilbish/_index.md b/docs/api/hilbish/_index.md index 8eded6b..aba1c6f 100644 --- a/docs/api/hilbish/_index.md +++ b/docs/api/hilbish/_index.md @@ -16,19 +16,19 @@ interfaces and functions which directly relate to shell functionality. |----|----| |alias(cmd, orig)|Sets an alias, with a name of `cmd` to another command.| |appendPath(dir)|Appends the provided dir to the command path (`$PATH`)| -|complete(scope, cb)|Registers a completion handler for `scope`.| +|complete(scope, cb)|Registers a completion handler for the specified scope.| |cwd() -> string|Returns the current directory of the shell| -|exec(cmd)|Replaces running hilbish with `cmd`| -|goro(fn)|Puts `fn` in a goroutine| -|highlighter(line)|Line highlighter handler. This is mainly for syntax highlighting, but in| +|exec(cmd)|Replaces the currently running Hilbish instance with the supplied command.| +|goro(fn)|Puts `fn` in a Goroutine.| +|highlighter(line)|Line highlighter handler.| |hinter(line, pos)|The command line hint handler. It gets called on every key insert to| -|inputMode(mode)|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim| +|inputMode(mode)|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.| |interval(cb, time) -> @Timer|Runs the `cb` function every `time` milliseconds.| -|multiprompt(str)|Changes the continued line prompt to `str`| -|prependPath(dir)|Prepends `dir` to $PATH| -|prompt(str, typ)|Changes the shell prompt to `str`| +|multiprompt(str)|Changes the text prompt when Hilbish asks for more input.| +|prependPath(dir)|Prepends `dir` to $PATH.| +|prompt(str, typ)|Changes the shell prompt to the provided string.| |read(prompt) -> input (string)|Read input from the user, using Hilbish's line editor/input reader.| -|run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)|Runs `cmd` in Hilbish's sh interpreter.| +|run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)|Runs `cmd` in Hilbish's shell script interpreter.| |runnerMode(mode)|Sets the execution/runner mode for interactive Hilbish. This determines whether| |timeout(cb, time) -> @Timer|Runs the `cb` function after `time` in milliseconds.| |which(name) -> string|Checks if `name` is a valid command.| @@ -111,13 +111,18 @@ hilbish.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.`, replacing 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`** + +
@@ -141,9 +146,12 @@ hilbish.exec(cmd) -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`** + +
@@ -154,9 +162,13 @@ hilbish.goro(fn) -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`** + +
@@ -167,20 +179,23 @@ hilbish.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: -``` -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. +`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 +````
@@ -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 +````
@@ -208,9 +237,13 @@ hilbish.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. +`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`** + +
@@ -248,9 +309,11 @@ hilbish.prependPath(dir) -Prepends `dir` to $PATH +Prepends `dir` to $PATH. #### Parameters -This function has no parameters. +`string` **`dir`** + +
@@ -261,14 +324,28 @@ hilbish.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 + #### 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 $ +````
@@ -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?`** + +
@@ -294,11 +373,14 @@ hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (strin -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. +
@@ -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`** + +
@@ -327,9 +411,14 @@ hilbish.timeout(cb, time) -> add(alias, cmd)|This is an alias (ha) for the `hilbish.alias` function.| +|add(alias, cmd)|This is an alias (ha) for the [hilbish.alias](../#alias) function.| |delete(name)|Removes an alias.| -|list() -> table|Get a table of all aliases, with string keys as the alias and the value as the command.| -|resolve(alias) -> command (string)|Tries to resolve an alias to its command.| +|list() -> table[string, string]|Get a table of all aliases, with string keys as the alias and the value as the command.| +|resolve(alias) -> string?|Resolves an alias to its original command. Will thrown an error if the alias doesn't exist.|

@@ -26,7 +26,7 @@ hilbish.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. #### Parameters This function has no parameters.
@@ -41,32 +41,45 @@ hilbish.aliases.delete(name) Removes an alias. #### Parameters -This function has no parameters. +`string` **`name`** + +

-hilbish.aliases.list() -> table\ +hilbish.aliases.list() -> table[string, string]

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'} +````

-hilbish.aliases.resolve(alias) -> command (string) +hilbish.aliases.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. #### Parameters -This function has no parameters. +`string` **`alias`** + +
diff --git a/docs/api/hilbish/hilbish.editor.md b/docs/api/hilbish/hilbish.editor.md index 52e6dfc..040ca85 100644 --- a/docs/api/hilbish/hilbish.editor.md +++ b/docs/api/hilbish/hilbish.editor.md @@ -16,8 +16,8 @@ directly interact with the line editor in use. |----|----| |getLine() -> string|Returns the current input line.| |getVimRegister(register) -> string|Returns the text that is at the register.| -|insert(text)|Inserts text into the line.| -|getChar() -> string|Reads a keystroke from the user. This is in a format| +|insert(text)|Inserts text into the Hilbish command line.| +|getChar() -> string|Reads a keystroke from the user. This is in a format of something like Ctrl-L.| |setVimRegister(register, text)|Sets the vim register at `register` to hold the passed text.|
@@ -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`** + +
@@ -54,9 +56,11 @@ hilbish.editor.insert(text) -Inserts text into the line. +Inserts text into the Hilbish command line. #### Parameters -This function has no parameters. +`string` **`text`** + +
@@ -67,8 +71,7 @@ hilbish.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. #### Parameters This function has no parameters.
@@ -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`** + + diff --git a/docs/api/hilbish/hilbish.history.md b/docs/api/hilbish/hilbish.history.md index 802ea42..bc1efb0 100644 --- a/docs/api/hilbish/hilbish.history.md +++ b/docs/api/hilbish/hilbish.history.md @@ -16,9 +16,9 @@ method of saving history. ||| |----|----| |add(cmd)|Adds a command to the history.| -|all() -> table|Retrieves all history.| +|all() -> table|Retrieves all history as a table.| |clear()|Deletes all commands from the history.| -|get(idx)|Retrieves a command from the history based on the `idx`.| +|get(index)|Retrieves a command from the history based on the `index`.| |size() -> number|Returns the amount of commands in the history.|
@@ -31,7 +31,9 @@ hilbish.history.add(cmd) Adds a command to the history. #### Parameters -This function has no parameters. +`string` **`cmd`** + +
@@ -42,7 +44,7 @@ hilbish.history.all() -> table -Retrieves all history. +Retrieves all history as a table. #### Parameters This function has no parameters.
@@ -62,15 +64,17 @@ This function has no parameters.

-hilbish.history.get(idx) +hilbish.history.get(index)

-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`** + +
diff --git a/docs/api/hilbish/hilbish.jobs.md b/docs/api/hilbish/hilbish.jobs.md index a640726..6a3423f 100644 --- a/docs/api/hilbish/hilbish.jobs.md +++ b/docs/api/hilbish/hilbish.jobs.md @@ -17,11 +17,11 @@ interactive usage or with the functions defined below for use in external runner ## Functions ||| |----|----| -|add(cmdstr, args, execPath)|Adds a new job to the job table. Note that this does not immediately run it.| -|all() -> table<@Job>|Returns a table of all job objects.| -|disown(id)|Disowns a job. This deletes it from the job table.| +|add(cmdstr, args, execPath)|Creates a new job. This function does not run the job. This function is intended to be| +|all() -> table[@Job]|Returns a table of all job objects.| +|disown(id)|Disowns a job. This simply deletes it from the list of jobs without stopping it.| |get(id) -> @Job|Get a job object via its ID.| -|last() -> @Job|Returns the last added job from the table.| +|last() -> @Job|Returns the last added job to the table.|

@@ -31,14 +31,29 @@ hilbish.jobs.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 +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') +````

-hilbish.jobs.all() -> table\<Job> +hilbish.jobs.all() -> table[Job] @@ -57,9 +72,11 @@ hilbish.jobs.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. #### Parameters -This function has no parameters. +`number` **`id`** + +
diff --git a/docs/api/hilbish/hilbish.module.md b/docs/api/hilbish/hilbish.module.md index 7a000c1..3363ca7 100644 --- a/docs/api/hilbish/hilbish.module.md +++ b/docs/api/hilbish/hilbish.module.md @@ -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`** + +
diff --git a/docs/api/hilbish/hilbish.os.md b/docs/api/hilbish/hilbish.os.md index 7749e3d..13b56b0 100644 --- a/docs/api/hilbish/hilbish.os.md +++ b/docs/api/hilbish/hilbish.os.md @@ -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 ||| diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index c3e2c19..c3134ae 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -17,7 +17,7 @@ write command in Fennel. ## Functions ||| |----|----| -|setMode(cb)|This is the same as the `hilbish.runnerMode` function. It takes a callback,| +|setMode(cb)|This is the same as the `hilbish.runnerMode` function.| |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| @@ -29,12 +29,14 @@ hilbish.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. #### Parameters -This function has no parameters. +`function` **`cb`** + +
@@ -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`** + +
@@ -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`** + +
diff --git a/docs/api/hilbish/hilbish.timers.md b/docs/api/hilbish/hilbish.timers.md index 3c0fadb..310c4dd 100644 --- a/docs/api/hilbish/hilbish.timers.md +++ b/docs/api/hilbish/hilbish.timers.md @@ -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 ||| |----|----| -|create(type, time, callback) -> @Timer|Creates a timer that runs based on the specified `time` in milliseconds.| +|create(type, time, callback) -> @Timer|Creates a timer that runs based on the specified `time`.| |get(id) -> @Timer|Retrieves a timer via its ID.| ## Static module fields @@ -50,10 +46,17 @@ hilbish.timers.create(type, time, callback) -> ## Types diff --git a/docs/api/terminal.md b/docs/api/terminal.md index 6e72d84..19eb0eb 100644 --- a/docs/api/terminal.md +++ b/docs/api/terminal.md @@ -14,8 +14,8 @@ The terminal library is a simple and lower level library for certain terminal in ||| |----|----| |restoreState()|Restores the last saved state of the terminal| -|saveState()|Saves the current state of the terminal| -|setRaw()|Puts the terminal in raw mode| +|saveState()|Saves the current state of the terminal.| +|setRaw()|Puts the terminal into raw mode.| |size()|Gets the dimensions of the terminal. Returns a table with `width` and `height`|
@@ -39,7 +39,7 @@ terminal.saveState() -Saves the current state of the terminal +Saves the current state of the terminal. #### Parameters This function has no parameters.
@@ -52,7 +52,7 @@ terminal.setRaw() -Puts the terminal in raw mode +Puts the terminal into raw mode. #### Parameters This function has no parameters. @@ -66,7 +66,7 @@ terminal.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. #### Parameters This function has no parameters. diff --git a/docs/runner-mode.md b/docs/runner-mode.md index 0b5ce24..4844c27 100644 --- a/docs/runner-mode.md +++ b/docs/runner-mode.md @@ -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. + - `: not-found` will throw a `command.not-found` hook + based on what `` is. + - `: 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. - -+ `: not-found` will throw a `command.not-found` hook -based on what `` is. -+ `: 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. diff --git a/editor.go b/editor.go index d720a41..9c49440 100644 --- a/editor.go +++ b/editor.go @@ -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() diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua index f6d58a4..8521065 100644 --- a/emmyLuaDocs/hilbish.lua +++ b/emmyLuaDocs/hilbish.lua @@ -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.`, --- replacing 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 +--- +--- 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 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 diff --git a/emmyLuaDocs/terminal.lua b/emmyLuaDocs/terminal.lua index 2266ac6..ed0b9ef 100644 --- a/emmyLuaDocs/terminal.lua +++ b/emmyLuaDocs/terminal.lua @@ -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 diff --git a/golibs/terminal/terminal.go b/golibs/terminal/terminal.go index 2040fac..954a4dd 100644 --- a/golibs/terminal/terminal.go +++ b/golibs/terminal/terminal.go @@ -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 { diff --git a/job.go b/job.go index 1beba9c..185ec91 100644 --- a/job.go +++ b/job.go @@ -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 +// #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() diff --git a/module.go b/module.go index 2ab55e8..bf4e32a 100644 --- a/module.go +++ b/module.go @@ -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 diff --git a/os.go b/os.go index da9eadd..46e3d3c 100644 --- a/os.go +++ b/os.go @@ -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 diff --git a/rl.go b/rl.go index 17ea4df..7d5ed89 100644 --- a/rl.go +++ b/rl.go @@ -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() diff --git a/runnermode.go b/runnermode.go index 8e9e7b9..56a0178 100644 --- a/runnermode.go +++ b/runnermode.go @@ -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 diff --git a/timerhandler.go b/timerhandler.go index 0cb4197..0a8e34f 100644 --- a/timerhandler.go +++ b/timerhandler.go @@ -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) diff --git a/website/config.toml b/website/config.toml index 174c434..42f3d30 100644 --- a/website/config.toml +++ b/website/config.toml @@ -35,6 +35,7 @@ lineNumbersInTable = false noClasses = false codeFences = true guessSyntax = true +tabWidth = 4 [author] [author.sammyette]