diff --git a/docs/completions.md b/docs/completions.md
index 75a9a346..f7f41ea9 100644
--- a/docs/completions.md
+++ b/docs/completions.md
@@ -12,31 +12,35 @@ 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.
+
+- `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.
-
+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`.
-
+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.
-
+`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.
+either be a string or a table.\
+ \
Example:
+
```lua
local cg = {
items = {
@@ -57,11 +61,14 @@ Which looks like this:
{{< video src="https://safe.saya.moe/t4CiLK6dgPbD.mp4" >}}
# Completion Group Types
-### grid
-Grid is the simplest completion group type. All items are strings and when
-completion is done is displayed in a grid based on size.
+### grid
+
+Grid is the simplest completion group type. All items are strings and when
+completion is done is displayed in a grid based on size.\
+ \
Example:
+
```lua
{
items = {'just', 'a bunch', 'of items', 'here', 'hehe'},
@@ -70,17 +77,16 @@ Example:
```
### list
-The list completion group type displays in a list. A list item can either be a string, or a table for additional display options.
+
+The list completion group type displays in a list. A list item can either be a string, or a table for additional display options.\
A completion alias can be specified either as the `2nd` entry in the options table
-or te `alias` key.
-
+or te `alias` key.\
A description can optionally be displayed for a list item, which is either the `1st`
-entry or the `description` key.
-
-Lastly, list entries can be styled. This is done with the `display` key. If this is present, this
-overrides what the completion item *looks* like.
-
+entry or the `description` key.\
+Lastly, list entries can be styled. This is done with the `display` key. If this is present, this overrides what the completion item _looks_ like.\
+ \
Example:
+
```lua
{
items = {
@@ -101,18 +107,22 @@ Example:
```
# 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.
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. It will try to run a handler
-for the command or fallback to file completions.
-
+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.\
+ \
+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:
+
```lua
-- line is the entire line as a string
-- pos is the position of the cursor.
diff --git a/docs/faq.md b/docs/faq.md
index f89f2696..c368cfdb 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -6,21 +6,25 @@ menu: docs
---
# 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](https://github.com/Rosettea/Hilbish/discussions/165).
# Why?
+
Hilbish emerged from the desire of a Lua configured shell.
It was the initial reason that it was created, but now it's more:
to be hyper extensible, simpler and more user friendly.
# Does it have "autocompletion" or "tab completion"
+
Of course! This is a modern shell. Hilbish provides a way for users
to write tab completion for any command and/or the whole shell.
Inline hinting and syntax highlighting are also available.
diff --git a/docs/features/notifications.md b/docs/features/notifications.md
index c3a9b53f..e40532ed 100644
--- a/docs/features/notifications.md
+++ b/docs/features/notifications.md
@@ -9,31 +9,30 @@ menu:
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.
-
+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 message
- `text`: Message text/body
-- `channel`: The source of the message. This should be a
-unique and easily readable text identifier.
-- `summary`: A short summary of the notification and message.
-If this is not present and you are using this to display messages,
-you should take part of the `text` instead.
+- `channel`: The source of the message. This should be a unique and easily readable text identifier.
+- `summary`: A short summary of the notification and message. If this is not present and you are using this to display messages, you should take part of the `text` instead.
+ \
The `hilbish.message` interface provides the following functions:
-- `send(message)`: Sends a message and emits the `hilbish.notification`
-signal. DO NOT emit the `hilbish.notification` signal directly, or
-the message will not be stored by the message handler.
+
+- `send(message)`: Sends a message and emits the `hilbish.notification` signal. DO NOT emit the `hilbish.notification` signal directly, or the message will not be stored by the message handler.
- `read(idx)`: Marks message at `idx` as read.
- `delete(idx)`: Removes message at `idx`.
- `readAll()`: Marks all messages as read.
- `clear()`: Deletes all messages.
+ \
There are a few simple use cases of this notification/messaging system.
It could also be used as some "inter-shell" messaging system (???) but
-is intended to display to users.
-
+is intended to display to users.\
+ \
An example is notifying users of completed jobs/commands ran in the background.
Any Hilbish-native command (think the upcoming Greenhouse pager) can display
it.
diff --git a/docs/features/opts.md b/docs/features/opts.md
index f975c79e..324b65b7 100644
--- a/docs/features/opts.md
+++ b/docs/features/opts.md
@@ -9,19 +9,22 @@ menu:
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.
-
+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
+be read or modified.
### `autocd`
+
#### Value: `boolean`
+
#### Default: `false`
The autocd opt makes it so that lone directories attempted to be executed are
instead set as the shell's directory.
Example:
+
```
~/Directory
∆ ~
@@ -33,51 +36,81 @@ Example:
∆
```
-
+``` =html
+
+```
### `history`
+
#### Value: `boolean`
+
#### Default: `true`
+
Sets whether command history will be saved or not.
-
-
-### `greeting`
-#### Value: `boolean` or `string`
-The greeting is the message that Hilbish shows on startup
-(the one which says Welcome to Hilbish).
+``` =html
+
+```
+### `greeting`
+
+#### Value: `boolean` or `string`
+
+The greeting is the message that Hilbish shows on startup
+(the one which says Welcome to Hilbish).\
This can be set to either true/false to enable/disable or a custom greeting string.
-
+``` =html
+
+```
### `motd`
-#### Value: `boolean`
-#### Default: `true`
-The message of the day shows the current major.minor version and
-includes a small range of things added in the current release.
+#### Value: `boolean`
+
+#### Default: `true`
+
+The message of the day shows the current major.minor version and
+includes a small range of things added in the current release.\
+ \
This can be set to `false` to disable the message.
-
+``` =html
+
+```
### `fuzzy`
+
#### Value: `boolean`
+
#### Default: `false`
+
Toggles the functionality of fuzzy history searching, usable
via the menu in Ctrl-R. Fuzzy searching is an approximate searching
method, which means results that match *closest* will be shown instead
of an exact match.
-
+``` =html
+
+```
### `notifyJobFinish`
+
#### Value: `boolean`
+
#### Default: `true`
+
If this is enabled, when a background job is finished,
a [notification](../notifications) will be sent.
+``` =html
+
+```
+
### `processorSkipList`
+
#### Value: `table`
+
#### Default: `{}`
+
A table listing the names of command processors to skip.
diff --git a/docs/features/runner-mode.md b/docs/features/runner-mode.md
index ec804c1b..3c5a19b3 100644
--- a/docs/features/runner-mode.md
+++ b/docs/features/runner-mode.md
@@ -9,45 +9,42 @@ menu:
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.
-
+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.
-
+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.
-
+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.
-
+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](../../api/hilbish/hilbish.runner)
-
+needs to run interactive input. For more detail, see the [API documentation](../../api/hilbish/hilbish.runner)\
+ \
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.
## 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
+- 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 `name`d 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.
+
+- 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 `name`d 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.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index b5c31484..745c3161 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -11,7 +11,9 @@ 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.
@@ -21,41 +23,40 @@ you still decide to do it, there will just be a few variables missing in
your environment` >}}
To do that, simply run `chsh -s /usr/bin/hilbish`.
+
Some distros (namely Fedora) might have `lchsh` instead, which is used like `lchsh `.
When prompted, you can put the path for Hilbish.
## Default with terminal
+
The simpler way is to set the default shell for your terminal. The way of
doing this depends on how your terminal settings are configured.
## Run after login shell
-Some shells (like zsh) have an rc file, like `.zlogin`, which is ran when the shell session
-is a login shell. In that file, you can run Hilbish. Example:
-```
-exec hilbish -S -l
-```
+Some shells (like zsh) have an rc file, like `.zlogin`, which is ran when the shell session
+is a login shell. In that file, you can run Hilbish with this command: `exec hilbish -S -l`
This will replace the shell with Hilbish, set $SHELL to Hilbish and launch it as a login shell.
# Configuration
+
Once installation and setup has been done, you can then configure Hilbish.
It is configured and scripted via Lua, so the config file is a Lua file.
-You can use any pure Lua library to do whatever you want.
-
+You can use any pure Lua library to do whatever you want.\
+ \
Hilbish's sample configuration is usually located in `hilbish.dataDir .. '/.hilbishrc.lua'`.
-You can print that path via Lua to see what it is: `print(hilbish.dataDir .. '/.hilbishrc.lua')`.
-As an example, it will usually will result in `/usr/share/hilbish/.hilbishrc.lua` on Linux.
-
-To edit your user configuration, you can copy that file to `hilbish.userDir.config .. '/hilbish/init.lua'`,
-which follows XDG on Linux and MacOS, and is located in %APPDATA% on Windows.
-
+You can print that path via Lua to see what it is: `print(hilbish.dataDir .. '/.hilbishrc.lua')`.\
+ \
+As an example, it will usually will result in `/usr/share/hilbish/.hilbishrc.lua` on Linux.\
+ \
+To edit your user configuration, you can copy that file to `hilbish.userDir.config .. '/hilbish/init.lua'`, which follows XDG on Linux and MacOS, and is located in %APPDATA% on Windows.\
+ \
As the directory is usually `~/.config` on Linux, you can run this command to copy it:
-`cp /usr/share/hilbish/.hilbishrc.lua ~/.config/hilbish/init.lua`
+`cp /usr/share/hilbish/.hilbishrc.lua ~/.config/hilbish/init.lua`. Now we can get to customization!\
+ \
+If we closely examine a small snippet of the default config:
-Now we can get to customization!
-
-If we closely examine a small snippet of the default config:
```lua
-- Default Hilbish config
-- .. with some omitted code .. --
@@ -72,20 +73,19 @@ bait.catch('command.exit', function(code)
doPrompt(code ~= 0)
end)
```
-
+\
+
We see a whopping **three** Hilbish libraries being used in this part of code.
First is of course, named after the shell itself, [`hilbish`](../api/hilbish). This is kind of a
-"catch-all" namespace for functions that directly related to shell functionality/settings.
-
+"catch-all" namespace for functions that directly related to shell functionality/settings.\
+ \
And as we can see, the [hilbish.prompt](../api/hilbish/#prompt) function is used
-to change our prompt. Change our prompt to what, exactly?
-
-The doc for the function states that the verbs `%u` and `%d`are used for username and current directory
-of the shell, respectively.
-
+to change our prompt. Change our prompt to what, exactly?\
+The doc for the function states that the verbs `%u` and `%d` are used for username and current directory of the shell, respectively.\
We wrap this in the [`lunacolors.format`](../lunacolors) function, to give
-our prompt some nice color.
-
+our prompt some nice color.\
+ \
+
But you might have also noticed that this is in the `doPrompt` function, which is called once,
and then used again in a [bait](../api/bait) hook. Specifically, the `command.exit` hook,
which is called after a command exits, so when it finishes running.
diff --git a/docs/hooks/command.md b/docs/hooks/command.md
index 2e3163e1..3df9350d 100644
--- a/docs/hooks/command.md
+++ b/docs/hooks/command.md
@@ -8,35 +8,46 @@ menu:
---
## command.preexec
+
Thrown right before a command is executed.
#### Variables
-`string` **`input`**
+
+`string` _input_
The raw string that the user typed. This will include the text
without changes applied to it (argument substitution, alias expansion,
etc.)
-`string` **`cmdStr`**
+`string` _cmdStr_
The command that will be directly executed by the current runner.
-
+``` =html
+
+```
## command.exit
+
Thrown after the user's ran command is finished.
#### Variables
-`number` **`code`**
+
+`number` _code_
The exit code of what was executed.
-`string` **`cmdStr`**
+`string` _cmdStr_
The command or code that was executed
-
-
+``` =html
+
+```
+
## command.not-found
+
Thrown if the command attempted to execute was not found.
This can be used to customize the text printed when a command is not found.
+
Example:
+
```lua
local bait = require 'bait'
-- Remove any present handlers on `command.not-found`
@@ -53,15 +64,20 @@ end)
```
#### Variables
-`string` **`cmdStr`**
+
+`string` _cmdStr_
The name of the command.
-
-
+``` =html
+
+```
+
## command.not-executable
+
Thrown when the user attempts to run a file that is not executable
(like a text file, or Unix binary without +x permission).
#### Variables
-`string` **`cmdStr`**
+
+`string` _cmdStr_
The name of the command.
diff --git a/docs/hooks/hilbish.md b/docs/hooks/hilbish.md
index 038b7216..121c9809 100644
--- a/docs/hooks/hilbish.md
+++ b/docs/hooks/hilbish.md
@@ -8,64 +8,87 @@ menu:
---
## hilbish.exit
+
Sent when Hilbish is going to exit.
#### Variables
+
This signal returns no variables.
-
+``` =html
+
+```
## hilbish.vimMode
+
Sent when the Vim mode of Hilbish is changed (like from insert to normal mode).
This can be used to change the prompt and notify based on Vim mode.
#### Variables
-`string` **`modeName`**
+
+`string` _modeName_
The mode that has been set.
Can be these values: `insert`, `normal`, `delete` or `replace`
-
+``` =html
+
+```
## hilbish.cancel
+
Sent when the user cancels their command input with Ctrl-C
#### Variables
+
This signal returns no variables.
-
+``` =html
+
+```
## hilbish.notification
+
Thrown when a [notification](../../features/notifications) is sent.
#### Variables
-`table` **`notification`**
+
+`table` _notification_
The notification. The properties are defined in the link above.
-
+``` =html
+
+```
## hilbish.cd
+
Sent when the current directory of the shell is changed (via interactive means.)
-If you are implementing a custom command that changes the directory of the shell,
-you must throw this hook manually for correctness.
+~~If you are implementing a custom command that changes the directory of the shell, you must throw this hook manually for correctness.~~ Since 3.0, `hilbish.cd` is thrown when `fs.cd` is called.
#### Variables
-`string` **`path`**
+
+`string` _path_
Absolute path of the directory that was changed to.
-`string` **`oldPath`**
+`string` _oldPath_
Absolute path of the directory Hilbish *was* in.
-
+``` =html
+
+```
## hilbish.vimAction
+
Sent when the user does a "vim action," being something like yanking or pasting text.
See `doc vim-mode actions` for more info.
#### Variables
-`string` **`actionName`**
+
+`string` _actionName_
Absolute path of the directory that was changed to.
-`table` **`args`**
+`table` _args_
Table of args relating to the Vim action.
-
+``` =html
+
+```
diff --git a/docs/hooks/job.md b/docs/hooks/job.md
index f37c8bea..fba64444 100644
--- a/docs/hooks/job.md
+++ b/docs/hooks/job.md
@@ -1,7 +1,6 @@
Note: `job` refers to a job object. You can check `doc jobs` for more
detail.
-+ `job.start` -> job > Thrown when a new background job starts.
-
-+ `job.done` -> job > Thrown when a background jobs exits.
+- `job.start` -> job > Thrown when a new background job starts.
+- `job.done` -> job > Thrown when a background jobs exits.
diff --git a/docs/hooks/signal.md b/docs/hooks/signal.md
index 63834b09..5ba77357 100644
--- a/docs/hooks/signal.md
+++ b/docs/hooks/signal.md
@@ -8,33 +8,46 @@ menu:
---
## signal.sigint
+
Thrown when Hilbish receive the SIGINT signal,
aka when Ctrl-C is pressed.
#### Variables
+
This signal returns no variables.
-
+``` =html
+
+```
## signal.resize
+
Thrown when the terminal is resized.
#### Variables
+
This signal returns no variables.
-
+``` =html
+
+```
## signal.sigusr1
+
Thrown when SIGUSR1 is sent to Hilbish.
#### Variables
+
This signal returns no variables.
-
+``` =html
+
+```
## signal.sigusr2
+
Thrown when SIGUSR2 is sent to Hilbish.
#### Variables
-This signal returns no variables.
+This signal returns no variables.
diff --git a/docs/nature/_index.md b/docs/nature/_index.md
index 4a3bc355..165fa062 100644
--- a/docs/nature/_index.md
+++ b/docs/nature/_index.md
@@ -8,12 +8,12 @@ menu: docs
A bit after creation, we have the outside nature. Little plants, seeds,
growing to their final phase: a full plant. A lot of Hilbish itself is
written in Go, but there are parts made in Lua, being most builtins
-(`doc`, `cd`, cdr), completions, and other things.
-
+(`doc`, `cd`, cdr), completions, and other things.\
Hilbish's Lua core module is called `nature`.
It runs after Hilbish's Go core does.
# Nature Modules
-Currently, `nature` provides 1 intended public module: `nature.dirs`.
+
+Currently, `nature` provides 1 intended public module: `nature.dirs`.\
It is a simple API for managing recent directories and old
current working directory.
diff --git a/docs/vim-mode/actions.md b/docs/vim-mode/actions.md
index 97578273..9a2f375e 100644
--- a/docs/vim-mode/actions.md
+++ b/docs/vim-mode/actions.md
@@ -9,12 +9,12 @@ menu:
Vim actions are essentially just when a user uses a Vim keybind.
Things like yanking and pasting are Vim actions.
-This is not an "offical Vim thing," just a Hilbish thing.
-
+This is not an "offical Vim thing," just a Hilbish thing.\
+ \
The `hilbish.vimAction` hook is thrown whenever a Vim action occurs.
It passes 2 arguments: the action name, and an array (table) of args
-relating to it.
-
+relating to it.\
+ \
Here is documentation for what the table of args will hold for an
appropriate Vim action.