sammyette/Hilbish
2
2
Fork 0
mirror of https://github.com/Hilbis/Hilbish synced 2025-04-20 20:43:23 +00:00
Code Issues Releases Wiki Activity

docs: add more detailed documentation for lua modules

Browse Source
This commit is contained in:
sammyette 2025-03-18 09:37:35 -04:00
parent 2e9925ef2a
commit 56f9954f97
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
10 changed files with 355 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

208
docs/api/hilbish/hilbish.messages.md
View File

@ -1316,3 +1316,211 @@ hilbish.messages.unreadCount()
This function has no parameters.
</div>
<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>
<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>

26
docs/api/hilbish/hilbish.runner.md
View File

@ -57,11 +57,11 @@ 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. If runnerName isn't passed, it uses|
|<a href="#set">set(name, runner)</a>|Sets a runner by name. The runner table must have the run function in it.|
|<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. If runner is a table,|
|<a href="#setCurrent">setCurrent(name)</a>|Sets the current interactive/command line runner mode.|
|<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>
@ -143,7 +143,7 @@ hilbish.runner.setCurrent(name)
</a>
</h4>
Sets the current interactive/command line runner mode.
Sets Hilbish's runner mode by name.
#### Parameters
`name` **`string`**
@ -159,11 +159,11 @@ hilbish.runner.add(name, runner)
</a>
</h4>
Adds a runner to the table of available runners. If runner is a table,
it must have the run function in it.
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`**
@ -182,7 +182,7 @@ hilbish.runner.get(name)
Get a runner by name.
#### Parameters
`name` **`string`**
Name of the runner to retrieve.
</div>
@ -195,7 +195,9 @@ hilbish.runner.set(name, runner)
</a>
</h4>
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.
#### Parameters
`name` **`string`**
@ -214,8 +216,8 @@ hilbish.runner.exec(cmd, runnerName)
</a>
</h4>
Executes cmd with a runner. If runnerName isn't passed, it uses
the user's current runner.
Executes `cmd` with a runner.
If `runnerName` is not specified, it uses the default Hilbish runner.
#### Parameters
`cmd` **`string`**

9
docs/nature/dirs.md
View File

@ -26,15 +26,17 @@ Sets the old directory string.
<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>
@ -47,6 +49,7 @@ 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`**

63
docs/nature/doc.md Normal file
View File

@ -0,0 +1,63 @@
---
title: Module doc
description: No description.
layout: doc
menu:
docs:
parent: "Nature"
---
<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>

9
nature/dirs.lua
View File

@ -1,4 +1,7 @@
-- @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 = {}
@ -35,13 +38,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.
function dirs.push(d)
--- Add `dir` to the recent directories list.
--- @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)

30
nature/doc.lua
View File

@ -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

3
nature/greenhouse/init.lua
View File

@ -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

2
nature/greenhouse/page.lua
View File

@ -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

17
nature/hummingbird.lua
View File

@ -1,4 +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'
@ -45,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
@ -53,17 +65,20 @@ function hilbish.messages.read(idx)
end
end
--- 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
@ -73,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

20
nature/runner.lua
View File

@ -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,
--- it must have the run function in it.
--- @param name string
--- Adds a runner to the table of available runners.
--- If runner is a table, it must have the run function in it.
--- @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
--- the user's current runner.
--- Executes `cmd` with a 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)