From 66c1eb95cd1f970f2e069037cf5332ddd748679a Mon Sep 17 00:00:00 2001
From: sammyette <torchedsammy@gmail.com>
Date: Tue, 13 Dec 2022 19:02:22 -0400
Subject: [PATCH] docs: add docs for hilbish.runner interface

---
 docs/api/hilbish/hilbish.runner.md | 28 ++++++++++++++++++++++++++++
 emmyLuaDocs/hilbish.lua            | 14 ++++++++++++++
 runnermode.go                      | 23 +++++++++++++++++++++++
 3 files changed, 65 insertions(+)
 create mode 100644 docs/api/hilbish/hilbish.runner.md

diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md
new file mode 100644
index 0000000..0b074b4
--- /dev/null
+++ b/docs/api/hilbish/hilbish.runner.md
@@ -0,0 +1,28 @@
+---
+name: Interface hilbish.runner
+description: interactive command runner customization
+layout: apidoc
+---
+
+## 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. 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.
+
+### lua(cmd)
+Evaluates `cmd` as Lua input. This is the same as using `dofile`
+or `load`, but is appropriated for the runner interface.
+
+### sh(cmd)
+Runs a command in Hilbish's shell script interpreter.
+This is the equivalent of using `source`.
+
diff --git a/emmyLuaDocs/hilbish.lua b/emmyLuaDocs/hilbish.lua
index 9d8180e..67c512b 100644
--- a/emmyLuaDocs/hilbish.lua
+++ b/emmyLuaDocs/hilbish.lua
@@ -7,6 +7,12 @@ local hilbish = {}
 --- @param cmd string
 function hilbish.aliases.add(alias, cmd) end
 
+--- 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.
+function hilbish.runner.setMode(cb) end
+
 --- Calls a completer function. This is mainly used to call
 --- a command completer, which will have a `name` in the form
 --- of `command.name`, example: `command.git`
@@ -128,6 +134,14 @@ function hilbish.completions.bins(query, ctx, fields) end
 --- Returns file completion candidates based on the provided query.
 function hilbish.completions.files(query, ctx, fields) end
 
+--- Evaluates `cmd` as Lua input. This is the same as using `dofile`
+--- or `load`, but is appropriated for the runner interface.
+function hilbish.runner.lua(cmd) end
+
+--- Runs a command in Hilbish's shell script interpreter.
+--- This is the equivalent of using `source`.
+function hilbish.runner.sh(cmd) end
+
 --- Stops a timer.
 function hilbish.timers:stop() end
 
diff --git a/runnermode.go b/runnermode.go
index c26ed03..e212604 100644
--- a/runnermode.go
+++ b/runnermode.go
@@ -6,6 +6,13 @@ import (
 	rt "github.com/arnodel/golua/runtime"
 )
 
+// #interface runner
+// interactive command runner customization
+// 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.
 func runnerModeLoader(rtm *rt.Runtime) *rt.Table {
 	exports := map[string]util.LuaExport{
 		"sh": {shRunner, 1, false},
@@ -19,6 +26,18 @@ func runnerModeLoader(rtm *rt.Runtime) *rt.Table {
 	return mod
 }
 
+// #interface 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.
+func _runnerMode() {}
+
+// #interface runner
+// sh(cmd)
+// Runs a command in Hilbish's shell script interpreter.
+// This is the equivalent of using `source`.
 func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err
@@ -42,6 +61,10 @@ func shRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext(t.Runtime, rt.TableValue(runnerRet)), nil
 }
 
+// #interface runner
+// lua(cmd)
+// Evaluates `cmd` as Lua input. This is the same as using `dofile`
+// or `load`, but is appropriated for the runner interface.
 func luaRunner(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err