From 23d18ef11c41070964d4d680bae54737c03b884f Mon Sep 17 00:00:00 2001
From: TorchedSammy <38820196+TorchedSammy@users.noreply.github.com>
Date: Sat, 3 Dec 2022 16:54:34 -0400
Subject: [PATCH] docs: push fixed docs

---
 docs/api/bait.md      |  96 ++++++++--------------------------------
 docs/api/commander.md |  19 +++-----
 docs/api/fs.md        | 100 +++++++++++-------------------------------
 docs/api/terminal.md  |  90 +++++--------------------------------
 4 files changed, 61 insertions(+), 244 deletions(-)

diff --git a/docs/api/bait.md b/docs/api/bait.md
index 829ba86..2eaaffe 100644
--- a/docs/api/bait.md
+++ b/docs/api/bait.md
@@ -1,91 +1,31 @@
 ---
 name: Module bait
-description: the core Hilbish API
+description: the event emitter
 layout: apidoc
 ---
 
 ## Introduction
-The Hilbish module includes the core API, containing
-interfaces and functions which directly relate to shell functionality.
+Bait is the event emitter for Hilbish. Why name it bait? Why not.
+It throws hooks that you can catch. This is what you will use if
+you want to listen in on hooks to know when certain things have
+happened, like when you've changed directory, a command has failed,
+etc. To find all available hooks thrown by Hilbish, see doc hooks.
 
 ## Functions
-### alias(cmd, orig)
-Sets an alias of `cmd` to `orig`
+### catch(name, cb)
+Catches a hook with `name`. Runs the `cb` when it is thrown
 
-### appendPath(dir)
-Appends `dir` to $PATH
+### catchOnce(name, cb)
+Same as catch, but only runs the `cb` once and then removes the hook
 
-### complete(scope, cb)
-Registers a completion handler for `scope`.
-A `scope` is currently only expected to be `command.<cmd>`,
-replacing <cmd> 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.
+### hooks(name) -> {cb, cb...}
+Returns a table with hooks on the event with `name`.
 
-### cwd()
-Returns the current directory of the shell
+### release(name, catcher)
+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.
 
-### 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
-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.
-
-### 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.
-
-### inputMode(mode)
-Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
-
-### interval(cb, time)
-Runs the `cb` function every `time` milliseconds.
-Returns a `timer` object (see `doc timers`).
-
-### multiprompt(str)
-Changes the continued line prompt to `str`
-
-### prependPath(dir)
-Prepends `dir` to $PATH
-
-### prompt(str, typ?)
-Changes the shell prompt to `str`
-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
-
-### read(prompt?) -> input?
-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)
-
-### run(cmd, returnOut) -> exitCode, stdout, stderr
-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.
-
-### 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.
-
-### timeout(cb, time)
-Runs the `cb` function after `time` in milliseconds
-Returns a `timer` object (see `doc timers`).
-
-### which(name)
-Checks if `name` is a valid command
+### throw(name, ...args)
+Throws a hook with `name` with the provided `args`
 
diff --git a/docs/api/commander.md b/docs/api/commander.md
index 01031d6..379ecba 100644
--- a/docs/api/commander.md
+++ b/docs/api/commander.md
@@ -1,23 +1,16 @@
 ---
 name: Module commander
-description: low level terminal library
+description: library for custom commands
 layout: apidoc
 ---
 
 ## Introduction
-The terminal library is a simple and lower level library for certain terminal interactions.
+Commander is a library for writing custom commands in Lua.
 
 ## Functions
-### restoreState()
-Restores the last saved state of the terminal
+### deregister(name)
+Deregisters any command registered with `name`
 
-### saveState()
-Saves the current state of the terminal
-
-### setRaw()
-Puts the terminal in raw mode
-
-### 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
+### register(name, cb)
+Register a command with `name` that runs `cb` when ran
 
diff --git a/docs/api/fs.md b/docs/api/fs.md
index 3a9db21..3800422 100644
--- a/docs/api/fs.md
+++ b/docs/api/fs.md
@@ -1,91 +1,43 @@
 ---
 name: Module fs
-description: the core Hilbish API
+description: filesystem interaction and functionality library
 layout: apidoc
 ---
 
 ## Introduction
-The Hilbish module includes the core API, containing
-interfaces and functions which directly relate to shell functionality.
+The fs module provides easy and simple access to filesystem functions
+and other things, and acts an addition to the Lua standard library's
+I/O and filesystem functions.
 
 ## Functions
-### alias(cmd, orig)
-Sets an alias of `cmd` to `orig`
+### abs(path)
+Gives an absolute version of `path`.
 
-### appendPath(dir)
-Appends `dir` to $PATH
+### basename(path)
+Gives the basename of `path`. For the rules,
+see Go's filepath.Base
 
-### complete(scope, cb)
-Registers a completion handler for `scope`.
-A `scope` is currently only expected to be `command.<cmd>`,
-replacing <cmd> 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.
+### cd(dir)
+Changes directory to `dir`
 
-### cwd()
-Returns the current directory of the shell
+### dir(path)
+Returns the directory part of `path`. For the rules, see Go's
+filepath.Dir
 
-### exec(cmd)
-Replaces running hilbish with `cmd`
+### glob(pattern)
+Glob all files and directories that match the pattern.
+For the rules, see Go's filepath.Glob
 
-### goro(fn)
-Puts `fn` in a goroutine
+### join(paths...)
+Takes paths and joins them together with the OS's
+directory separator (forward or backward slash).
 
-### 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.
+### mkdir(name, recursive)
+Makes a directory called `name`. If `recursive` is true, it will create its parent directories.
 
-### 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.
+### readdir(dir)
+Returns a table of files in `dir`
 
-### inputMode(mode)
-Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
-
-### interval(cb, time)
-Runs the `cb` function every `time` milliseconds.
-Returns a `timer` object (see `doc timers`).
-
-### multiprompt(str)
-Changes the continued line prompt to `str`
-
-### prependPath(dir)
-Prepends `dir` to $PATH
-
-### prompt(str, typ?)
-Changes the shell prompt to `str`
-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
-
-### read(prompt?) -> input?
-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)
-
-### run(cmd, returnOut) -> exitCode, stdout, stderr
-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.
-
-### 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.
-
-### timeout(cb, time)
-Runs the `cb` function after `time` in milliseconds
-Returns a `timer` object (see `doc timers`).
-
-### which(name)
-Checks if `name` is a valid command
+### stat(path)
+Returns info about `path`
 
diff --git a/docs/api/terminal.md b/docs/api/terminal.md
index 017084d..f1007d8 100644
--- a/docs/api/terminal.md
+++ b/docs/api/terminal.md
@@ -1,91 +1,23 @@
 ---
 name: Module terminal
-description: the core Hilbish API
+description: low level terminal library
 layout: apidoc
 ---
 
 ## Introduction
-The Hilbish module includes the core API, containing
-interfaces and functions which directly relate to shell functionality.
+The terminal library is a simple and lower level library for certain terminal interactions.
 
 ## Functions
-### alias(cmd, orig)
-Sets an alias of `cmd` to `orig`
+### restoreState()
+Restores the last saved state of the terminal
 
-### appendPath(dir)
-Appends `dir` to $PATH
+### saveState()
+Saves the current state of the terminal
 
-### complete(scope, cb)
-Registers a completion handler for `scope`.
-A `scope` is currently only expected to be `command.<cmd>`,
-replacing <cmd> 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.
+### setRaw()
+Puts the terminal in raw mode
 
-### cwd()
-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
-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.
-
-### 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.
-
-### inputMode(mode)
-Sets the input mode for Hilbish's line reader. Accepts either emacs or vim
-
-### interval(cb, time)
-Runs the `cb` function every `time` milliseconds.
-Returns a `timer` object (see `doc timers`).
-
-### multiprompt(str)
-Changes the continued line prompt to `str`
-
-### prependPath(dir)
-Prepends `dir` to $PATH
-
-### prompt(str, typ?)
-Changes the shell prompt to `str`
-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
-
-### read(prompt?) -> input?
-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)
-
-### run(cmd, returnOut) -> exitCode, stdout, stderr
-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.
-
-### 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.
-
-### timeout(cb, time)
-Runs the `cb` function after `time` in milliseconds
-Returns a `timer` object (see `doc timers`).
-
-### which(name)
-Checks if `name` is a valid command
+### 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