docs: upload docs

- add remove function
- change _abbrevs to all for it to be known as publically available
- change the signature of the add function (args not only a single table)
- add documentation
- make expand be either function or string

.github/workflows/docs.yml

@@ -11,8 +11,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
-      - name: Run docgen
+      - name: Download Task
+        run: 'sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d'
+      - name: Build
+        run: ./bin/task
+      - name: Run docgen (go-written)
         run: go run cmd/docgen/docgen.go
+      - name: Run docgen (lua-written)
+        run: ./hilbish cmd/docgen/docgen.lua
       - name: Commit new docs
         uses: stefanzweifel/git-auto-commit-action@v4
         with:

cmd/docgen/docgen.go

@@ -299,7 +299,25 @@ start:
 func main() {
 	fset := token.NewFileSet()
 	os.Mkdir("docs", 0777)
+	os.RemoveAll("docs/api")
 	os.Mkdir("docs/api", 0777)
+
+	f, err := os.Create("docs/api/_index.md")
+	if err != nil {
+		panic(err)
+	}
+	f.WriteString(`---
+title: API
+layout: doc
+weight: -100
+menu: docs
+---
+
+Welcome to the API documentation for Hilbish. This documents Lua functions
+provided by Hilbish.
+`)
+	f.Close()
+
 	os.Mkdir("emmyLuaDocs", 0777)
 
 	dirs := []string{"./"}

cmd/docgen/docgen.lua

@@ -1,7 +1,9 @@
 local fs = require 'fs'
 local emmyPattern = '^%-%-%- (.+)'
-local modpattern = '^%-+ @module (%w+)'
+local emmyPattern2 = '^%-%- (.+)'
+local modpattern = '^%-+ @module (.+)'
 local pieces = {}
+local descriptions = {}
 
 local files = fs.readdir 'nature'
 for _, fname in ipairs(files) do
@@ -15,16 +17,24 @@ for _, fname in ipairs(files) do
 
 	print(fname, mod)
 	pieces[mod] = {}
+	descriptions[mod] = {}
 
 	local docPiece = {}
 	local lines = {}
 	local lineno = 0
+	local doingDescription = true
+
 	for line in f:lines() do
 		lineno = lineno + 1
 		lines[lineno] = line
 
 		if line == header then goto continue2 end
-		if not line:match(emmyPattern) then
+		if line:match(emmyPattern) or line:match(emmyPattern2) then
+			if doingDescription then
+				table.insert(descriptions[mod], line:match(emmyPattern) or line:match(emmyPattern2))
+			end
+		else
+			doingDescription = false
 			if line:match '^function' then
 				local pattern = (string.format('^function %s%%.', mod) .. '(%w+)')
 				local funcName = line:match(pattern)
@@ -49,10 +59,14 @@ for _, fname in ipairs(files) do
 
 						if emmy then
 							if emmy == 'param' then
+								print('bruh', emmythings[1], emmythings[2])
 								table.insert(dps.params, 1, {
 									name = emmythings[1],
-									type = emmythings[2]
+									type = emmythings[2],
+									-- the +1 accounts for space.
+									description = table.concat(emmythings, ' '):sub(emmythings[1]:len() + 1 + emmythings[2]:len() + 1)
 								})
+								print(table.concat(emmythings, '/'))
 							end
 						else
 							table.insert(dps.description, 1, docline)
@@ -81,29 +95,78 @@ description: %s
 layout: doc
 menu:
   docs:
-    parent: "Nature"
+    parent: "%s"
 ---
 
 ]]
 
 for iface, dps in pairs(pieces) do
 	local mod = iface:match '(%w+)%.' or 'nature'
-	local path = string.format('docs/%s/%s.md', mod, iface)
+	local docParent = 'Nature'
+
+	path = string.format('docs/%s/%s.md', mod, iface)
+	if mod ~= 'nature' then
+		docParent = "API"
+		path = string.format('docs/api/%s/%s.md', mod, iface)
+	end
+
 	fs.mkdir(fs.dir(path), true)
-	local f <close> = io.open(path, 'w')
+
-	f:write(string.format(header, 'Module', iface, 'No description.'))
+	local exists = pcall(fs.stat, path)
+	local newOrNotNature = exists and mod ~= 'nature'
+
+	local f <close> = io.open(path, newOrNotNature and 'r+' or 'w+')
+	local tocPos
+	if not newOrNotNature then
+		f:write(string.format(header, 'Module', iface, (descriptions[iface] and #descriptions[iface] > 0) and descriptions[iface][1] or 'No description.', docParent))
+		if descriptions[iface] and #descriptions[iface] > 0 then
+			table.remove(descriptions[iface], 1)
+			f:write(string.format('\n## Introduction\n%s\n\n', table.concat(descriptions[iface], '\n')))
+			f:write('## Functions\n')
+			f:write([[|||
+|----|----|
+]])
+			tocPos = f:seek()
+		end
+	end
 	print(f)
 
-	print(mod, path)
+	print('mod and path:', mod, path)
+
+	local tocSearch = false
+	for line in f:lines() do
+		if line:match '^## Functions' then
+			tocSearch = true
+		end
+		if tocSearch and line == '' then
+			tocSearch = false
+			tocPos = f:seek() - 1
+		end
+	end
 
 	for func, docs in pairs(dps) do
-		f:write(string.format('<hr>\n<div id=\'%s\'>', func))
 		local sig = string.format('%s.%s(', iface, func)
+		local params = ''
 		for idx, param in ipairs(docs.params) do
-			sig = sig .. ((param.name:gsub('%?$', '')))
+			sig = sig .. param.name:gsub('%?$', '')
-			if idx ~= #docs.params then sig = sig .. ', ' end
+			params = params .. param.name:gsub('%?$', '')
+			if idx ~= #docs.params then
+				sig = sig .. ', '
+				params = params .. ', '
+			end
 		end
 		sig = sig .. ')'
+
+		if tocPos then
+			f:seek('set', tocPos)
+			local contents = f:read '*a'
+			f:seek('set', tocPos)
+			local tocLine = string.format('|<a href="#%s">%s</a>|%s|\n', func, string.format('%s(%s)', func, params), docs.description[1])
+			f:write(tocLine .. contents)
+			f:seek 'end'
+		end
+
+		f:write(string.format('<hr>\n<div id=\'%s\'>\n', func))
 		f:write(string.format([[
 <h4 class='heading'>
 %s
@@ -121,6 +184,7 @@ for iface, dps in pairs(pieces) do
 		end
 		for _, param in ipairs(docs.params) do
 			f:write(string.format('`%s` **`%s`**  \n', param.name:gsub('%?$', ''), param.type))
+			f:write(string.format('%s\n\n', param.description))
 		end
 		--[[
 		local params = table.filter(docs, function(t)

docs/api/hilbish/hilbish.abbr.md

@@ -0,0 +1,67 @@
+---
+title: Module hilbish.abbr
+description: command line abbreviations
+layout: doc
+menu:
+  docs:
+    parent: "API"
+---
+
+
+## Introduction
+The abbr module manages Hilbish abbreviations. These are words that can be replaced
+with longer command line strings when entered.
+As an example, `git push` can be abbreviated to `gp`. When the user types
+`gp` into the command line, after hitting space or enter, it will expand to `git push`.
+Abbreviations can be used as an alternative to aliases. They are saved entirely in the history
+Instead of the aliased form of the same command.
+
+## Functions
+|||
+|----|----|
+|<a href="#add">add(abbr, expanded|function, opts)</a>|Adds an abbreviation. The `abbr` is the abbreviation itself,|
+|<a href="#remove">remove(abbr)</a>|Removes the named `abbr`.|
+<hr>
+<div id='remove'>
+<h4 class='heading'>
+hilbish.abbr.remove(abbr)
+<a href="#remove" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Removes the named `abbr`.
+#### Parameters
+`abbr` **`string`**  
+
+
+</div>
+
+<hr>
+<div id='add'>
+<h4 class='heading'>
+hilbish.abbr.add(abbr, expanded|function, opts)
+<a href="#add" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Adds an abbreviation. The `abbr` is the abbreviation itself,
+while `expanded` is what the abbreviation should expand to.
+It can be either a function or a string. If it is a function, it will expand to what
+the function returns.
+`opts` is a table that accepts 1 key: `anywhere`.
+`opts.anywhere` defines whether the abbr expands anywhere in the command line or not,
+whereas the default behavior is only at the beginning of the line
+#### Parameters
+`abbr` **`string`**  
+
+
+`expanded|function` **`string`**  
+
+
+`opts` **`table`**  
+
+
+</div>
+

docs/api/hilbish/hilbish.editor.md

@@ -14,12 +14,30 @@ directly interact with the line editor in use.
 ## Functions
 |||
 |----|----|
+|<a href="#editor.deleteByAmount">deleteByAmount(amount)</a>|Deletes characters in the line by the given amount.|
 |<a href="#editor.getLine">getLine() -> string</a>|Returns the current input line.|
 |<a href="#editor.getVimRegister">getVimRegister(register) -> string</a>|Returns the text that is at the register.|
 |<a href="#editor.insert">insert(text)</a>|Inserts text into the Hilbish command line.|
 |<a href="#editor.getChar">getChar() -> string</a>|Reads a keystroke from the user. This is in a format of something like Ctrl-L.|
 |<a href="#editor.setVimRegister">setVimRegister(register, text)</a>|Sets the vim register at `register` to hold the passed text.|
 
+<hr>
+<div id='editor.deleteByAmount'>
+<h4 class='heading'>
+hilbish.editor.deleteByAmount(amount)
+<a href="#editor.deleteByAmount" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Deletes characters in the line by the given amount.  
+
+#### Parameters
+`number` **`amount`**  
+
+
+</div>
+
 <hr>
 <div id='editor.getLine'>
 <h4 class='heading'>
@@ -96,6 +114,9 @@ hilbish.editor.setVimRegister(register, text)
 Sets the vim register at `register` to hold the passed text.  
 
 #### Parameters
+`string` **`register`**  
+
+
 `string` **`text`**  
 
 

docs/api/hilbish/hilbish.messages.md

@@ -0,0 +1,135 @@
+---
+title: Module hilbish.messages
+description: simplistic message passing
+layout: doc
+menu:
+  docs:
+    parent: "API"
+---
+
+
+## Introduction
+The messages interface defines a way for Hilbish-integrated commands,
+user config and other tasks to send notifications to alert the user.z
+The `hilbish.message` type is a table with the following keys:
+`title` (string): A title for the message notification.
+`text` (string): The contents of the message.
+`channel` (string): States the origin of the message, `hilbish.*` is reserved for Hilbish tasks.
+`summary` (string): A short summary of the `text`.
+`icon` (string): Unicode (preferably standard emoji) icon for the message notification
+`read` (boolean): Whether the full message has been read or not.
+
+## Functions
+|||
+|----|----|
+|<a href="#unreadCount">unreadCount()</a>|Returns the amount of unread messages.|
+|<a href="#readAll">readAll()</a>|Marks all messages as read.|
+|<a href="#send">send(message)</a>|Sends a message.|
+|<a href="#read">read(idx)</a>|Marks a message at `idx` as read.|
+|<a href="#delete">delete(idx)</a>|Deletes the message at `idx`.|
+|<a href="#clear">clear()</a>|Deletes all messages.|
+|<a href="#all">all()</a>|Returns all messages.|
+<hr>
+<div id='all'>
+<h4 class='heading'>
+hilbish.messages.all()
+<a href="#all" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns all messages.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='clear'>
+<h4 class='heading'>
+hilbish.messages.clear()
+<a href="#clear" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Deletes all messages.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='delete'>
+<h4 class='heading'>
+hilbish.messages.delete(idx)
+<a href="#delete" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Deletes the message at `idx`.
+#### Parameters
+`idx` **`number`**  
+
+
+</div>
+
+<hr>
+<div id='read'>
+<h4 class='heading'>
+hilbish.messages.read(idx)
+<a href="#read" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Marks a message at `idx` as read.
+#### Parameters
+`idx` **`number`**  
+
+
+</div>
+
+<hr>
+<div id='send'>
+<h4 class='heading'>
+hilbish.messages.send(message)
+<a href="#send" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sends a message.
+#### Parameters
+`message` **`hilbish.message`**  
+
+
+</div>
+
+<hr>
+<div id='readAll'>
+<h4 class='heading'>
+hilbish.messages.readAll()
+<a href="#readAll" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Marks all messages as read.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='unreadCount'>
+<h4 class='heading'>
+hilbish.messages.unreadCount()
+<a href="#unreadCount" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns the amount of unread messages.
+#### Parameters
+This function has no parameters.  
+</div>
+

docs/api/hilbish/hilbish.runner.md

@@ -57,6 +57,12 @@ end)
 |<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function.|
 |<a href="#runner.lua">lua(cmd)</a>|Evaluates `cmd` as Lua input. This is the same as using `dofile`|
 |<a href="#runner.sh">sh(cmd)</a>|Runs a command in Hilbish's shell script interpreter.|
+|<a href="#exec">exec(cmd, runnerName)</a>|Executes `cmd` with a runner.|
+|<a href="#set">set(name, runner)</a>|*Sets* a runner by name. The difference between this function and|
+|<a href="#get">get(name)</a>|Get a runner by name.|
+|<a href="#add">add(name, runner)</a>|Adds a runner to the table of available runners.|
+|<a href="#setCurrent">setCurrent(name)</a>|Sets Hilbish's runner mode by name.|
+|<a href="#getCurrent">getCurrent()</a>|Returns the current runner by name.|
 
 <hr>
 <div id='runner.setMode'>
@@ -114,3 +120,110 @@ This is the equivalent of using `source`.
 
 </div>
 
+<hr>
+<div id='getCurrent'>
+<h4 class='heading'>
+hilbish.runner.getCurrent()
+<a href="#getCurrent" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Returns the current runner by name.
+#### Parameters
+This function has no parameters.  
+</div>
+
+<hr>
+<div id='setCurrent'>
+<h4 class='heading'>
+hilbish.runner.setCurrent(name)
+<a href="#setCurrent" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Sets Hilbish's runner mode by name.
+#### Parameters
+`name` **`string`**  
+
+
+</div>
+
+<hr>
+<div id='add'>
+<h4 class='heading'>
+hilbish.runner.add(name, runner)
+<a href="#add" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Adds a runner to the table of available runners.
+If runner is a table, it must have the run function in it.
+#### Parameters
+`name` **`string`**  
+ Name of the runner
+
+`runner` **`function|table`**  
+ 
+
+</div>
+
+<hr>
+<div id='get'>
+<h4 class='heading'>
+hilbish.runner.get(name)
+<a href="#get" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Get a runner by name.
+#### Parameters
+`name` **`string`**  
+ Name of the runner to retrieve.
+
+</div>
+
+<hr>
+<div id='set'>
+<h4 class='heading'>
+hilbish.runner.set(name, runner)
+<a href="#set" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+*Sets* a runner by name. The difference between this function and
+add, is set will *not* check if the named runner exists.
+The runner table must have the run function in it.
+#### Parameters
+`name` **`string`**  
+
+
+`runner` **`table`**  
+
+
+</div>
+
+<hr>
+<div id='exec'>
+<h4 class='heading'>
+hilbish.runner.exec(cmd, runnerName)
+<a href="#exec" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Executes `cmd` with a runner.
+If `runnerName` is not specified, it uses the default Hilbish runner.
+#### Parameters
+`cmd` **`string`**  
+
+
+`runnerName` **`string?`**  
+
+
+</div>
+

docs/getting-started.md

@@ -53,8 +53,39 @@ 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`
 
-Now you can get to editing it. Since it's just a Lua file, having basic
+Now we can get to customization!
-knowledge of Lua would help. All of Lua's standard libraries and functions
+
-from Lua 5.4 are available. Hilbish has some custom and modules that are
+If we closely examine a small snippet of the default config:  
-available. To see them, you can run the `doc` command. This also works as
+```lua
-general documentation for other things.
+-- Default Hilbish config
+-- .. with some omitted code .. --
+
+local function doPrompt(fail)
+	hilbish.prompt(lunacolors.format(
+		'{blue}%u {cyan}%d ' .. (fail and '{red}' or '{green}') .. '∆ '
+	))
+end
+
+doPrompt()
+
+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.
+
+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. 
+
+We wrap this in the [`lunacolors.format`](../lunacolors) function, to give
+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.

docs/nature/dirs.md

@@ -1,12 +1,25 @@
 ---
 title: Module dirs
-description: No description.
+description: internal directory management
 layout: doc
 menu:
   docs:
     parent: "Nature"
 ---
 
+
+## Introduction
+The dirs module defines a small set of functions to store and manage
+directories.
+
+## Functions
+|||
+|----|----|
+|<a href="#recent">recent(idx)</a>|Get entry from recent directories list based on index.|
+|<a href="#pop">pop(num)</a>|Remove the specified amount of dirs from the recent directories list.|
+|<a href="#peak">peak(num)</a>|Look at `num` amount of recent directories, starting from the latest.|
+|<a href="#push">push(dir)</a>|Add `dir` to the recent directories list.|
+|<a href="#setOld">setOld(d)</a>|Sets the old directory string.|
 <hr>
 <div id='setOld'>
 <h4 class='heading'>
@@ -19,20 +32,24 @@ dirs.setOld(d)
 Sets the old directory string.
 #### Parameters
 `d` **`string`**  
+
+
 </div>
 
 <hr>
 <div id='push'>
 <h4 class='heading'>
-dirs.push()
+dirs.push(dir)
 <a href="#push" class='heading-link'>
 	<i class="fas fa-paperclip"></i>
 </a>
 </h4>
 
-Add `d` to the recent directories list.
+Add `dir` to the recent directories list.
 #### Parameters
-This function has no parameters.  
+`dir` **`string`**  
+
+
 </div>
 
 <hr>
@@ -45,8 +62,11 @@ dirs.peak(num)
 </h4>
 
 Look at `num` amount of recent directories, starting from the latest.
+This returns  a table of recent directories, up to the `num` amount.
 #### Parameters
 `num` **`number`**  
+
+
 </div>
 
 <hr>
@@ -61,6 +81,8 @@ dirs.pop(num)
 Remove the specified amount of dirs from the recent directories list.
 #### Parameters
 `num` **`number`**  
+
+
 </div>
 
 <hr>
@@ -75,5 +97,7 @@ dirs.recent(idx)
 Get entry from recent directories list based on index.
 #### Parameters
 `idx` **`number`**  
+
+
 </div>
 

docs/nature/doc.md

@@ -0,0 +1,76 @@
+---
+title: Module doc
+description: command-line doc rendering
+layout: doc
+menu:
+  docs:
+    parent: "Nature"
+---
+
+
+## Introduction
+The doc module contains a small set of functions
+used by the Greenhouse pager to render parts of the documentation pages.
+This is only documented for the sake of it. It's only intended use
+is by the Greenhouse pager.
+
+## Functions
+|||
+|----|----|
+|<a href="#renderCodeBlock">renderCodeBlock(text)</a>|Assembles and renders a code block. This returns|
+|<a href="#highlight">highlight(text)</a>|Performs basic Lua code highlighting.|
+|<a href="#renderInfoBlock">renderInfoBlock(type, text)</a>|Renders an info block. An info block is a block of text with|
+<hr>
+<div id='renderInfoBlock'>
+<h4 class='heading'>
+doc.renderInfoBlock(type, text)
+<a href="#renderInfoBlock" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Renders an info block. An info block is a block of text with
+an icon and styled text block.
+#### Parameters
+`type` **`string`**  
+ Type of info block. The only one specially styled is the `warning`.
+
+`text` **`string`**  
+
+
+</div>
+
+<hr>
+<div id='highlight'>
+<h4 class='heading'>
+doc.highlight(text)
+<a href="#highlight" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Performs basic Lua code highlighting.
+#### Parameters
+`text` **`string`**  
+ Code/text to do highlighting on.
+
+</div>
+
+<hr>
+<div id='renderCodeBlock'>
+<h4 class='heading'>
+doc.renderCodeBlock(text)
+<a href="#renderCodeBlock" class='heading-link'>
+	<i class="fas fa-paperclip"></i>
+</a>
+</h4>
+
+Assembles and renders a code block. This returns
+the supplied text based on the number of command line columns,
+and styles it to resemble a code block.
+#### Parameters
+`text` **`string`**  
+
+
+</div>
+

editor.go

@@ -48,7 +48,7 @@ func editorInsert(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 // #interface editor
 // setVimRegister(register, text)
 // Sets the vim register at `register` to hold the passed text.
-// #aram register string
+// #param register string
 // #param text string
 func editorSetRegister(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
@@ -109,8 +109,9 @@ func editorReadChar(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 }
 
 // #interface editor
-// deleteByAmount() -> string
+// deleteByAmount(amount)
-// Reads a keystroke from the user. This is in a format of something like Ctrl-L.
+// Deletes characters in the line by the given amount.
+// #param amount number
 func editorDeleteByAmount(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.Check1Arg(); err != nil {
 		return nil, err

emmyLuaDocs/hilbish.lua

@@ -13,6 +13,9 @@ function hilbish.aliases.add(alias, cmd) end
 --- as the higher level functions listed below this will handle it.
 function hilbish.runner.setMode(cb) end
 
+--- Deletes characters in the line by the given amount.
+function hilbish.editor.deleteByAmount(amount) end
+
 --- Returns the current input line.
 function hilbish.editor.getLine() end
 

nature/abbr.lua

@@ -1,24 +1,42 @@
+-- @module hilbish.abbr
+-- command line abbreviations
+-- The abbr module manages Hilbish abbreviations. These are words that can be replaced
+-- with longer command line strings when entered.
+-- As an example, `git push` can be abbreviated to `gp`. When the user types
+-- `gp` into the command line, after hitting space or enter, it will expand to `git push`.
+-- Abbreviations can be used as an alternative to aliases. They are saved entirely in the history
+-- Instead of the aliased form of the same command.
 local bait = require 'bait'
 local hilbish = require 'hilbish'
 hilbish.abbr = {
-	_abbrevs = {}
+	all = {}
 }
 
-function hilbish.abbr.add(opts)
-	hilbish.abbr._abbrevs[opts.abbr] = opts
-end
-
 print 'abbr loaded'
-hilbish.abbr.add {
-	abbr = 'tt',
-	expand = 'echo titties'
-}
 
-hilbish.abbr.add {
+--- Adds an abbreviation. The `abbr` is the abbreviation itself,
-	abbr = 'idk',
+--- while `expanded` is what the abbreviation should expand to.
-	expand = 'i dont know',
+--- It can be either a function or a string. If it is a function, it will expand to what
-	anywhere = true
+--- the function returns.
-}
+--- `opts` is a table that accepts 1 key: `anywhere`.
+--- `opts.anywhere` defines whether the abbr expands anywhere in the command line or not,
+--- whereas the default behavior is only at the beginning of the line
+-- @param abbr string
+-- @param expanded|function string
+-- @param opts table
+function hilbish.abbr.add(abbr, expanded, opts)
+	print(abbr, expanded, opts)
+	opts = opts or {}
+	opts.abbr = abbr
+	opts.expand = expanded
+	hilbish.abbr.all[abbr] = opts
+end
+
+--- Removes the named `abbr`.
+-- @param abbr string
+function hilbish.abbr.remove(abbr)
+	hilbish.abbr.all[abbr] = nil
+end
 
 bait.catch('hilbish.rawInput', function(c)
 	-- 0x0d == enter
@@ -26,11 +44,29 @@ bait.catch('hilbish.rawInput', function(c)
 		-- check if the last "word" was a valid abbreviation
 		local line = hilbish.editor.getLine()
 		local lineSplits = string.split(line, ' ')
-		local thisAbbr = hilbish.abbr._abbrevs[lineSplits[#lineSplits]]
+		local thisAbbr = hilbish.abbr.all[lineSplits[#lineSplits]]
 
 		if thisAbbr and (#lineSplits == 1 or thisAbbr.anywhere == true) then
 			hilbish.editor.deleteByAmount(-lineSplits[#lineSplits]:len())
+			if type(thisAbbr.expand) == 'string' then
 				hilbish.editor.insert(thisAbbr.expand)
+			elseif type(thisAbbr.expand) == 'function' then
+				local expandRet = thisAbbr.expand()
+				if type(expandRet) ~= 'string' then
+					print(string.format('abbr %s has an expand function that did not return a string. instead it returned: %s', thisAbbr.abbr, expandRet))
+				end
+				hilbish.editor.insert(expandRet)
+			end
 		end
 	end
 end)
+
+hilbish.abbr.add('tt', 'echo titties')
+
+hilbish.abbr.add('idk', 'i dont know', {
+	anywhere = true
+})
+
+hilbish.abbr.add('!!', function()
+	return hilbish.history.get(hilbish.history.size() - 1)
+end)

nature/dirs.lua

@@ -1,10 +1,12 @@
 -- @module dirs
+-- internal directory management
+-- The dirs module defines a small set of functions to store and manage
+-- directories.
 local fs = require 'fs'
 
 local dirs = {}
 
---- Last (current working) directory. Separate from recentDirs mainly for
+--- Last (current working) directory. Separate from recentDirs mainly for easier use.
---- easier use.
 dirs.old = ''
 --- Table of recent directories. For use, look at public functions.
 dirs.recentDirs = {}
@@ -35,13 +37,15 @@ function dirRecents(num, remove)
 end
 
 --- Look at `num` amount of recent directories, starting from the latest.
+--- This returns  a table of recent directories, up to the `num` amount.
 -- @param num? number
 function dirs.peak(num)
 	return dirRecents(num)
 end
 
---- Add `d` to the recent directories list.
+--- Add `dir` to the recent directories list.
-function dirs.push(d)
+--- @param dir string
+function dirs.push(dir)
 	dirs.recentDirs[dirs.recentSize + 1] = nil
 	if dirs.recentDirs[#dirs.recentDirs - 1] ~= d then
 		ok, d = pcall(fs.abs, d)

nature/doc.lua

@@ -1,13 +1,25 @@
+-- @module doc
+-- command-line doc rendering
+-- The doc module contains a small set of functions
+-- used by the Greenhouse pager to render parts of the documentation pages.
+-- This is only documented for the sake of it. It's only intended use
+-- is by the Greenhouse pager.
 local lunacolors = require 'lunacolors'
 
-local M = {}
+local doc = {}
 
-function M.highlight(text)
+--- Performs basic Lua code highlighting.
+--- @param text string Code/text to do highlighting on.
+function doc.highlight(text)
 	return text:gsub('\'.-\'', lunacolors.yellow)
 	--:gsub('%-%- .-', lunacolors.black)
 end
 
-function M.renderCodeBlock(text)
+--- Assembles and renders a code block. This returns
+--- the supplied text based on the number of command line columns,
+--- and styles it to resemble a code block.
+--- @param text string
+function doc.renderCodeBlock(text)
 	local longest = 0
 	local lines = string.split(text:gsub('\t', '    '), '\n')
 
@@ -17,14 +29,18 @@ function M.renderCodeBlock(text)
 	end
 
 	for i, line in ipairs(lines) do
-		lines[i] = lunacolors.format('{greyBg}' .. ' ' .. M.highlight(line:sub(0, longest))
+		lines[i] = lunacolors.format('{greyBg}' .. ' ' .. doc.highlight(line:sub(0, longest))
 		.. string.rep(' ', longest - line:len()) .. ' ')
 	end
 
 	return '\n' .. lunacolors.format('{greyBg}' .. table.concat(lines, '\n')) .. '\n'
 end
 
-function M.renderInfoBlock(type, text)
+--- Renders an info block. An info block is a block of text with
+--- an icon and styled text block.
+--- @param type string Type of info block. The only one specially styled is the `warning`.
+--- @param text string
+function doc.renderInfoBlock(type, text)
 	local longest = 0
 	local lines = string.split(text:gsub('\t', '    '), '\n')
 
@@ -34,7 +50,7 @@ function M.renderInfoBlock(type, text)
 	end
 
 	for i, line in ipairs(lines) do
-		lines[i] = ' ' .. M.highlight(line:sub(0, longest))
+		lines[i] = ' ' .. doc.highlight(line:sub(0, longest))
 		.. string.rep(' ', longest - line:len()) .. ' '
 	end
 
@@ -44,4 +60,4 @@ function M.renderInfoBlock(type, text)
 	end
 	return '\n' .. heading .. '\n' .. lunacolors.format('{greyBg}' .. table.concat(lines, '\n')) .. '\n'
 end
-return M
+return doc

nature/greenhouse/init.lua

@@ -1,4 +1,5 @@
--- Greenhouse is a simple text scrolling handler for terminal programs.
+-- @module greenhouse
+-- Greenhouse is a simple text scrolling handler (pager) for terminal programs.
 -- The idea is that it can be set a region to do its scrolling and paging
 -- job and then the user can draw whatever outside it.
 -- This reduces code duplication for the message viewer

nature/greenhouse/page.lua

@@ -1,3 +1,4 @@
+-- @module greenhouse.page
 local Object = require 'nature.object'
 
 local Page = Object:extend()
@@ -10,6 +11,7 @@ function Page:new(title, text)
 	self.children = {}
 end
 
+
 function Page:setText(text)
 	self.lines = string.split(text, '\n')
 end

nature/hummingbird.lua

@@ -1,3 +1,14 @@
+-- @module hilbish.messages
+-- simplistic message passing
+-- The messages interface defines a way for Hilbish-integrated commands,
+-- user config and other tasks to send notifications to alert the user.z
+-- The `hilbish.message` type is a table with the following keys:
+-- `title` (string): A title for the message notification.
+-- `text` (string): The contents of the message.
+-- `channel` (string): States the origin of the message, `hilbish.*` is reserved for Hilbish tasks.
+-- `summary` (string): A short summary of the `text`.
+-- `icon` (string): Unicode (preferably standard emoji) icon for the message notification
+-- `read` (boolean): Whether the full message has been read or not.
 local bait = require 'bait'
 local commander = require 'commander'
 local lunacolors = require 'lunacolors'
@@ -44,6 +55,8 @@ function hilbish.messages.send(message)
 	bait.throw('hilbish.notification', message)
 end
 
+--- Marks a message at `idx` as read.
+--- @param idx number
 function hilbish.messages.read(idx)
 	local msg = M._messages[idx]
 	if msg then 
@@ -52,16 +65,20 @@ function hilbish.messages.read(idx)
 	end
 end
 
-function hilbish.messages.readAll(idx)
+--- Marks all messages as read.
+function hilbish.messages.readAll()
 	for _, msg in ipairs(hilbish.messages.all()) do
 		hilbish.messages.read(msg.index)
 	end
 end
 
+--- Returns the amount of unread messages.
 function hilbish.messages.unreadCount()
 	return unread
 end
 
+--- Deletes the message at `idx`.
+--- @param idx number
 function hilbish.messages.delete(idx)
 	local msg = M._messages[idx]
 	if not msg then
@@ -71,12 +88,14 @@ function hilbish.messages.delete(idx)
 	M._messages[idx] = nil
 end
 
+--- Deletes all messages.
 function hilbish.messages.clear()
 	for _, msg in ipairs(hilbish.messages.all()) do
 		hilbish.messages.delete(msg.index)
 	end
 end
 
+--- Returns all messages.
 function hilbish.messages.all()
 	return M._messages
 end

nature/opts/motd.lua

@@ -2,9 +2,7 @@ local bait = require 'bait'
 local lunacolors = require 'lunacolors'
 
 hilbish.motd = [[
-Wait ... {magenta}2.3{reset} is basically the same as {red}2.2?{reset}
+{magenta}Hilbish{reset} blooms in the {blue}midnight.{reset}
-Erm.. {blue}Ctrl-C works for Commanders,{reset} {cyan}and the sh runner has some fixes.{reset}
-Just trust me bro, this is an important bug fix release. {red}- 🌺 sammyette{reset}
 ]]
 
 bait.catch('hilbish.init', function()

nature/runner.lua

@@ -1,4 +1,4 @@
---- hilbish.runner
+-- @module hilbish.runner
 local currentRunner = 'hybrid'
 local runners = {}
 
@@ -6,7 +6,7 @@ local runners = {}
 hilbish = hilbish
 
 --- Get a runner by name.
---- @param name string
+--- @param name string Name of the runner to retrieve.
 --- @return table
 function hilbish.runner.get(name)
 	local r = runners[name]
@@ -18,9 +18,9 @@ function hilbish.runner.get(name)
 	return r
 end
 
---- Adds a runner to the table of available runners. If runner is a table,
+--- Adds a runner to the table of available runners.
---- it must have the run function in it.
+--- If runner is a table, it must have the run function in it.
---- @param name string
+--- @param name string Name of the runner
 --- @param runner function|table 
 function hilbish.runner.add(name, runner)
 	if type(name) ~= 'string' then
@@ -42,7 +42,9 @@ function hilbish.runner.add(name, runner)
 	hilbish.runner.set(name, runner)
 end
 
---- Sets a runner by name. The runner table must have the run function in it.
+--- *Sets* a runner by name. The difference between this function and
+--- add, is set will *not* check if the named runner exists.
+--- The runner table must have the run function in it.
 --- @param name string
 --- @param runner table
 function hilbish.runner.set(name, runner)
@@ -53,11 +55,11 @@ function hilbish.runner.set(name, runner)
 	runners[name] = runner
 end
 
---- Executes cmd with a runner. If runnerName isn't passed, it uses
+--- Executes `cmd` with a runner.
---- the user's current runner.
+--- If `runnerName` is not specified, it uses the default Hilbish runner.
 --- @param cmd string
 --- @param runnerName string?
---- @return string, number, string
+--- @return table
 function hilbish.runner.exec(cmd, runnerName)
 	if not runnerName then runnerName = currentRunner end
 
@@ -66,7 +68,7 @@ function hilbish.runner.exec(cmd, runnerName)
 	return r.run(cmd)
 end
 
---- Sets the current interactive/command line runner mode.
+--- Sets Hilbish's runner mode by name.
 --- @param name string
 function hilbish.runner.setCurrent(name)
 	local r = hilbish.runner.get(name)