sammyette/Hilbish
2
3
Fork 0
mirror of https://github.com/sammy-ette/Hilbish synced 2025-08-10 02:52:03 +00:00
Code Issues Releases Wiki Activity

fix: make lua implemented hilbish interfaces documented (#335)

Browse Source 
* fix: make lua implemented hilbish interfaces documented

* fix: signature link in table of contents

* fix: reduce function list to match in go generated docs

* fix: toc appending

* docs: enable docs for hilbish.messages

* feat: add description gen, and more spacing between param listing

* docs: add more detailed documentation for lua modules

* docs: update hilbish.messages docs

* fix: add description for lua doc'd modules, remove duplicate docs

* docs: add back hilbish.jobs doc

* feat: generate toc for lua modules

* fix: add table heading

* ci: add lua docgen

* docs: put dirs.old doc on 1 line
This commit is contained in:
sammyette 2025-04-02 09:41:37 -04:00 committed by GitHub
parent 32ed0d2348
commit 4150001d8b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 532 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
.github/workflows/docs.yml vendored
View File

@ -11,8 +11,14 @@ jobs:
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- uses: actions/setup-go@v5 - 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 run: go run cmd/docgen/docgen.go
- name: Run docgen (lua-written)
run: ./hilbish cmd/docgen/docgen.lua
- name: Commit new docs - name: Commit new docs
uses: stefanzweifel/git-auto-commit-action@v4 uses: stefanzweifel/git-auto-commit-action@v4
with: with:

18
cmd/docgen/docgen.go
View File

@ -299,7 +299,25 @@ start:
func main() { func main() {
fset := token.NewFileSet() fset := token.NewFileSet()
os.Mkdir("docs", 0777) os.Mkdir("docs", 0777)
os.RemoveAll("docs/api")
os.Mkdir("docs/api", 0777) 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) os.Mkdir("emmyLuaDocs", 0777)
dirs := []string{"./"} dirs := []string{"./"}

88
cmd/docgen/docgen.lua
View File

@ -1,7 +1,9 @@
local fs = require 'fs' local fs = require 'fs'
local emmyPattern = '^%-%-%- (.+)' local emmyPattern = '^%-%-%- (.+)'
local modpattern = '^%-+ @module (%w+)' local emmyPattern2 = '^%-%- (.+)'
local modpattern = '^%-+ @module (.+)'
local pieces = {} local pieces = {}
local descriptions = {}
local files = fs.readdir 'nature' local files = fs.readdir 'nature'
for _, fname in ipairs(files) do for _, fname in ipairs(files) do
@ -15,16 +17,24 @@ for _, fname in ipairs(files) do
print(fname, mod) print(fname, mod)
pieces[mod] = {} pieces[mod] = {}
descriptions[mod] = {}
local docPiece = {} local docPiece = {}
local lines = {} local lines = {}
local lineno = 0 local lineno = 0
local doingDescription = true
for line in f:lines() do for line in f:lines() do
lineno = lineno + 1 lineno = lineno + 1
lines[lineno] = line lines[lineno] = line
if line == header then goto continue2 end 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 if line:match '^function' then
local pattern = (string.format('^function %s%%.', mod) .. '(%w+)') local pattern = (string.format('^function %s%%.', mod) .. '(%w+)')
local funcName = line:match(pattern) local funcName = line:match(pattern)
@ -49,10 +59,14 @@ for _, fname in ipairs(files) do
if emmy then if emmy then
if emmy == 'param' then if emmy == 'param' then
print('bruh', emmythings[1], emmythings[2])
table.insert(dps.params, 1, { table.insert(dps.params, 1, {
name = emmythings[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 end
else else
table.insert(dps.description, 1, docline) table.insert(dps.description, 1, docline)
@ -81,29 +95,78 @@ description: %s
layout: doc layout: doc
menu: menu:
docs: docs:
parent: "Nature" parent: "%s"
--- ---
]] ]]
for iface, dps in pairs(pieces) do for iface, dps in pairs(pieces) do
local mod = iface:match '(%w+)%.' or 'nature' 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) 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(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 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 sig = string.format('%s.%s(', iface, func)
local params = ''
for idx, param in ipairs(docs.params) do 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 end
sig = sig .. ')' 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([[ f:write(string.format([[
<h4 class='heading'> <h4 class='heading'>
%s %s
@ -120,7 +183,8 @@ for iface, dps in pairs(pieces) do
f:write 'This function has no parameters. \n' f:write 'This function has no parameters. \n'
end end
for _, param in ipairs(docs.params) do for _, param in ipairs(docs.params) do
f:write(string.format('`%s` **`%s`**\n', param.name:gsub('%?$', ''), param.type)) f:write(string.format('`%s` **`%s`** \n', param.name:gsub('%?$', ''), param.type))
f:write(string.format('%s\n\n', param.description))
end end
--[[ --[[
local params = table.filter(docs, function(t) local params = table.filter(docs, function(t)

135
docs/api/hilbish/hilbish.messages.md Normal file
View File

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

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

@ -57,6 +57,12 @@ end)
|<a href="#runner.setMode">setMode(cb)</a>|This is the same as the `hilbish.runnerMode` function.| |<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.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="#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> <hr>
<div id='runner.setMode'> <div id='runner.setMode'>
@ -114,3 +120,110 @@ This is the equivalent of using `source`.
</div> </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>

32
docs/nature/dirs.md
View File

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

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

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

12
nature/dirs.lua
View File

@ -1,10 +1,12 @@
-- @module dirs -- @module dirs
-- internal directory management
-- The dirs module defines a small set of functions to store and manage
-- directories.
local fs = require 'fs' local fs = require 'fs'
local dirs = {} 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 = '' dirs.old = ''
--- Table of recent directories. For use, look at public functions. --- Table of recent directories. For use, look at public functions.
dirs.recentDirs = {} dirs.recentDirs = {}
@ -35,13 +37,15 @@ function dirRecents(num, remove)
end end
--- Look at `num` amount of recent directories, starting from the latest. --- 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 -- @param num? number
function dirs.peak(num) function dirs.peak(num)
return dirRecents(num) return dirRecents(num)
end 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 dirs.recentDirs[dirs.recentSize + 1] = nil
if dirs.recentDirs[#dirs.recentDirs - 1] ~= d then if dirs.recentDirs[#dirs.recentDirs - 1] ~= d then
ok, d = pcall(fs.abs, d) 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 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) return text:gsub('\'.-\'', lunacolors.yellow)
--:gsub('%-%- .-', lunacolors.black) --:gsub('%-%- .-', lunacolors.black)
end 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 longest = 0
local lines = string.split(text:gsub('\t', ' '), '\n') local lines = string.split(text:gsub('\t', ' '), '\n')
@ -17,14 +29,18 @@ function M.renderCodeBlock(text)
end end
for i, line in ipairs(lines) do 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()) .. ' ') .. string.rep(' ', longest - line:len()) .. ' ')
end end
return '\n' .. lunacolors.format('{greyBg}' .. table.concat(lines, '\n')) .. '\n' return '\n' .. lunacolors.format('{greyBg}' .. table.concat(lines, '\n')) .. '\n'
end 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 longest = 0
local lines = string.split(text:gsub('\t', ' '), '\n') local lines = string.split(text:gsub('\t', ' '), '\n')
@ -34,7 +50,7 @@ function M.renderInfoBlock(type, text)
end end
for i, line in ipairs(lines) do 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()) .. ' ' .. string.rep(' ', longest - line:len()) .. ' '
end end
@ -44,4 +60,4 @@ function M.renderInfoBlock(type, text)
end end
return '\n' .. heading .. '\n' .. lunacolors.format('{greyBg}' .. table.concat(lines, '\n')) .. '\n' return '\n' .. heading .. '\n' .. lunacolors.format('{greyBg}' .. table.concat(lines, '\n')) .. '\n'
end 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 -- 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. -- job and then the user can draw whatever outside it.
-- This reduces code duplication for the message viewer -- 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 Object = require 'nature.object'
local Page = Object:extend() local Page = Object:extend()
@ -10,6 +11,7 @@ function Page:new(title, text)
self.children = {} self.children = {}
end end
function Page:setText(text) function Page:setText(text)
self.lines = string.split(text, '\n') self.lines = string.split(text, '\n')
end end

21
nature/hummingbird.lua
View File

@ -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 bait = require 'bait'
local commander = require 'commander' local commander = require 'commander'
local lunacolors = require 'lunacolors' local lunacolors = require 'lunacolors'
@ -44,6 +55,8 @@ function hilbish.messages.send(message)
bait.throw('hilbish.notification', message) bait.throw('hilbish.notification', message)
end end
--- Marks a message at `idx` as read.
--- @param idx number
function hilbish.messages.read(idx) function hilbish.messages.read(idx)
local msg = M._messages[idx] local msg = M._messages[idx]
if msg then if msg then
@ -52,16 +65,20 @@ function hilbish.messages.read(idx)
end end
end end
function hilbish.messages.readAll(idx) --- Marks all messages as read.
function hilbish.messages.readAll()
for _, msg in ipairs(hilbish.messages.all()) do for _, msg in ipairs(hilbish.messages.all()) do
hilbish.messages.read(msg.index) hilbish.messages.read(msg.index)
end end
end end
--- Returns the amount of unread messages.
function hilbish.messages.unreadCount() function hilbish.messages.unreadCount()
return unread return unread
end end
--- Deletes the message at `idx`.
--- @param idx number
function hilbish.messages.delete(idx) function hilbish.messages.delete(idx)
local msg = M._messages[idx] local msg = M._messages[idx]
if not msg then if not msg then
@ -71,12 +88,14 @@ function hilbish.messages.delete(idx)
M._messages[idx] = nil M._messages[idx] = nil
end end
--- Deletes all messages.
function hilbish.messages.clear() function hilbish.messages.clear()
for _, msg in ipairs(hilbish.messages.all()) do for _, msg in ipairs(hilbish.messages.all()) do
hilbish.messages.delete(msg.index) hilbish.messages.delete(msg.index)
end end
end end
--- Returns all messages.
function hilbish.messages.all() function hilbish.messages.all()
return M._messages return M._messages
end end

24
nature/runner.lua
View File

@ -1,4 +1,4 @@
--- hilbish.runner -- @module hilbish.runner
local currentRunner = 'hybrid' local currentRunner = 'hybrid'
local runners = {} local runners = {}
@ -6,7 +6,7 @@ local runners = {}
hilbish = hilbish hilbish = hilbish
--- Get a runner by name. --- Get a runner by name.
--- @param name string --- @param name string Name of the runner to retrieve.
--- @return table --- @return table
function hilbish.runner.get(name) function hilbish.runner.get(name)
local r = runners[name] local r = runners[name]
@ -18,10 +18,10 @@ function hilbish.runner.get(name)
return r return r
end 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 --- @param runner function|table
function hilbish.runner.add(name, runner) function hilbish.runner.add(name, runner)
if type(name) ~= 'string' then if type(name) ~= 'string' then
error 'expected runner name to be a table' error 'expected runner name to be a table'
@ -42,7 +42,9 @@ function hilbish.runner.add(name, runner)
hilbish.runner.set(name, runner) hilbish.runner.set(name, runner)
end 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 name string
--- @param runner table --- @param runner table
function hilbish.runner.set(name, runner) function hilbish.runner.set(name, runner)
@ -53,11 +55,11 @@ function hilbish.runner.set(name, runner)
runners[name] = runner runners[name] = runner
end 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 cmd string
--- @param runnerName string? --- @param runnerName string?
--- @return string, number, string --- @return table
function hilbish.runner.exec(cmd, runnerName) function hilbish.runner.exec(cmd, runnerName)
if not runnerName then runnerName = currentRunner end if not runnerName then runnerName = currentRunner end
@ -66,7 +68,7 @@ function hilbish.runner.exec(cmd, runnerName)
return r.run(cmd) return r.run(cmd)
end end
--- Sets the current interactive/command line runner mode. --- Sets Hilbish's runner mode by name.
--- @param name string --- @param name string
function hilbish.runner.setCurrent(name) function hilbish.runner.setCurrent(name)
local r = hilbish.runner.get(name) local r = hilbish.runner.get(name)