docs: minor changes and fixes

api.go

@@ -237,7 +237,7 @@ func hlrun(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // cwd() -> string
-// Returns the current directory of the shell
+// Returns the current directory of the shell.
 // #returns string
 func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	cwd, _ := os.Getwd()
@@ -249,8 +249,8 @@ func hlcwd(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // 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).
+// Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
-// #param prompt? string
+// #param prompt? string Text to print before input, can be empty.
 // #returns string|nil
 func hlread(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	luaprompt := c.Arg(0)
@@ -479,8 +479,9 @@ func hlexec(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // goro(fn)
 // Puts `fn` in a Goroutine.
-// This can be used to run any function in another thread.
+// 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.**
 // #param fn function
 func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
@@ -503,10 +504,10 @@ func hlgoro(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // timeout(cb, time) -> @Timer
-// Runs the `cb` function after `time` in milliseconds.
+// Executed the `cb` function after a period of `time`.
-// This creates a Timer that starts immediately.
+// This creates a Timer that starts ticking immediately.
 // #param cb function
-// #param time number
+// #param time number Time to run in milliseconds.
 // #returns Timer
 func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
@@ -529,10 +530,10 @@ func hltimeout(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // interval(cb, time) -> @Timer
-// Runs the `cb` function every `time` milliseconds.
+// Runs the `cb` function every specified amount of `time`.
-// This creates a timer that starts immediately.
+// This creates a timer that ticking immediately.
 // #param cb function
-// #param time number
+// #param time number Time in milliseconds.
 // #return Timer
 func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
@@ -556,12 +557,39 @@ func hlinterval(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 
 // complete(scope, cb)
 // Registers a completion handler for the specified scope.
-// A `scope` is currently only expected to be `command.<cmd>`,
+// A `scope` is expected to be `command.<cmd>`,
 // replacing <cmd> with the name of the command (for example `command.git`).
 // The documentation for completions, under Features/Completions or `doc completions`
 // provides more details.
 // #param scope string
 // #param cb function
+/*
+#example
+-- 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)
+#example
+*/
 func hlcomplete(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	scope, cb, err := util.HandleStrCallback(t, c)
 	if err != nil {
@@ -628,10 +656,10 @@ func hlwhich(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // inputMode(mode)
-// Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
+// 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.
-// #param mode string
+// #param mode string Can be set to either `emacs` or `vim`
 func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -656,11 +684,13 @@ func hlinputMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // runnerMode(mode)
-// Sets the execution/runner mode for interactive Hilbish. This determines whether
+// Sets the execution/runner mode for interactive Hilbish.
-// Hilbish wll try to run input as Lua and/or sh or only do one of either.
+// 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.
+// Read [about runner mode](../features/runner-mode) for more information.
 // #param mode string|function
 func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
@@ -688,7 +718,7 @@ func hlrunnerMode(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // as the text for the hint. This is by default a shim. To set hints,
 // override this function with your custom handler.
 // #param line string
-// #param pos number
+// #param pos number Position of cursor in line. Usually equals string.len(line)
 /*
 #example
 -- this will display "hi" after the cursor in a dimmed color.

docs/api/bait.md

@@ -37,7 +37,7 @@ this function will set the user prompt.
 |----|----|
 |<a href="#catch">catch(name, cb)</a>|Catches an event. This function can be used to act on events.|
 |<a href="#catchOnce">catchOnce(name, cb)</a>|Catches an event, but only once. This will remove the hook immediately after it runs for the first time.|
-|<a href="#hooks">hooks(name) -> table</a>|Returns a list of callbacks that are hooked on an event with the corresponding `name`.|
+|<a href="#hooks">hooks(name) -> table</a>|Returns a table of functions that are hooked on an event with the corresponding `name`.|
 |<a href="#release">release(name, catcher)</a>|Removes the `catcher` for the event with `name`.|
 |<a href="#throw">throw(name, ...args)</a>|Throws a hook with `name` with the provided `args`.|
 
@@ -96,11 +96,11 @@ bait.hooks(name) -> table
 </a>
 </h4>
 
-Returns a list of callbacks that are hooked on an event with the corresponding `name`.  
+Returns a table of functions that are hooked on an event with the corresponding `name`.  
 
 #### Parameters
 `string` **`name`**  
-The name of the function
+The name of the hook
 
 </div>
 

docs/api/fs.md

@@ -167,9 +167,6 @@ fs.mkdir(name, recursive)
 
 Creates a new directory with the provided `name`.  
 With `recursive`, mkdir will create parent directories.  
--- This will create the directory foo, then create the directory bar in the  
--- foo directory. If recursive is false in this case, it will fail.  
-fs.mkdir('./foo/bar', true)  
 
 #### Parameters
 `string` **`name`**  
@@ -180,7 +177,9 @@ Whether to create parent directories for the provided name
 
 #### Example
 ```lua
-
+-- This will create the directory foo, then create the directory bar in the
+-- foo directory. If recursive is false in this case, it will fail.
+fs.mkdir('./foo/bar', true)
 ```
 </div>
 

docs/api/hilbish/_index.md

@@ -17,20 +17,20 @@ interfaces and functions which directly relate to shell functionality.
 |<a href="#alias">alias(cmd, orig)</a>|Sets an alias, with a name of `cmd` to another command.|
 |<a href="#appendPath">appendPath(dir)</a>|Appends the provided dir to the command path (`$PATH`)|
 |<a href="#complete">complete(scope, cb)</a>|Registers a completion handler for the specified scope.|
-|<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell|
+|<a href="#cwd">cwd() -> string</a>|Returns the current directory of the shell.|
 |<a href="#exec">exec(cmd)</a>|Replaces the currently running Hilbish instance with the supplied command.|
 |<a href="#goro">goro(fn)</a>|Puts `fn` in a Goroutine.|
 |<a href="#highlighter">highlighter(line)</a>|Line highlighter handler.|
 |<a href="#hinter">hinter(line, pos)</a>|The command line hint handler. It gets called on every key insert to|
-|<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.|
+|<a href="#inputMode">inputMode(mode)</a>|Sets the input mode for Hilbish's line reader.|
-|<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every `time` milliseconds.|
+|<a href="#interval">interval(cb, time) -> @Timer</a>|Runs the `cb` function every specified amount of `time`.|
 |<a href="#multiprompt">multiprompt(str)</a>|Changes the text prompt when Hilbish asks for more input.|
 |<a href="#prependPath">prependPath(dir)</a>|Prepends `dir` to $PATH.|
 |<a href="#prompt">prompt(str, typ)</a>|Changes the shell prompt to the provided string.|
 |<a href="#read">read(prompt) -> input (string)</a>|Read input from the user, using Hilbish's line editor/input reader.|
 |<a href="#run">run(cmd, returnOut) -> exitCode (number), stdout (string), stderr (string)</a>|Runs `cmd` in Hilbish's shell script interpreter.|
-|<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish. This determines whether|
+|<a href="#runnerMode">runnerMode(mode)</a>|Sets the execution/runner mode for interactive Hilbish.|
-|<a href="#timeout">timeout(cb, time) -> @Timer</a>|Runs the `cb` function after `time` in milliseconds.|
+|<a href="#timeout">timeout(cb, time) -> @Timer</a>|Executed the `cb` function after a period of `time`.|
 |<a href="#which">which(name) -> string</a>|Checks if `name` is a valid command.|
 
 ## Static module fields
@@ -113,7 +113,7 @@ hilbish.complete(scope, cb)
 </h4>
 
 Registers a completion handler for the specified scope.  
-A `scope` is currently only expected to be `command.<cmd>`,  
+A `scope` is expected to be `command.<cmd>`,  
 replacing <cmd> with the name of the command (for example `command.git`).  
 The documentation for completions, under Features/Completions or `doc completions`  
 provides more details.  
@@ -125,6 +125,32 @@ provides more details.
 `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)
+```
 </div>
 
 <hr>
@@ -136,7 +162,7 @@ hilbish.cwd() -> string
 </a>
 </h4>
 
-Returns the current directory of the shell  
+Returns the current directory of the shell.  
 
 #### Parameters
 This function has no parameters.  
@@ -170,8 +196,9 @@ hilbish.goro(fn)
 </h4>
 
 Puts `fn` in a Goroutine.  
-This can be used to run any function in another thread.  
+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`**  
@@ -227,7 +254,7 @@ override this function with your custom handler.
 
 
 `number` **`pos`**  
-
+Position of cursor in line. Usually equals string.len(line)
 
 #### Example
 ```lua
@@ -247,13 +274,13 @@ hilbish.inputMode(mode)
 </a>
 </h4>
 
-Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.  
+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`
 
 </div>
 
@@ -266,15 +293,15 @@ hilbish.interval(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/
 </a>
 </h4>
 
-Runs the `cb` function every `time` milliseconds.  
+Runs the `cb` function every specified amount of `time`.  
-This creates a timer that starts immediately.  
+This creates a timer that ticking immediately.  
 
 #### Parameters
 `function` **`cb`**  
 
 
 `number` **`time`**  
-
+Time in milliseconds.
 
 </div>
 
@@ -375,11 +402,11 @@ 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).  
+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.
 
 </div>
 
@@ -412,11 +439,13 @@ hilbish.runnerMode(mode)
 </a>
 </h4>
 
-Sets the execution/runner mode for interactive Hilbish. This determines whether  
+Sets the execution/runner mode for interactive Hilbish.  
-Hilbish wll try to run input as Lua and/or sh or only do one of either.  
+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.  
+Read [about runner mode](../features/runner-mode) for more information.  
 
 #### Parameters
 `string|function` **`mode`**  
@@ -433,15 +462,15 @@ hilbish.timeout(cb, time) -> <a href="/Hilbish/docs/api/hilbish/hilbish.timers/#
 </a>
 </h4>
 
-Runs the `cb` function after `time` in milliseconds.  
+Executed the `cb` function after a period of `time`.  
-This creates a Timer that starts immediately.  
+This creates a Timer that starts ticking immediately.  
 
 #### Parameters
 `function` **`cb`**  
 
 
 `number` **`time`**  
-
+Time to run in milliseconds.
 
 </div>
 

docs/api/hilbish/hilbish.jobs.md

@@ -43,7 +43,7 @@ String that a user would write for the job
 Arguments for the commands. Has to include the name of the command.
 
 `string` **`execPath`**  
-Binary to use to run the command. Does not
+Binary to use to run the command. Needs to be an absolute path.
 
 #### Example
 ```lua

docs/api/hilbish/hilbish.runner.md

@@ -14,6 +14,41 @@ 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.
 
+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.
+```lua
+local fennel = require 'fennel'
+
+hilbish.runnerMode(function(input)
+	local ok = pcall(fennel.eval, input)
+	if ok then
+		return {
+			input = input
+		}
+	end
+
+	return hilbish.runner.sh(input)
+end)
+```
+
 ## Functions
 |||
 |----|----|

docs/completions.md

@@ -7,59 +7,72 @@ menu:
     parent: "Features"
 ---
 
-Hilbish has a pretty good completion system. It has a nice looking
+Completions for commands can be created with the [`hilbish.complete`](../api/hilbish#complete)
-menu, with 2 types of menus: grid (like file completions) or
+function. See the link for how to use it.
-list.
 
+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:
+```lua
+local cg = {
+	items = {
+		'list item 1',
+		['--command-flag-here'] = {'this does a thing', '--the-flag-alias'}
+	},
+	type = 'list'
+}
+local cg2 = {
+	items = {'just', 'a bunch', 'of items', 'here', 'hehe'},
+	type = 'grid'
+}
+
+return {cg, cg2}, prefix
+```
+
+Which looks like this:  
+{{< video src="https://safe.saya.moe/t4CiLK6dgPbD.mp4" >}}
+
+# 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.
 
-# Completion Handler
+The default completion handler provides 3 things:
-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. With the default 
+$PATH), files, or command completions. It will try to run a handler
-completion handler, it will try to run a handler for the 
+for the  command or fallback to file completions.
-command or fallback to file completions.
 
-To overwrite it, just assign a function to
+To overwrite it, just assign a function to `hilbish.completion.handler` like so:
-`hilbish.completion.handler` like so:
+```lua
+-- line is the entire line as a string
+-- pos is the position of the cursor.
 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 line
-- `fields` 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>`

docs/features/runner-mode.md

@@ -19,3 +19,48 @@ 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.
+
+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](../../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.
+
+A runner function is expected to return a table with the following values:
+- `exitCode` (number): Exit code of the command
+- `input` (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 `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.

docs/jobs.md

@@ -1,11 +1,4 @@
----
+(This has mainly been replaced by [hilbish.jobs](../api/hilbish.jobs)).
-title: Jobs
-description: Controls for background commands in Hilbish.
-layout: doc
-menu: 
-  docs:
-    parent: "Features"
----
 
 Hilbish has pretty standard job control. It's missing one or two things,
 but works well. One thing which is different from other shells

docs/runner-mode.md

@@ -1,70 +0,0 @@
-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](https://github.com/TorchedSammy/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 example, you can set this to a simple
-function to compile and evaluate Fennel, and now you can run Fennel.
-You can even mix it with sh to make a hybrid mode with Lua replaced by
-Fennel.
-
-An example:
-hilbish.runnerMode(function(input)
-	local ok = pcall(fennel.eval, input)
-	if ok then
-		return input, 0, nil
-	end
-
-	return hilbish.runner.sh(input)
-end)
-
-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 command
-- `input` (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 `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.

emmyLuaDocs/bait.lua

@@ -10,7 +10,7 @@ function bait.catch(name, cb) end
 --- Catches an event, but only once. This will remove the hook immediately after it runs for the first time.
 function bait.catchOnce(name, cb) end
 
---- Returns a list of callbacks that are hooked on an event with the corresponding `name`.
+--- Returns a table of functions that are hooked on an event with the corresponding `name`.
 function bait.hooks(name) end
 
 --- Removes the `catcher` for the event with `name`.

emmyLuaDocs/fs.lua

@@ -31,9 +31,7 @@ function fs.join(...path) end
 --- Creates a new directory with the provided `name`.
 --- With `recursive`, mkdir will create parent directories.
 --- 
---- -- This will create the directory foo, then create the directory bar in the
+--- 
---- -- foo directory. If recursive is false in this case, it will fail.
---- fs.mkdir('./foo/bar', true)
 function fs.mkdir(name, recursive) end
 
 --- Returns a list of all files and directories in the provided path.

emmyLuaDocs/hilbish.lua

@@ -61,13 +61,15 @@ function hilbish.alias(cmd, orig) end
 function hilbish.appendPath(dir) end
 
 --- Registers a completion handler for the specified scope.
---- A `scope` is currently only expected to be `command.<cmd>`,
+--- A `scope` is expected to be `command.<cmd>`,
 --- replacing <cmd> with the name of the command (for example `command.git`).
 --- The documentation for completions, under Features/Completions or `doc completions`
 --- provides more details.
+--- 
+--- 
 function hilbish.complete(scope, cb) end
 
---- Returns the current directory of the shell
+--- Returns the current directory of the shell.
 function hilbish.cwd() end
 
 --- Replaces the currently running Hilbish instance with the supplied command.
@@ -75,8 +77,9 @@ function hilbish.cwd() end
 function hilbish.exec(cmd) end
 
 --- Puts `fn` in a Goroutine.
---- This can be used to run any function in another thread.
+--- 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.**
 function hilbish.goro(fn) end
 
 --- Line highlighter handler.
@@ -96,13 +99,13 @@ function hilbish.highlighter(line) end
 --- 
 function hilbish.hinter(line, pos) end
 
---- Sets the input mode for Hilbish's line reader. Accepts either emacs or vim.
+--- 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.
 function hilbish.inputMode(mode) end
 
---- Runs the `cb` function every `time` milliseconds.
+--- Runs the `cb` function every specified amount of `time`.
---- This creates a timer that starts immediately.
+--- This creates a timer that ticking immediately.
 function hilbish.interval(cb, time) end
 
 --- Changes the text prompt when Hilbish asks for more input.
@@ -125,21 +128,23 @@ function hilbish.prompt(str, typ) end
 
 --- 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).
+--- Returns `input`, will be nil if Ctrl-D is pressed, or an error occurs.
 function hilbish.read(prompt) end
 
 --- Runs `cmd` in Hilbish's shell script interpreter.
 function hilbish.run(cmd, returnOut) end
 
---- Sets the execution/runner mode for interactive Hilbish. This determines whether
+--- Sets the execution/runner mode for interactive Hilbish.
---- Hilbish wll try to run input as Lua and/or sh or only do one of either.
+--- 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.
+--- Read [about runner mode](../features/runner-mode) for more information.
 function hilbish.runnerMode(mode) end
 
---- Runs the `cb` function after `time` in milliseconds.
+--- Executed the `cb` function after a period of `time`.
---- This creates a Timer that starts immediately.
+--- This creates a Timer that starts ticking immediately.
 function hilbish.timeout(cb, time) end
 
 --- Checks if `name` is a valid command.

golibs/bait/bait.go

@@ -285,8 +285,8 @@ func (b *Bait) bcatchOnce(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // hooks(name) -> table
-// Returns a list of callbacks that are hooked on an event with the corresponding `name`.
+// Returns a table of functions that are hooked on an event with the corresponding `name`.
-// #param name string The name of the function
+// #param name string The name of the hook
 // #returns table<function>
 func (b *Bait) bhooks(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {

golibs/fs/fs.go

@@ -198,6 +198,7 @@ func fjoin(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 -- This will create the directory foo, then create the directory bar in the
 -- foo directory. If recursive is false in this case, it will fail.
 fs.mkdir('./foo/bar', true)
+#example
 */
 func fmkdir(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {

job.go

@@ -418,7 +418,7 @@ func (j *jobHandler) luaGetJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // used by runners, but can also be used to create jobs via Lua. Commanders cannot be ran as jobs.
 // #param cmdstr string String that a user would write for the job
 // #param args table Arguments for the commands. Has to include the name of the command.
-// #param execPath string Binary to use to run the command. Does not 
+// #param execPath string Binary to use to run the command. Needs to be an absolute path.
 /*
 #example
 hilbish.jobs.add('go build', {'go', 'build'}, '/usr/bin/go')

runnermode.go

@@ -8,11 +8,47 @@ import (
 
 // #interface runner
 // interactive command runner customization
-// The runner interface contains functions that allow the user to change
+/* The runner interface contains functions that allow the user to change
-// how Hilbish interprets interactive input.
+how Hilbish interprets interactive input.
-// Users can add and change the default runner for interactive input to any
+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
+language or script of their choosing. A good example is using it to
-// write command in Fennel.
+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.
+```lua
+local fennel = require 'fennel'
+
+hilbish.runnerMode(function(input)
+	local ok = pcall(fennel.eval, input)
+	if ok then
+		return {
+			input = input
+		}
+	end
+
+	return hilbish.runner.sh(input)
+end)
+```
+*/
 func runnerModeLoader(rtm *rt.Runtime) *rt.Table {
 	exports := map[string]util.LuaExport{
 		"sh": {shRunner, 1, false},

website/themes/hsh/layouts/shortcodes/video.html

@@ -0,0 +1,5 @@
+<video src="{{ .Get "src" }}" style="height: auto; max-width: 100%;" controls>
+    There's a video missing here...
+    Well here is the URL: {{ .Get "src" }}
+</video>
+