Plugin System Internals: Help Text Use Case

Use Case: Help Text

This is a sub-ticket of issue #50, as it will inform the decisions around creating a plugin system.

First possible use case for a plugin system (registry, really):

lfetool needs to display:
1. a list of all top level commands (one could give by calling (lfetool-inspect:get-all-commands))
2. the corresponding help for each one of these commands (not currently defined anywhere)
3. support both lfetool-standard commands as well as potentially user-added top-level commands

To accomplish support of that third point, we would need a mechanism such that:

all plugins that support or add a top-level commands register their name, their top-level command, and the general help for that command
a query to that registry that can get plugins which meet certain criteria

Each plugin might support a new command. For instance, the script and yaws plugin will each have a new function that will be called in the event of one of the following commands being issued:

lfetool new script <name> or
lfetool new yaws <name>
Example Scenario

However, when listing all commands, e.g., lfetool commands, we would want to see not the plugins, but just the supported commands and what they mean generally, e.g.:

$ lfetool commands

commands - list all the top-level commands supported by lfetool
help     - get the general help for lfetool; if passed a plugin name as an argument,
           display the help for that plugin
new      - create new LFE projects with related files pre-populated with code
version  - display lfetool-related versioning information

Custom commands:

alice    - a special command for a custom workflow, written by Alice for her use only
bob      - some of a lark, but bob tends to use this command a bunch, so there
carol    - a super-useful command Carol's thinking about contributing back to lfetool

Registry Questions

If we had a registry, what might a plugin/command need to register ... what, exactly? (what's the minimum amount of information necessary to identify and then call any given "plugin behaviour" function in any given plugin module?

path to plugin? or
module? (and then use functions defined in a behaviour to get things like help text, command output, etc.)
atom that identifies type (either lfetool command or user command ... anymore?)

Default lfetoolcommands would be obtained by lists:usorting all the commands each lfetool plugin supported.

Likewise for user commands, filtering on plugins where type="user" (or "custom"?).

Summary

In summary, lfetool needs:

a data source for querying plugin metadata
functions for updating this data source
a way of querying a data source and displaying to the terminal such that:
- general help that is valid for all plugins, even when a plugin command may come from only one or two plugins (in other words, might not be supported by all plugins)
- general help for custom commands, not specific to the one or two user plugins that might support that command

Thoughts on technical tasks:

[x] create src/lfetool-registry.lfe module
[ ] create an API for creating, updating, and querying the registry
[ ] do a first implementation of a registry using orddict accessible a process that receives messages
- [ ] messages should receive on plugin name, plugin type, and desired function? feature?
- [ ] process should send back just a list of modules which support these (on which the desired function may be called)
[x] create a new behaviour for plugins that provide top-level command help definitions
[ ] update plugins and command modules with a new register function that will provide the registry with enough information to do its job
[x] find all plugins and command modules
[ ] then call the register function in them to populate the registry with scanned data (this should be done in (lfetool:init))
[ ] query the registry to get all general top-level command help text for lfetool commands
[ ] query the registry to get all general top-level command help text for user commands

With the latest changes committed (and pushed), here's the current output of lfetool commands:

Help for lfetool built-in top-level commands:

commands - List all the top-level commands available to lfetool.
extract  - lfetool is no longer compressed; this is a no-op (included for
           backwards compatibility only).
help     - Get the general help for lfetool; if passed a plugin name as
           an argument, display the help for that plugin.
info     - Get information of the type indicated by the passed argument.
install  - Install LFE by default; if passed an argument, in stall the
           indicated software.
repl     - By default, start an LFE REPL with access to all the
           dependency modules; if passed an argument, start a REPL of
           that particular type.
new      - Create new LFE projects with related files pre-populated with
           code.
tests    - Perform the tests-related action for the given argument.
update   - Update the system/software associated with the given argument.
usage    - Get lfetool usage.
version  - Get the current version of lfetool and associated systems.

User-provided top-level commands:

whiggity - Do something crazy.
whack    - Do something even crazier.

lfe-deprecated / lfetool