diff --git a/README.md b/README.md
index 1b741dd..39c0c7e 100644
--- a/README.md
+++ b/README.md
@@ -262,6 +262,175 @@ source code. You are encouraged to hack around with that.
+
+
+## Commands
+
+
+
+Fidget exposes some of its Lua API functions through `:Fidget` sub-commands
+(e.g., `:Fidget clear`), which support shell-like arguments and completion.
+These sub-commands are documented below.
+
+
+
+### `:Fidget` sub-commands
+
+#### `:Fidget clear`
+
+Clear active notifications
+
+
+ Command arguments
+
+Positional arguments:
+
+ - `{group_key}`: `(any)` group to clear
+
+
+
+
+#### `:Fidget lsp_suppress`
+
+Suppress LSP progress notifications
+
+
+ Command arguments
+
+Positional arguments:
+
+ - `{suppress}`: `(boolean)` whether to suppress (omitting this argument toggles suppression)
+
+
+
+
+#### `:Fidget clear_history`
+
+Clear notifications history
+
+
+ Command arguments
+
+Flags:
+
+ - `--include_active {true|false}`: `(boolean)` whether to clear items that have not been removed (default: true)
+ - `--group_key {group_key}`: `(any)` clear history by group key
+ - `--include_removed {true|false}`: `(boolean)` whether to clear items that have have been removed (default: true)
+ - `--since {since}`: `(number)` clear history of items updated at most this long ago
+ - `--before {before}`: `(number)` clear history of items updated at least this long ago
+
+Positional arguments:
+
+ - `{group_key}`: `(any)` clear history by group key
+
+
+
+
+#### `:Fidget suppress`
+
+Suppress notification window
+
+
+ Command arguments
+
+Positional arguments:
+
+ - `{suppress}`: `(boolean)` whether to suppress (omitting this argument toggles suppression)
+
+
+
+
+#### `:Fidget history`
+
+Show notifications history
+
+
+ Command arguments
+
+Flags:
+
+ - `--include_active {true|false}`: `(boolean)` whether to clear items that have not been removed (default: `true`)
+ - `--group_key {group_key}`: `(any)` filter history by group key
+ - `--include_removed {true|false}`: `(boolean)` whether to clear items that have have been removed (default: `true`)
+ - `--since {since}`: `(number)` filter history for items updated at most this long ago
+ - `--before {before}`: `(number)` filter history for items updated at least this long ago
+
+Positional arguments:
+
+ - `{group_key}`: `(any)` filter history by group key
+
+
+
+
+
+
+
+
+
+
## Highlights
Rather than defining its own highlights, Fidget's default configuration uses
diff --git a/doc/fidget.txt b/doc/fidget.txt
index 961b962..9d802cd 100644
--- a/doc/fidget.txt
+++ b/doc/fidget.txt
@@ -1,4 +1,4 @@
-*fidget.txt* Extensible UI for Neovim notifications and LSP progress messages.
+*fidget.txt* For Last change: 2023 December 25
==============================================================================
Table of Contents *fidget-table-of-contents*
@@ -9,8 +9,9 @@ Table of Contents *fidget-table-of-contents*
- Versioning |fidget-getting-started-versioning|
2. Options |fidget-options|
3. Lua API |fidget-lua-api|
-4. Highlights |fidget-highlights|
-5. Related Work |fidget-related-work|
+4. Commands |fidget-commands|
+5. Highlights |fidget-highlights|
+6. Related Work |fidget-related-work|
- Acknowledgements |fidget-related-work-acknowledgements|
==============================================================================
@@ -93,6 +94,9 @@ For instance, using Lazy
==============================================================================
2. Options *fidget-options*
+Fidgetcan be configured by passing a table of options to the `setup()`.
+Available options are shown below:
+
>lua
{
-- Options related to LSP progress subsystem
@@ -192,7 +196,7 @@ For instance, using Lazy
}
<
-Formore details, see |fidget-option.txt|.
+For more details, see |fidget-option.txt|.
==============================================================================
@@ -202,16 +206,84 @@ See |fidget-api.txt|.
==============================================================================
-4. Highlights *fidget-highlights*
+4. Commands *fidget-commands*
+
+*fidget-:Fidget* *:Fidget*
+
+Fidget exposes some of its Lua API functions through `:Fidget` sub-commands
+(e.g., `:Fidget clear`), which support shell-like arguments and completion.
+These sub-commands are documented below.
+
+:Fidget clear *fidget-:Fidget-clear*
+
+ Clear active notifications
+
+ Positional arguments: ~
+ {group_key} (any) group to clear
+
+
+:Fidget lsp_suppress *fidget-:Fidget-lsp_suppress*
+
+ Suppress LSP progress notifications
+
+ Positional arguments: ~
+ {suppress} (boolean) whether to suppress (omitting this argument toggles suppression)
+
+
+:Fidget clear_history *fidget-:Fidget-clear_history*
+
+ Clear notifications history
+
+ Flags: ~
+ --include_active {true|false} (boolean) whether to clear items that have not been removed (default: true)
+ --group_key {group_key} (any) clear history by group key
+ --include_removed {true|false} (boolean) whether to clear items that have have been removed (default: true)
+ --since {since} (number) clear history of items updated at most this long ago
+ --before {before} (number) clear history of items updated at least this long ago
+
+ Positional arguments: ~
+ {group_key} (any) clear history by group key
+
+
+:Fidget suppress *fidget-:Fidget-suppress*
+
+ Suppress notification window
+
+ Positional arguments: ~
+ {suppress} (boolean) whether to suppress (omitting this argument toggles suppression)
+
+
+:Fidget history *fidget-:Fidget-history*
+
+ Show notifications history
+
+ Flags: ~
+ --include_active {true|false} (boolean) whether to clear items that have not been removed (default: `true`)
+ --group_key {group_key} (any) filter history by group key
+ --include_removed {true|false} (boolean) whether to clear items that have have been removed (default: `true`)
+ --since {since} (number) filter history for items updated at most this long ago
+ --before {before} (number) filter history for items updated at least this long ago
+
+ Positional arguments: ~
+ {group_key} (any) filter history by group key
+
+
+
+==============================================================================
+5. Highlights *fidget-highlights*
+
+Rather than defining its own highlights, Fidget’s default configuration uses
+built-in highlight groups that are typically overridden by custom Vim color
+schemes. With any luck, these will look reasonable when rendered, but the
+visual outcome will really depend on what your color scheme decided to do with
+those highlight groups.
-Rather than defining its own highlights, Fidget uses built-in highlight groups
-that are typically overridden by custom Vim color schemes. With any luck, these
-will look reasonable when rendered, but the visual outcome will really depend
-on what your color scheme decided to do with those highlight groups.
+You can override these highlight groups (e.g., `icon_style`) using the
+|fidget-options| shown above.
==============================================================================
-5. Related Work *fidget-related-work*
+6. Related Work *fidget-related-work*
rcarriga/nvim-notify is first and
foremost a `vim.notify()` backend, and it also supports LSP progress
diff --git a/lua/fidget/commands.lua b/lua/fidget/commands.lua
index beab8f1..e046a49 100644
--- a/lua/fidget/commands.lua
+++ b/lua/fidget/commands.lua
@@ -14,11 +14,13 @@ local SC = {}
--- The specification of an argument type.
---@class Type
+---@field name string Human-readable name of the type
---@field parse fun(str: string): (any|nil) How to parse the argument (returns nil if it cannot be parsed)
---@field suggestions string[]|(fun(): string[])|nil Possible list of completion suggestions
---@type Type
SC.Boolean = {
+ name = "boolean",
suggestions = { "true", "false" },
parse = function(str)
if str == "true" then
@@ -33,11 +35,13 @@ SC.Boolean = {
---@type Type
SC.Number = {
+ name = "number",
parse = tonumber,
}
---@type Type
SC.String = {
+ name = "string",
parse = function(str)
if string.sub(str, 1, 1) == [["]] and string.sub(str, #str) == [["]] then
str = string.sub(str, 2, #str - 1)
@@ -55,6 +59,7 @@ SC.String = {
---@return Type
function SC.Enum(alts)
return {
+ name = [["]] .. table.concat(alts, [["|"]]) .. [["]],
suggestions = alts,
parse = function(str)
for _, alt in ipairs(alts) do
@@ -69,6 +74,7 @@ end
---@type Type
SC.Any = {
+ name = "any",
parse = function(str)
local v = SC.Boolean.parse(str)
if v ~= nil then return v end
@@ -290,8 +296,109 @@ function SC.handle_complete(subcmds)
end
end
-function SC.make_vimdoc(subcmd)
+--- Generate vim `:help` docs, with the given tag prefix.
+---
+---@param cmdname string
+---@param subname string
+---@param subcmd SubCommand
+---@param tag_prefix string
+---@return string
+function SC.vimdoc(cmdname, subname, subcmd, tag_prefix)
+ local tag = string.format("*%s-:%s-%s*", tag_prefix, cmdname, subname)
+ local cmd = string.format(":%s %s", cmdname, subname)
+ local header = string.format("%s%s%s", cmd, string.rep(" ", math.max(78 - #tag - #cmd, 0)), tag)
+
+ local pos_args, named_args = {}, {}
+ for name, arg in pairs(subcmd.args) do
+ if type(name) == "string" then
+ name = string.format("--%s {%s}", name, arg.name or name)
+ table.insert(named_args,
+ string.format(" %-30s %-12s %s", name, string.format("(%s)", arg.type.name), arg.desc))
+ else
+ name = string.format("{%s}", arg.name)
+ table.insert(pos_args,
+ string.format(" %-30s %-12s %s", name, string.format("(%s)", arg.type.name), arg.desc))
+ end
+ end
+
+ local pos_docs, named_docs = "", ""
+ if #named_args > 0 then
+ named_docs = string.format([[
+
+ Flags: ~
+%s
+]], table.concat(named_args, "\n"))
+ end
+ if #pos_args > 0 then
+ pos_docs = string.format([[
+
+ Positional arguments: ~
+%s
+]], table.concat(pos_args, "\n"))
+ end
+ return string.format([[
+%s
+
+ %s
+%s%s]], header, subcmd.desc, named_docs, pos_docs)
+end
+
+--- Generate subcommand docs, at the given header level.
+---
+---@param cmdname string
+---@param subname string
+---@param subcmd SubCommand
+---@param level number|nil
+---@return string
+function SC.mddoc(cmdname, subname, subcmd, level)
+ level = level or 4
+
+ local heading = string.format("%s `:%s %s`", string.rep("#", level), cmdname, subname)
+
+ local pos_args, named_args = {}, {}
+ for name, arg in pairs(subcmd.args) do
+ if type(name) == "string" then
+ table.insert(named_args,
+ string.format(" - `--%s {%s}`: `(%s)` %s", name, arg.name or name, arg.type.name, arg.desc))
+ else
+ table.insert(pos_args, string.format(" - `{%s}`: `(%s)` %s", arg.name, arg.type.name, arg.desc))
+ end
+ end
+
+ local pos_docs, named_docs = "", ""
+ if #named_args > 0 then
+ named_docs = string.format([[
+
+Flags:
+
+%s
+]], table.concat(named_args, "\n"))
+ end
+ if #pos_args > 0 then
+ pos_docs = string.format([[
+
+Positional arguments:
+
+%s
+]], table.concat(pos_args, "\n"))
+ end
+
+ local detailed_docs = ""
+ if #named_args > 0 or #pos_args > 0 then
+ detailed_docs = string.format([[
+
+
+ Command arguments
+ %s%s
+ ]], named_docs, pos_docs)
+ end
+
+ return string.format([[%s
+
+%s
+%s
+]], heading, subcmd.desc, detailed_docs)
end
--[[
@@ -325,8 +432,16 @@ SC.subcommands = {
group_key = { type = SC.Any, desc = "filter history by group key" },
before = { type = SC.Number, desc = "filter history for items updated at least this long ago" },
since = { type = SC.Number, desc = "filter history for items updated at most this long ago" },
- include_removed = { type = SC.Boolean, desc = "whether to clear items that have have been removed (default: true)" },
- include_active = { type = SC.Boolean, desc = "whether to clear items that have not been removed (default: true)" },
+ include_removed = {
+ name = "true|false",
+ type = SC.Boolean,
+ desc = "whether to clear items that have have been removed (default: `true`)"
+ },
+ include_active = {
+ name = "true|false",
+ type = SC.Boolean,
+ desc = "whether to clear items that have not been removed (default: `true`)"
+ },
}
},
clear_history = {
@@ -340,8 +455,16 @@ SC.subcommands = {
group_key = { type = SC.Any, desc = "clear history by group key" },
before = { type = SC.Number, desc = "clear history of items updated at least this long ago" },
since = { type = SC.Number, desc = "clear history of items updated at most this long ago" },
- include_removed = { type = SC.Boolean, desc = "whether to clear items that have have been removed (default: true)" },
- include_active = { type = SC.Boolean, desc = "whether to clear items that have not been removed (default: true)" },
+ include_removed = {
+ name = "true|false",
+ type = SC.Boolean,
+ desc = "whether to clear items that have have been removed (default: true)"
+ },
+ include_active = {
+ name = "true|false",
+ type = SC.Boolean,
+ desc = "whether to clear items that have not been removed (default: true)"
+ },
}
},
suppress = {
@@ -373,4 +496,56 @@ function SC.setup()
})
end
+--- Reflect on subcommands specification to generate README documentation.
+---@return string docs
+function SC.make_panvimdocs()
+ local mddocs, vimdocs = {}, {}
+ for name, subcmd in pairs(SC.subcommands) do
+ table.insert(mddocs, SC.mddoc(COMMAND_NAME, name, subcmd, 4))
+ table.insert(vimdocs, SC.vimdoc(COMMAND_NAME, name, subcmd, "fidget"))
+ end
+
+ return string.format([[
+
+
+## Commands
+
+
+
+Fidget exposes some of its Lua API functions through `:Fidget` sub-commands
+(e.g., `:Fidget clear`), which support shell-like arguments and completion.
+These sub-commands are documented below.
+
+
+
+### `:Fidget` sub-commands
+
+%s
+
+
+
+
+
+
+]], table.concat(mddocs, "\n\n"), table.concat(vimdocs, "\n\n"))
+end
+
+-- Quick and dirty: to generate docs, un-comment the following and run :luafile %
+-- local out = io.open("commands.txt", "w")
+-- if out then
+-- out:write(SC.make_panvimdocs())
+-- out:close()
+-- end
+
return SC