--- title: Module hilbish description: layout: doc menu: docs: parent: "API" --- ## Introduction ## Functions ``` =html
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 the specified scope.
cwd() -> string Returns the current directory of the shell.
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.
interval(cb, time) -> @Timer Runs the `cb` function every specified amount of `time`.
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.
timeout(cb, time) -> @Timer Executed the `cb` function after a period of `time`.
which(name) -> string Checks if `name` is a valid command.
``` ## Functions ``` =html

hilbish.alias(cmd, orig)

``` Sets an alias, with a name of `cmd` to another command. #### Parameters `string` `*cmd*` Name of the alias `string` `*orig*` Command that will be aliased #### Example ```lua -- With this, "ga file" will turn into "git add file" hilbish.alias('ga', 'git add') -- Numbered substitutions are supported here! hilbish.alias('dircount', 'ls %1 | wc -l') -- "dircount ~" would count how many files are in ~ (home directory). ``` ``` =html

hilbish.appendPath(dir)

``` Appends the provided dir to the command path (`$PATH`) #### Parameters `string|table` `*dir*` Directory (or directories) to append to path #### Example ```lua hilbish.appendPath '~/go/bin' -- Will add ~/go/bin to the command path. -- Or do multiple: hilbish.appendPath { '~/go/bin', '~/.local/bin' } ``` ``` =html

hilbish.complete(scope, cb)

``` Registers a completion handler for the specified scope. A `scope` is expected to be `command.`, replacing with the name of the command (for example `command.git`). The documentation for completions, under Features/Completions or `doc completions` provides more details. #### Parameters `string` `*scope*` `function` `*cb*` #### Example ```lua -- This is a very simple example. Read the full doc for completions for details. hilbish.complete('command.sudo', function(query, ctx, fields) if #fields == 0 then -- complete for commands local comps, pfx = hilbish.completion.bins(query, ctx, fields) local compGroup = { items = comps, -- our list of items to complete type = 'grid' -- what our completions will look like. } return {compGroup}, pfx end -- otherwise just be boring and return files local comps, pfx = hilbish.completion.files(query, ctx, fields) local compGroup = { items = comps, type = 'grid' } return {compGroup}, pfx end) ``` ``` =html

hilbish.cwd() -> string

``` Returns the current directory of the shell. #### Parameters This function has no parameters. ``` =html

hilbish.exec(cmd)

``` Replaces the currently running Hilbish instance with the supplied command. This can be used to do an in-place restart. #### Parameters `string` `*cmd*` ``` =html

hilbish.goro(fn)

``` Puts `fn` in a Goroutine. This can be used to run any function in another thread at the same time as other Lua code. **NOTE: THIS FUNCTION MAY CRASH HILBISH IF OUTSIDE VARIABLES ARE ACCESSED.** **This is a limitation of the Lua runtime.** #### Parameters `function` `*fn*` ``` =html

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. Note that to set a highlighter, one has to override this function. #### 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 ``` ``` =html

hilbish.hinter(line, pos)

``` The command line hint handler. It gets called on every key insert to 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 `string` `*line*` `number` `*pos*` Position of cursor in line. Usually equals string.len(line) #### Example ```lua -- this will display "hi" after the cursor in a dimmed color. function hilbish.hinter(line, pos) return 'hi' end ``` ``` =html

hilbish.inputMode(mode)

``` Sets the input mode for Hilbish's line reader. `emacs` is the default. Setting it to `vim` changes behavior of input to be Vim-like with modes and Vim keybinds. #### Parameters `string` `*mode*` Can be set to either `emacs` or `vim` ``` =html

hilbish.interval(cb, time) -> @Timer

``` Runs the `cb` function every specified amount of `time`. This creates a timer that ticking immediately. #### Parameters `function` `*cb*` `number` `*time*` Time in milliseconds. ``` =html

hilbish.multiprompt(str)

``` Changes the text prompt when Hilbish asks for more input. This will show up when text is incomplete, like a missing quote #### 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 '-->' ``` ``` =html

hilbish.prependPath(dir)

``` Prepends `dir` to $PATH. #### Parameters `string` `*dir*` ``` =html

hilbish.prompt(str, typ)

``` 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 `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 $ ``` ``` =html

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. #### Parameters `string` `*prompt?*` Text to print before input, can be empty. ``` =html

hilbish.timeout(cb, time) -> @Timer

``` Executed the `cb` function after a period of `time`. This creates a Timer that starts ticking immediately. #### Parameters `function` `*cb*` `number` `*time*` Time to run in milliseconds. ``` =html

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 `string` `*name*` ## Types ``` =html
``` ## Sink A sink is a structure that has input and/or output to/from a desination. ### Methods #### autoFlush(auto) Sets/toggles the option of automatically flushing output. A call with no argument will toggle the value. #### flush() Flush writes all buffered input to the sink. #### read() -> string Reads a liine of input from the sink. #### readAll() -> string Reads all input from the sink. #### write(str) Writes data to a sink. #### writeln(str) Writes data to a sink with a newline at the end.