the event emitter
the event emitter
Bait is the event emitter for Hilbish. Much like Node.js and
its events system, many actions in Hilbish emit events.
Unlike Node.js, Hilbish events are global. So make sure to
@@ -16,7 +16,7 @@ Consider this part of it:
<
5end)
What this does is, whenever the command.exit event is thrown,
this function will set the user prompt.
| catch(name, cb) | Catches an event. This function can be used to act on events. |
| catchOnce(name, cb) | Catches an event, but only once. This will remove the hook immediately after it runs for the first time. |
| hooks(name) -> table | Returns a list of callbacks that are hooked on an event with the corresponding name. |
| release(name, catcher) | Removes the catcher for the event with name. |
| throw(name, …args) | Throws a hook with name with the provided args. |
| catch(name, cb) | Catches an event. This function can be used to act on events. |
| catchOnce(name, cb) | Catches an event, but only once. This will remove the hook immediately after it runs for the first time. |
| hooks(name) -> table | Returns a table of functions that are hooked on an event with the corresponding name. |
| release(name, catcher) | Removes the catcher for the event with name. |
| throw(name, …args) | Throws a hook with name with the provided args. |
Catches an event. This function can be used to act on events.
string name
The name of the hook.
function cb
The function that will be called when the hook is thrown.
1bait.catch('hilbish.exit', function()
@@ -25,8 +25,8 @@ this function will set the user prompt.Functi
Catches an event, but only once. This will remove the hook immediately after it runs for the first time.
string name
The name of the event
function cb
The function that will be called when the event is thrown.
Returns a list of callbacks that are hooked on an event with the corresponding name.
string name
The name of the function
Returns a table of functions that are hooked on an event with the corresponding name.
string name
The name of the hook
Removes the catcher for the event with name.
For this to work, catcher has to be the same function used to catch
an event, like one saved to a variable.
string name
Name of the event the hook is on
function catcher
Hook function to remove
1local hookCallback = function() print 'hi' end
diff --git a/versions/doc-improvements/docs/api/commander/index.html b/versions/doc-improvements/docs/api/commander/index.html
index 865622c..45d9675 100644
--- a/versions/doc-improvements/docs/api/commander/index.html
+++ b/versions/doc-improvements/docs/api/commander/index.html
@@ -1,7 +1,7 @@
Module commander — Hilbish
Module commander
library for custom commands
Introduction
+
Module commander
library for custom commands
Introduction
Commander is the library which handles Hilbish commands. This makes
the user able to add Lua-written commands to their shell without making
a separate script in a bin folder. Instead, you may simply use the Commander
diff --git a/versions/doc-improvements/docs/api/fs/index.html b/versions/doc-improvements/docs/api/fs/index.html
index 5c7c521..a5f8004 100644
--- a/versions/doc-improvements/docs/api/fs/index.html
+++ b/versions/doc-improvements/docs/api/fs/index.html
@@ -1,7 +1,7 @@
Module fs — Hilbish
Module fs
filesystem interaction and functionality library
Introduction
+
Module fs
filesystem interaction and functionality library
Introduction
The fs module provides filesystem functions to Hilbish. While Lua’s standard
library has some I/O functions, they’re missing a lot of the basics. The fs
library offers more functions and will work on any operating system Hilbish does.
Functions
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.aliases/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.aliases/index.html
index b0b5848..4355d05 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.aliases/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.aliases/index.html
@@ -1,7 +1,7 @@
Module hilbish.aliases — Hilbish
Module hilbish.aliases
command aliasing
Introduction
+
Module hilbish.aliases
command aliasing
Introduction
The alias interface deals with all command aliases in Hilbish.
Functions
add(alias, cmd) This is an alias (ha) for the hilbish.alias
function. delete(name) Removes an alias. 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.
hilbish.aliases.add(alias, cmd)
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.completion/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.completion/index.html
index cce8bb1..c6d6743 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.completion/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.completion/index.html
@@ -1,7 +1,7 @@
Module hilbish.completion — Hilbish
Module hilbish.completion
tab completions
Introduction
+
Module hilbish.completion
tab completions
Introduction
The completions interface deals with tab completions.
Functions
bins(query, ctx, fields) -> entries (table), prefix (string) Return binaries/executables based on the provided parameters. call(name, query, ctx, fields) -> completionGroups (table), prefix (string) Calls a completer function. This is mainly used to call a command completer, which will have a name files(query, ctx, fields) -> entries (table), prefix (string) Returns file matches based on the provided parameters. handler(line, pos) This function contains the general completion handler for Hilbish. This function handles
hilbish.completion.bins(query, ctx, fields) -> entries (table), prefix (string)
Return binaries/executables based on the provided parameters.
This function is meant to be used as a helper in a command completion handler.
Parameters
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.editor/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.editor/index.html
index 509602b..99dc815 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.editor/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.editor/index.html
@@ -1,7 +1,7 @@
Module hilbish.editor — Hilbish
Module hilbish.editor
interactions for Hilbish's line reader
Introduction
+
Module hilbish.editor
interactions for Hilbish's line reader
Introduction
The hilbish.editor interface provides functions to
directly interact with the line editor in use.
Functions
getLine() -> string Returns the current input line. getVimRegister(register) -> string Returns the text that is at the register. 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.
hilbish.editor.getLine() -> string
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.history/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.history/index.html
index da37e2b..ad93530 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.history/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.history/index.html
@@ -1,7 +1,7 @@
Module hilbish.history — Hilbish
Module hilbish.history
command history
Introduction
+
Module hilbish.history
command history
Introduction
The history interface deals with command history.
This includes the ability to override functions to change the main
method of saving history.
Functions
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.jobs/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.jobs/index.html
index dc05061..9c84018 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.jobs/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.jobs/index.html
@@ -1,7 +1,7 @@
Module hilbish.jobs — Hilbish
Module hilbish.jobs
background job management
Introduction
+
Module hilbish.jobs
background job management
Introduction
Manage interactive jobs in Hilbish via Lua.
Jobs are the name of background tasks/commands. A job can be started via
interactive usage or with the functions defined below for use in external runners.
Functions
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 to the table.
hilbish.jobs.add(cmdstr, args, execPath)
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.module/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.module/index.html
index 3179ac9..7ea891c 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.module/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.module/index.html
@@ -1,7 +1,7 @@
Module hilbish.module — Hilbish
Module hilbish.module
native module loading
Introduction
+
Module hilbish.module
native module loading
Introduction
The hilbish.module interface provides a function to load
Hilbish plugins/modules. Hilbish modules are Go-written
plugins (see https://pkg.go.dev/plugin
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.os/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.os/index.html
index 9925186..f5da44c 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.os/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.os/index.html
@@ -1,7 +1,7 @@
Module hilbish.os — Hilbish
Module hilbish.os
operating system info
Introduction
+
Module hilbish.runner — Hilbish
Module hilbish.runner
interactive command runner customization
Introduction
+
Module hilbish.runner
interactive command runner customization
Introduction
The runner interface contains functions that allow the user to change
how Hilbish interprets interactive input.
Users can add and change the default runner for interactive input to any
language or script of their choosing. A good example is using it to
-write command in Fennel.
Functions
+write command in Fennel.
Runners are functions that evaluate user input. The default runners in
+Hilbish can run shell script and Lua code.
A runner is passed the input and has to return a table with these values.
+All are not required, only the useful ones the runner needs to return.
+(So if there isn’t an error, just omit err.)
exitCode (number): A numerical code to indicate the exit result.input (string): The user input. This will be used to add
+to the history.err (string): A string to indicate an interal error for the runner.
+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 to prompt the user for more input.
Here is a simple example of a fennel runner. It falls back to
+shell script if fennel eval has an error.
1local fennel = require 'fennel'
+ 2
+ 3hilbish.runnerMode(function(input)
+ 4 local ok = pcall(fennel.eval, input)
+ 5 if ok then
+ 6 return {
+ 7 input = input
+ 8 }
+ 9 end
+10
+11 return hilbish.runner.sh(input)
+12end)
+
Functions
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.
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.
In normal cases, neither callbacks should be overrided by the user,
as the higher level functions listed below this will handle it.
Parameters
function cb
hilbish.runner.lua(cmd)
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.timers/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.timers/index.html
index 406a672..b15bbd2 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.timers/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.timers/index.html
@@ -1,7 +1,7 @@
Module hilbish.timers — Hilbish
Module hilbish.timers
timeout and interval API
Introduction
+
Module hilbish.timers
timeout and interval API
Introduction
If you ever want to run a piece of code on a timed interval, or want to wait
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
diff --git a/versions/doc-improvements/docs/api/hilbish/hilbish.userdir/index.html b/versions/doc-improvements/docs/api/hilbish/hilbish.userdir/index.html
index 073541c..d4c2db0 100644
--- a/versions/doc-improvements/docs/api/hilbish/hilbish.userdir/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/hilbish.userdir/index.html
@@ -1,7 +1,7 @@
Module hilbish.userDir — Hilbish
Module hilbish.userDir
user-related directories
Introduction
+
Module hilbish.userDir
user-related directories
Introduction
This interface just contains properties to know about certain user directories.
It is equivalent to XDG on Linux and gets the user’s preferred directories
for configs and data.
Static module fields
diff --git a/versions/doc-improvements/docs/api/hilbish/index.html b/versions/doc-improvements/docs/api/hilbish/index.html
index ae074df..3b3dde9 100644
--- a/versions/doc-improvements/docs/api/hilbish/index.html
+++ b/versions/doc-improvements/docs/api/hilbish/index.html
@@ -1,7 +1,7 @@
Module hilbish — Hilbish
Module hilbish
the core Hilbish API
Introduction
+
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
@@ -26,8 +26,32 @@ interfaces and functions which directly relate to shell functionality.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
+
Registers a completion handler for the specified scope.
A scope is 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
Example
+
1-- This is a very simple example. Read the full doc for completions for details.
+ 2hilbish.complete('command.sudo', function(query, ctx, fields)
+ 3 if #fields == 0 then
+ 4 -- complete for commands
+ 5 local comps, pfx = hilbish.completion.bins(query, ctx, fields)
+ 6 local compGroup = {
+ 7 items = comps, -- our list of items to complete
+ 8 type = 'grid' -- what our completions will look like.
+ 9 }
+10
+11 return {compGroup}, pfx
+12 end
+13
+14 -- otherwise just be boring and return files
+15
+16 local comps, pfx = hilbish.completion.files(query, ctx, fields)
+17 local compGroup = {
+18 items = comps,
+19 type = 'grid'
+20 }
+21
+22 return {compGroup}, pfx
+23end)
+
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
@@ -35,15 +59,15 @@ interfaces and functions which directly relate to shell functionality.
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.
+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.
+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
@@ -53,8 +77,8 @@ interfaces and functions which directly relate to shell functionality.
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--[[
+string str
Example
+
1--[[
2imagine this is your text input:
3user ~ ∆ echo "hey
4
@@ -73,8 +97,8 @@ interfaces and functions which directly relate to shell functionality.
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
+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 $'
diff --git a/versions/doc-improvements/docs/api/hilbish/index.xml b/versions/doc-improvements/docs/api/hilbish/index.xml
index fc5a0aa..033ac36 100644
--- a/versions/doc-improvements/docs/api/hilbish/index.xml
+++ b/versions/doc-improvements/docs/api/hilbish/index.xml
@@ -7,7 +7,8 @@ Jobs are the name of background tasks/commands. A job can be started via interac
Functions 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.Module hilbish.module https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.module/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.module/ Introduction The hilbish.module interface provides a function to load Hilbish plugins/modules. Hilbish modules are Go-written plugins (see https://pkg.go.dev/plugin ) that are used to add functionality to Hilbish that cannot be written in Lua for any reason.
Note that you don’t ever need to use the load function that is here as modules can be loaded with a require call like Lua C modules, and the search paths can be changed with the paths property here. Module hilbish.os https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.os/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.os/ Introduction Provides simple text information properties about the current operating system. This mainly includes the name and version.
Static module fields family Family name of the current OS name Pretty name of the current OS version Version of the current OS Module hilbish.runner https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.runner/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.runner/ Introduction The runner interface contains functions that allow the user to change how Hilbish interprets interactive input. Users can add and change the default runner for interactive input to any language or script of their choosing. A good example is using it to write command in Fennel.
-Functions 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. Module hilbish.timers https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.timers/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.timers/ Introduction If you ever want to run a piece of code on a timed interval, or want to wait a few seconds, you don’t have to rely on timing tricks, as Hilbish has a timer API to set intervals and timeouts.
+Runners are functions that evaluate user input. The default runners in Hilbish can run shell script and Lua code.
+A runner is passed the input and has to return a table with these values. Module hilbish.timers https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.timers/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.timers/ Introduction If you ever want to run a piece of code on a timed interval, or want to wait 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, or Module hilbish on the Website).
An example of usage:
1local t = hilbish.timers.create(hilbish.timers.TIMEOUT, 5000, function() 2 print 'hello! Module hilbish.userDir https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.userdir/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/api/hilbish/hilbish.userdir/ Introduction This interface just contains properties to know about certain user directories. It is equivalent to XDG on Linux and gets the user’s preferred directories for configs and data.
diff --git a/versions/doc-improvements/docs/api/index.html b/versions/doc-improvements/docs/api/index.html
index e68167d..0b5a474 100644
--- a/versions/doc-improvements/docs/api/index.html
+++ b/versions/doc-improvements/docs/api/index.html
@@ -1,5 +1,5 @@
API — Hilbish
API
Welcome to the API documentation for Hilbish. This documents Lua functions
+
API
Welcome to the API documentation for Hilbish. This documents Lua functions
provided by Hilbish.
Module terminal — Hilbish
Module terminal
low level terminal library
Introduction
+
Module terminal
low level terminal library
Introduction
The terminal library is a simple and lower level library for certain terminal interactions.
Functions
restoreState() Restores the last saved state of the terminal 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
terminal.restoreState()
Restores the last saved state of the terminal
Parameters
diff --git a/versions/doc-improvements/docs/completions/index.html b/versions/doc-improvements/docs/completions/index.html
index 1e15d27..2c00af7 100644
--- a/versions/doc-improvements/docs/completions/index.html
+++ b/versions/doc-improvements/docs/completions/index.html
@@ -1,34 +1,44 @@
Completions — Hilbish
Completions
Tab completion for commands.
Hilbish has a pretty good completion system. It has a nice looking
-menu, with 2 types of menus: grid (like file completions) or
-list.
Like most parts of Hilbish, it’s made to be extensible and
+
Completions
Tab completion for commands.
Completions for commands can be created with the hilbish.complete
+function. See the link for how to use it.
To create completions for a command is simple.
+The callback will be passed 3 parameters:
query (string): The text that the user is currently trying to complete.
+This should be used to match entries.ctx (string): Contains the entire line. Use this if
+more text is needed to be parsed for context.fields (string): The ctx split up by spaces.
In most cases, the completer just uses fields to check the amount
+and query on what to match entries on.
In order to return your results, it has to go within a “completion group.”
+Then you return a table of completion groups and a prefix. The prefix will
+usually just be the query.
Hilbish allows one to mix completion menus of different types, so
+a grid menu and a list menu can be used and complete and display at the same time.
+A completion group is a table with these keys:
type (string): type of completion menu, either grid or list.items (table): a list of items.
The requirements of the items table is different based on the
+type. If it is a grid, it can simply be a table of strings.
Otherwise if it is a list then each entry can
+either be a string or a table.
+Example:
1local cg = {
+ 2 items = {
+ 3 'list item 1',
+ 4 ['--command-flag-here'] = {'this does a thing', '--the-flag-alias'}
+ 5 },
+ 6 type = 'list'
+ 7}
+ 8local cg2 = {
+ 9 items = {'just', 'a bunch', 'of items', 'here', 'hehe'},
+10 type = 'grid'
+11}
+12
+13return {cg, cg2}, prefix
+
Which looks like this:
Completion Handler
+
Like most parts of Hilbish, it’s made to be extensible and
customizable. The default handler for completions in general can
-be overwritten to provide more advanced completions if needed.
Completion Handler
-
By default, it provides 3 things: for the first argument,
+be overwritten to provide more advanced completions if needed.
+This usually doesn’t need to be done though, unless you know
+what you’re doing.
The default completion handler provides 3 things:
binaries (with a plain name requested to complete, those in
-$PATH), files, or command completions. With the default
-completion handler, it will try to run a handler for the
-command or fallback to file completions.
To overwrite it, just assign a function to
-hilbish.completion.handler like so:
-function hilbish.completion.handler(line, pos)
-– do things
-end
It is passed 2 arguments, the entire line, and the current
-cursor position. The functions in the completion interface
-take 3 arguments: query, ctx, and fields.
- The
query, which what the user is currently trying to complete ctx, being just the entire linefields being a table of arguments. It’s just ctx split up,
-delimited by spaces.
It’s expected to return 2 things: a table of completion groups, and
-a prefix. A completion group is defined as a table with 2 keys:
-items and type.
- The
items field is just a table of items to use for completions. - The
type is for the completion menu type, being either grid or
-list.
The prefix is what all the completions start with. It should be empty
-if the user doesn’t have a query. If the beginning of the completion
-item does not match the prefix, it will be replaced and fixed
-properly in the line. It is case sensitive.
If you want to overwrite the functionality of the general completion
-handler, or make your command completion have files as well
-(and filter them), then there is the files function, which is
-mentioned below.
Completion Interface
-
Functions
-
files(query, ctx, fields) -> table, prefix: get file completions,
-based on the user’s query.bins(query, ctx, fields) -> table, prefix: get binary/executable
-completions, based on user query.call(scope, query, ctx, fields) -> table, prefix: call a completion
-handler with scope, usually being in the form of command.<name>
To overwrite it, just assign a function to hilbish.completion.handler like so:
1-- line is the entire line as a string
+2-- pos is the position of the cursor.
+3function hilbish.completion.handler(line, pos)
+4 -- do things
+5end
+
\ No newline at end of file
diff --git a/versions/doc-improvements/docs/faq/index.html b/versions/doc-improvements/docs/faq/index.html
index 8bb0843..4953ce7 100644
--- a/versions/doc-improvements/docs/faq/index.html
+++ b/versions/doc-improvements/docs/faq/index.html
@@ -5,7 +5,7 @@ Why? Hilbish emerged from the desire of a Lua configured shell." property="og:de
Windows Support? It compiles for Windows (CI ensures it does), but otherwise it is not directly supported. If you’d like to improve this situation, checkout the discussion .
Why? Hilbish emerged from the desire of a Lua configured shell." name=description>Frequently Asked Questions
Last updated Nov 12, 2023
Is Hilbish POSIX compliant?
+
Frequently Asked Questions
Last updated Nov 12, 2023
Is Hilbish POSIX compliant?
No, it is not. POSIX compliance is a non-goal. Perhaps in the future,
someone would be able to write a native plugin to support shell scripting
(which would be against it’s main goal, but ….)
Windows Support?
diff --git a/versions/doc-improvements/docs/features/index.html b/versions/doc-improvements/docs/features/index.html
index b398aa0..b7b19d0 100644
--- a/versions/doc-improvements/docs/features/index.html
+++ b/versions/doc-improvements/docs/features/index.html
@@ -1,7 +1,7 @@
Features — Hilbish
Features
Last updated Nov 12, 2023
Hilbish has a wide range of features to enhance the user’s experience
+
Features
Last updated Nov 12, 2023
Hilbish has a wide range of features to enhance the user’s experience
new ones are always being added. If there is something missing here or
something you would like to see, please start a discussion
or comment on any existing ones which match your request.
Notification — Hilbish
Notification
Last updated Nov 12, 2023
Get notified of shell actions.
Hilbish features a simple notification system which can be
+
Notification
Last updated Nov 12, 2023
Get notified of shell actions.
Hilbish features a simple notification system which can be
used by other plugins and parts of the shell to notify the user
of various actions. This is used via the hilbish.message interface.
A message is defined as a table with the following properties:
icon: A unicode/emoji icon for the notification.title: The title of the messagetext: Message text/bodychannel: The source of the message. This should be a
unique and easily readable text identifier.summary: A short summary of the notification and message.
diff --git a/versions/doc-improvements/docs/features/opts/index.html b/versions/doc-improvements/docs/features/opts/index.html
index 34e751f..2b31e8b 100644
--- a/versions/doc-improvements/docs/features/opts/index.html
+++ b/versions/doc-improvements/docs/features/opts/index.html
@@ -1,7 +1,7 @@
Options — Hilbish
Options
Simple customizable options.
Opts are simple toggle or value options a user can set in Hilbish.
+
Options
Simple customizable options.
Opts are simple toggle or value options a user can set in Hilbish.
As toggles, there are things like autocd or history saving. As values,
there is the motd which the user can either change to a custom string or disable.
Opts are accessed from the hilbish.opts table. Here they can either
be read or modified
autocd
diff --git a/versions/doc-improvements/docs/features/runner-mode/index.html b/versions/doc-improvements/docs/features/runner-mode/index.html
index 9507b2a..ecbea0a 100644
--- a/versions/doc-improvements/docs/features/runner-mode/index.html
+++ b/versions/doc-improvements/docs/features/runner-mode/index.html
@@ -1,11 +1,29 @@
Runner Mode — Hilbish
Runner Mode
Last updated Nov 12, 2023
Customize the interactive script/command runner.
Hilbish allows you to change how interactive text can be interpreted.
+
Runner Mode
Last updated Nov 12, 2023
Customize the interactive script/command runner.
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
-handles links.
The “runner mode” of Hilbish is customizable via hilbish.runnerMode,
+which determines how Hilbish will run user input. By default, this is
+set to hybrid which is the previously mentioned behaviour of running Lua
+first then going to shell script. If you want the reverse order, you can
+set it to hybridRev and for isolated modes there is sh and lua
+respectively.
You can also set it to a function, which will be called everytime Hilbish
+needs to run interactive input. For more detail, see the API documentation
The hilbish.runner interface is an alternative to using hilbish.runnerMode
+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 commandinput (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.
- setMode(mode) > The same as
hilbish.runnerMode - sh(input) -> table > Runs
input in Hilbish’s sh interpreter - lua(input) -> table > Evals
input as Lua code
These functions should be preferred over the previous ones.
- setCurrent(mode) > The same as
setMode, but works with runners managed
+via the functions below. - add(name, runner) > Adds a runner to a table of available runners. The
runner
+argument is either a function or a table with a run callback. - set(name, runner) > The same as
add but requires passing a table and
+overwrites if the named runner already exists. - get(name) > runner > Gets a runner by name. It is a table with at least a
+run function, to run input.
- exec(cmd, runnerName) > Runs
cmd with a runner. If runnerName isn’t passed,
+the current runner mode is used.
\ No newline at end of file
diff --git a/versions/doc-improvements/docs/getting-started/index.html b/versions/doc-improvements/docs/getting-started/index.html
index e19d290..0f4b1cc 100644
--- a/versions/doc-improvements/docs/getting-started/index.html
+++ b/versions/doc-improvements/docs/getting-started/index.html
@@ -3,7 +3,7 @@
Setting as Default Login shell There are a few ways to make Hilbish your default shell. A simple way is to make it your user/login shell." property="og:description">Getting Started
Last updated Nov 12, 2023
To start Hilbish, open a terminal. If Hilbish has been installed and is not the
+
Getting Started
Last updated Nov 12, 2023
To start Hilbish, open a terminal. If Hilbish has been installed and is not the
default shell, you can simply run hilbish to start it. This will launch
a normal interactive session.
To exit, you can either run the exit command or hit Ctrl+D.
Setting as Default
diff --git a/versions/doc-improvements/docs/hooks/command/index.html b/versions/doc-improvements/docs/hooks/command/index.html
index debe600..6557524 100644
--- a/versions/doc-improvements/docs/hooks/command/index.html
+++ b/versions/doc-improvements/docs/hooks/command/index.html
@@ -19,7 +19,7 @@ The exit code of what was executed.
string cmdStr
The command or code that was executed" name=description>Command
command.preexec
+
Command
command.preexec
Thrown right before a command is executed.
Variables
string input
The raw string that the user typed. This will include the text
without changes applied to it (argument substitution, alias expansion,
diff --git a/versions/doc-improvements/docs/hooks/hilbish/index.html b/versions/doc-improvements/docs/hooks/hilbish/index.html
index 431444a..92e7a7c 100644
--- a/versions/doc-improvements/docs/hooks/hilbish/index.html
+++ b/versions/doc-improvements/docs/hooks/hilbish/index.html
@@ -11,7 +11,7 @@ Variables string modeName
The mode that has been set. Can be these values: insert, normal, delete or replace
hilbish.cancel Sent when the user cancels their command input with Ctrl-C" name=description>
Hilbish
hilbish.exit
+
Hilbish
hilbish.exit
Sent when Hilbish is going to exit.
Variables
This signal returns no variables.
hilbish.vimMode
Sent when the Vim mode of Hilbish is changed (like from insert to normal mode).
diff --git a/versions/doc-improvements/docs/hooks/index.html b/versions/doc-improvements/docs/hooks/index.html
index 4f555af..a7db815 100644
--- a/versions/doc-improvements/docs/hooks/index.html
+++ b/versions/doc-improvements/docs/hooks/index.html
@@ -1,6 +1,6 @@
Signals — Hilbish
Signals
Signals are global events emitted with the Bait
module.
For more detail on how to use these signals, you may check the Bait page.
Signal
signal.sigint
+
Signal
signal.sigint
Thrown when Hilbish receive the SIGINT signal,
aka when Ctrl-C is pressed.
Variables
This signal returns no variables.
signal.resize
diff --git a/versions/doc-improvements/docs/index.html b/versions/doc-improvements/docs/index.html
index dff0f30..7d57e31 100644
--- a/versions/doc-improvements/docs/index.html
+++ b/versions/doc-improvements/docs/index.html
@@ -3,7 +3,7 @@
Here documents some of the features of Hilbish and the Lua API." property="og:description">Introduction
Last updated Nov 12, 2023
Hilbish is a hyper-extensible shell mainly intended for interactive use.
+
Introduction
Last updated Nov 12, 2023
Hilbish is a hyper-extensible shell mainly intended for interactive use.
To enhance the interactive experience, Hilbish comes with a wide range
of features and sane defaults, including a nice looking prompt,
advanced completion menus and history search.
Here documents some of the features of Hilbish and the Lua API.
Frequently Asked Questions https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/faq/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/faq/ Is Hilbish POSIX compliant? No, it is not. POSIX compliance is a non-goal. Perhaps in the future, someone would be able to write a native plugin to support shell scripting (which would be against it’s main goal, but ….)
Windows Support? It compiles for Windows (CI ensures it does), but otherwise it is not directly supported. If you’d like to improve this situation, checkout the discussion .
Why? Hilbish emerged from the desire of a Lua configured shell. Getting Started https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/getting-started/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/getting-started/ To start Hilbish, open a terminal. If Hilbish has been installed and is not the default shell, you can simply run hilbish to start it. This will launch a normal interactive session. To exit, you can either run the exit command or hit Ctrl+D.
-Setting as Default Login shell There are a few ways to make Hilbish your default shell. A simple way is to make it your user/login shell. Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/runner-mode/ 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. Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/timers/ This has been moved to the hilbish.timers API doc (accessible by doc api hilbish.timers) Completions https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/completions/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/completions/ Hilbish has a pretty good completion system. It has a nice looking menu, with 2 types of menus: grid (like file completions) or list.
-Like most parts of Hilbish, it’s made to be extensible and customizable. The default handler for completions in general can be overwritten to provide more advanced completions if needed.
-Completion Handler By default, it provides 3 things: for the first argument, binaries (with a plain name requested to complete, those in $PATH), files, or command completions. Jobs https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/jobs/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/jobs/ Hilbish has pretty standard job control. It’s missing one or two things, but works well. One thing which is different from other shells (besides Hilbish) itself is the API for jobs, and of course it’s in Lua. You can add jobs, stop and delete (disown) them and even get output.
+Setting as Default Login shell There are a few ways to make Hilbish your default shell. A simple way is to make it your user/login shell. Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/jobs/ (This has mainly been replaced by hilbish.jobs ).
+Hilbish has pretty standard job control. It’s missing one or two things, but works well. One thing which is different from other shells (besides Hilbish) itself is the API for jobs, and of course it’s in Lua. You can add jobs, stop and delete (disown) them and even get output.
Job Interface The job interface refers to hilbish.jobs.
-Functions (Note that in the list here, they’re called from hilbish.jobs, so a listing of foo would mean hilbish. Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/timers/ This has been moved to the hilbish.timers API doc (accessible by doc api hilbish.timers) Completions https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/completions/Mon, 01 Jan 0001 00:00:00 +0000 https://rosettea.github.io/Hilbish/versions/doc-improvements/docs/completions/ Completions for commands can be created with the hilbish.complete function. See the link for how to use it.
+To create completions for a command is simple. The callback will be passed 3 parameters:
+query (string): The text that the user is currently trying to complete. This should be used to match entries. ctx (string): Contains the entire line. Use this if more text is needed to be parsed for context. fields (string): The ctx split up by spaces. Jobs — Hilbish
-