diff --git a/docs/api/hilbish/hilbish.messages.md b/docs/api/hilbish/hilbish.messages.md index 4c72d3a..fc33a22 100644 --- a/docs/api/hilbish/hilbish.messages.md +++ b/docs/api/hilbish/hilbish.messages.md @@ -1316,3 +1316,211 @@ hilbish.messages.unreadCount() This function has no parameters. +
+
+

+hilbish.messages.all() + + + +

+ +Returns all messages. +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.messages.clear() + + + +

+ +Deletes all messages. +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.messages.delete(idx) + + + +

+ +Deletes the message at `idx`. +#### Parameters +`idx` **`number`** + + +
+ +
+
+

+hilbish.messages.read(idx) + + + +

+ +Marks a message at `idx` as read. +#### Parameters +`idx` **`number`** + + +
+ +
+
+

+hilbish.messages.send(message) + + + +

+ +Sends a message. +#### Parameters +`message` **`hilbish.message`** + + +
+ +
+
+

+hilbish.messages.readAll() + + + +

+ +Marks all messages as read. +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.messages.unreadCount() + + + +

+ +Returns the amount of unread messages. +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.messages.all() + + + +

+ +Returns all messages. +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.messages.clear() + + + +

+ +Deletes all messages. +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.messages.delete(idx) + + + +

+ +Deletes the message at `idx`. +#### Parameters +`idx` **`number`** + + +
+ +
+
+

+hilbish.messages.read(idx) + + + +

+ +Marks a message at `idx` as read. +#### Parameters +`idx` **`number`** + + +
+ +
+
+

+hilbish.messages.send(message) + + + +

+ +Sends a message. +#### Parameters +`message` **`hilbish.message`** + + +
+ +
+
+

+hilbish.messages.readAll() + + + +

+ +Marks all messages as read. +#### Parameters +This function has no parameters. +
+ +
+
+

+hilbish.messages.unreadCount() + + + +

+ +Returns the amount of unread messages. +#### Parameters +This function has no parameters. +
+ diff --git a/docs/api/hilbish/hilbish.runner.md b/docs/api/hilbish/hilbish.runner.md index 8666c16..c4cfbe4 100644 --- a/docs/api/hilbish/hilbish.runner.md +++ b/docs/api/hilbish/hilbish.runner.md @@ -57,11 +57,11 @@ end) |setMode(cb)|This is the same as the `hilbish.runnerMode` function.| |lua(cmd)|Evaluates `cmd` as Lua input. This is the same as using `dofile`| |sh(cmd)|Runs a command in Hilbish's shell script interpreter.| -|exec(cmd, runnerName)|Executes cmd with a runner. If runnerName isn't passed, it uses| -|set(name, runner)|Sets a runner by name. The runner table must have the run function in it.| +|exec(cmd, runnerName)|Executes `cmd` with a runner.| +|set(name, runner)|*Sets* a runner by name. The difference between this function and| |get(name)|Get a runner by name.| -|add(name, runner)|Adds a runner to the table of available runners. If runner is a table,| -|setCurrent(name)|Sets the current interactive/command line runner mode.| +|add(name, runner)|Adds a runner to the table of available runners.| +|setCurrent(name)|Sets Hilbish's runner mode by name.| |getCurrent()|Returns the current runner by name.|
@@ -143,7 +143,7 @@ hilbish.runner.setCurrent(name) -Sets the current interactive/command line runner mode. +Sets Hilbish's runner mode by name. #### Parameters `name` **`string`** @@ -159,14 +159,14 @@ hilbish.runner.add(name, runner) -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. @@ -195,7 +195,9 @@ hilbish.runner.set(name, runner) -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) -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`** diff --git a/docs/nature/dirs.md b/docs/nature/dirs.md index b658c98..8b52f8a 100644 --- a/docs/nature/dirs.md +++ b/docs/nature/dirs.md @@ -26,15 +26,17 @@ Sets the old directory string.

-dirs.push() +dirs.push(dir)

-Add `d` to the recent directories list. +Add `dir` to the recent directories list. #### Parameters -This function has no parameters. +`dir` **`string`** + +
@@ -47,6 +49,7 @@ dirs.peak(num) 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`** diff --git a/docs/nature/doc.md b/docs/nature/doc.md new file mode 100644 index 0000000..b508240 --- /dev/null +++ b/docs/nature/doc.md @@ -0,0 +1,63 @@ +--- +title: Module doc +description: No description. +layout: doc +menu: + docs: + parent: "Nature" +--- + +
+
+

+doc.renderInfoBlock(type, text) + + + +

+ +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`** + + +
+ +
+
+

+doc.highlight(text) + + + +

+ +Performs basic Lua code highlighting. +#### Parameters +`text` **`string`** + Code/text to do highlighting on. + +
+ +
+
+

+doc.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. +#### Parameters +`text` **`string`** + + +
+ diff --git a/nature/dirs.lua b/nature/dirs.lua index 328b4b7..9c5f645 100644 --- a/nature/dirs.lua +++ b/nature/dirs.lua @@ -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) diff --git a/nature/doc.lua b/nature/doc.lua index f0b7e11..a21312a 100644 --- a/nature/doc.lua +++ b/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 diff --git a/nature/greenhouse/init.lua b/nature/greenhouse/init.lua index fe4c31c..2badfae 100644 --- a/nature/greenhouse/init.lua +++ b/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 diff --git a/nature/greenhouse/page.lua b/nature/greenhouse/page.lua index 51d1440..185ef61 100644 --- a/nature/greenhouse/page.lua +++ b/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 diff --git a/nature/hummingbird.lua b/nature/hummingbird.lua index 058353d..88cb88f 100644 --- a/nature/hummingbird.lua +++ b/nature/hummingbird.lua @@ -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 diff --git a/nature/runner.lua b/nature/runner.lua index 8e3dfb8..86c2ad9 100644 --- a/nature/runner.lua +++ b/nature/runner.lua @@ -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,10 +18,10 @@ 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 ---- @param runner function|table +--- 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 error 'expected runner name to be a table' @@ -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)