# Module hilbish

the core Hilbish API

### Introduction

The Hilbish module includes the core API, containing interfaces and functions which directly relate to shell functionality.

### Functions

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. Accepts either emacs or vim.
interval(cb, time) -> @Timer | Runs the `cb` function every `time` milliseconds.
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 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.

### Static module fields

ver | The version of Hilbish
goVersion | The version of Go that Hilbish was compiled with
user | Username of the user
host | Hostname of the machine
dataDir | Directory for Hilbish data files, including the docs and default modules
interactive | Is Hilbish in an interactive shell?
login | Is Hilbish the login shell?
vimMode | Current Vim input mode of Hilbish (will be nil if not in Vim input mode)
exitCode | Exit code of the last executed command

#### 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

    1-- With this, "ga file" will turn into "git add file"
    2hilbish.alias('ga', 'git add')
    3
    4-- Numbered substitutions are supported here!
    5hilbish.alias('dircount', 'ls %1 | wc -l')
    6-- "dircount ~" would count how many files are in ~ (home directory).

#### hilbish.appendPath(dir)

Appends the provided dir to the command path (`$PATH`)

##### Parameters

`string|table` `dir`
Directory (or directories) to append to path

##### Example

    1hilbish.appendPath '~/go/bin'
    2-- Will add ~/go/bin to the command path.
    3
    4-- Or do multiple:
    5hilbish.appendPath {
    6	'~/go/bin',
    7	'~/.local/bin'
    8}

#### hilbish.complete(scope, cb)

Registers a completion handler for the specified scope.
A `scope` is currently only expected to be `command.<cmd>`,
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`

#### hilbish.cwd() -> string

Returns the current directory of the shell

##### Parameters

This function has no parameters.

#### 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`

#### hilbish.goro(fn)

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

`function` `fn`

#### 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

    1--This code will highlight all double quoted strings in green.
    2function hilbish.highlighter(line)
    3   return line:gsub('"%w+"', function(c) return lunacolors.green(c) end)
    4end

#### 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`

##### Example

    1-- this will display "hi" after the cursor in a dimmed color.
    2function hilbish.hinter(line, pos)
    3	return 'hi'
    4end

#### hilbish.inputMode(mode)

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

`string` `mode`

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

Runs the `cb` function every `time` milliseconds.
This creates a timer that starts immediately.

##### Parameters

`function` `cb`

`number` `time`

#### 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

     1--[[
     2imagine this is your text input:
     3user ~ ∆ echo "hey
     4
     5but there's a missing quote! hilbish will now prompt you so the terminal
     6will look like:
     7user ~ ∆ echo "hey
     8--> ...!"
     9
    10so then you get
    11user ~ ∆ echo "hey
    12--> ...!"
    13hey ...!
    14]]--
    15hilbish.multiprompt '-->'

#### hilbish.prependPath(dir)

Prepends `dir` to $PATH.

##### Parameters

`string` `dir`

#### 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

    1-- the default hilbish prompt without color
    2hilbish.prompt '%u %d ∆'
    3-- or something of old:
    4hilbish.prompt '%u@%h :%d $'
    5-- prompt: user@hostname: ~/directory $

#### 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).

##### Parameters

`string` `prompt?`

#### hilbish.run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)

Runs `cmd` in Hilbish’s shell script interpreter.

##### 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.

#### hilbish.runnerMode(mode)

Sets the execution/runner mode for interactive Hilbish. This determines whether
Hilbish wll try to run input as Lua and/or sh or only do one of either.
Accepted values for mode are hybrid (the default), hybridRev (sh first then Lua),
sh, and lua. It also accepts a function, to which if it is passed one
will call it to execute user input instead.

##### Parameters

`string|function` `mode`

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

Runs the `cb` function after `time` in milliseconds.
This creates a Timer that starts immediately.

##### Parameters

`function` `cb`

`number` `time`

#### 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

### 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.