README
¶
disgord-plugin-router
A plugin management and routing mechanism for Disgord.
WARNING: this repository is still in active development and is not yet ready for the proper expected user experience. See the roadmap for more details.
Design Approach
The approach of this library is that the bot developer will create a plugin for each command, each plugin can have a set of sub-commands.
Example Design
- Roles -> lists the roles when invoked (e.g.: /roles)
- add {role-name} -> appends a given role
- remove {role-name} -> pops a given role
- Colors [color-name] -> lists the roles or set the user's color when invoked
(e.g.: /colors or /colors blue)
- add {color-hex} {color-name} -> registers a new color
- remove {color-name} -> removes a given color
Features
- Can define or not a command to be executed on root commands (read or example)
- Can define sub-commands (one level max by design, see above section) (read or example)
- Can define Disgord events handlers per plugin (read or example)
- Can define typed arguments with auto parsing and error management (read or example)
- Can blacklist/ disable pluging using patterns or matchers (read or example)
- Can define plugin
setUpandtearDownhandlers (read or example) - Command handlers/ callbacks are context based (read or example)
- Plugins can have separate or the same command prefix everywhere (read or example)
- Errors can be returned by handlers and directly reported to the user (read or example)
- Modular, modules can be imported from anywhere using go modules (read or example)
- ...It's open source, fully tested and made with love! 🚀
Usage
package main
import (
"github.com/NyanKiyoshi/disgord-plugin-router"
"github.com/andersfylling/disgord"
)
type _internal struct {}
func main() {
client := disgord.New(&disgord.Config{BotToken: "YOUR BOT TOKEN"})
drouter.Router.Plugin(_internal{}, "ping").
Handler(func(ctx *drouter.Context) error {
return ctx.Say("pong!")
}).
Command("miss").Handler(func(ctx *drouter.Context) error {
return ctx.Say("I missed.")
})
// Setup the client from the router
drouter.Router.Configure(client)
// Connect to the discord gateway to receive events
if err := client.Connect(); err != nil {
panic(err)
}
// Wait for ever for interrupt. Then, disconnect.
if err := client.DisconnectOnInterrupt(); err != nil {
panic(err)
}
}
Roadmap
- Implement arguments parsing with dynamic typing (instead of strings).
- Context arguments should not contain the dispatched root command or sub command.
- Drop plugins pointer array in the router.
- Implement
SetUp(...)andTearDown(...)functions on the plugins. - Add final documentation and complete examples for each feature.
Documentation
¶
Overview ¶
Package drouter was taken from docker's distribution repo, under Apache-2.0 license: https://github.com/docker/distribution/blob/0d3efadf015/registry/auth/token/stringset.go Thank you for your work! <3
Index ¶
- Variables
- func DispatchMessage(ctx *Context, success chan bool)
- func ParseMessage(message string) []string
- type Command
- func (cmd *Command) Handler(callbackFunc callbackFunc) *Command
- func (cmd *Command) Help(helpText string) *Command
- func (cmd *Command) IsMatching(targetCommand string) bool
- func (cmd *Command) Match(matcherFunc matcherFunc) *Command
- func (cmd *Command) MatchRE(regex string) *Command
- func (cmd *Command) Use(callbackFuncs ...callbackFunc) *Command
- type Context
- type Plugin
- func (plugin *Plugin) Activate()
- func (plugin *Plugin) Command(names ...string) *Command
- func (plugin *Plugin) Handler(callbackFunc callbackFunc) *Plugin
- func (plugin *Plugin) Help(helpText string) *Plugin
- func (plugin *Plugin) On(eventName string, inputs ...interface{}) *Plugin
- func (plugin *Plugin) SetPrefix(prefix string) *Plugin
- func (plugin *Plugin) Use(callbackFuncs ...callbackFunc) *Plugin
- type RouterDefinition
- func (router *RouterDefinition) Configure(client routerClient)
- func (router *RouterDefinition) Find(args ...string) (string, *Command)
- func (router *RouterDefinition) OnMessageReceived(session disgord.Session, event *disgord.MessageCreate)
- func (router *RouterDefinition) Plugin(pluginType interface{}, names ...string) *Plugin
- func (router *RouterDefinition) ShouldNotUseRE(regex string) *RouterDefinition
- func (router *RouterDefinition) ShouldUse(pluginFuncs ...shouldEnablePluginFunc) *RouterDefinition
- type StringSet
Constants ¶
This section is empty.
Variables ¶
var DefaultPrefix = "/"
DefaultPrefix defines the default command prefix of plugins.
var LogFatalf = log.Fatalf
LogFatalf is defined from log.Fatalf, the variable is used for mocking purposes.
var Router = &RouterDefinition{}
Router is the global plugin routing object. It should be used by plugins to register themselves during their initialization or else.
Functions ¶
func DispatchMessage ¶
DispatchMessage dispatches a command from a context to the command wrappers and then, if it was succeeded, it invokes the command itself.
Otherwise or if any error from the command, it sends the error to the user as reply. Or if the bot is not able to (e.g.: don't have the 'Send Message' permission), it logs the error.
func ParseMessage ¶
ParseMessage parses a message into a list of arguments.
TODO: in a future release it will parse using typing
and allow quoted arguments.
Types ¶
type Command ¶
type Command struct {
// Names lists the different aliases of the sub-command.
Names StringSet
// MatchFunc is called whenever a new message
// (starting with the correct prefix) is received by the plugin
// and return true or false if it should be handled by this command or not.
MatchFunc matcherFunc
// HandlerFunc Contains the function to invoke
// whenever the command is requested.
HandlerFunc callbackFunc
// Wrappers Contains the functions to invoke before the command.
Wrappers []callbackFunc
// ShortHelp Contains the short straightforward command help.
ShortHelp string
// LongHelp Contains the long descriptive command documentation.
LongHelp string
}
Command defines the structure of a plugin sub-command.
func (*Command) Handler ¶
Handler defines the function to invoke whenever the command is being invoked.
func (*Command) Help ¶
Help sets the help text of a command. The first line is the short and straightforward documentation. The whole text is the long and descriptive documentation.
func (*Command) IsMatching ¶
IsMatching returns true if the command name exists or if it matches the matching function, if provided.
type Context ¶
type Context struct {
// Message contains the received message
Message *disgord.Message
// Session contains the received discord session
Session routerSession
// Command is the matched command
Command *Command
// MatchedPrefix is the command (plugin's) prefix
MatchedPrefix string
// Args contains the received arguments
// Deprecated: it will totally change in a future release
Args []string
}
Context defines callbacks invocation context.
type Plugin ¶
type Plugin struct {
// ImportName defines the import name of the plugin.
ImportName string
// Prefix defines the commands prefix.
Prefix string
// RootCommand defines the base plugin's root/ base command
RootCommand Command
// Listeners defines the different event handlers
// of the plugin (see https://godoc.org/github.com/andersfylling/disgord/event).
Listeners map[string][]interface{}
// Wrappers Contains the registered sub-commands of the plugin.
Commands []*Command
// IsReady is true is the module was loaded and installed into the client.
IsReady bool
}
Plugin defines the structure of a disgord plugin.
func (*Plugin) Handler ¶
Handler defines the function to invoke whenever the plugin command is being invoked.
func (*Plugin) Help ¶
Help sets the help text of a command. The first line is the short and straightforward documentation. The whole text is the long and descriptive documentation.
type RouterDefinition ¶
type RouterDefinition struct {
// Plugins Contains every registered plugin.
Plugins []*Plugin
// ShouldEnablePluginFuncs Contains a list of matcher to test
// against package paths. If it returns false, the plugin must disabled.
ShouldEnablePluginFuncs []shouldEnablePluginFunc
}
RouterDefinition defines the structure of a bot plugins routing.
func (*RouterDefinition) Configure ¶
func (router *RouterDefinition) Configure(client routerClient)
Configure configures the bot's client with the router and plugins. 1. It hooks the internal events of the router; 2. It configures and enables every plugin that are enabled.
func (*RouterDefinition) Find ¶
func (router *RouterDefinition) Find(args ...string) (string, *Command)
Find looks for a matching command. Returns the matched prefix and command, if found.
func (*RouterDefinition) OnMessageReceived ¶
func (router *RouterDefinition) OnMessageReceived(session disgord.Session, event *disgord.MessageCreate)
OnMessageReceived is invoked whenever a new message is created, it will dispatch instructions if the message is a command, and if the message is not from the bot itself.
func (*RouterDefinition) Plugin ¶
func (router *RouterDefinition) Plugin(pluginType interface{}, names ...string) *Plugin
Plugin creates a new module from a given type that will generate the proper Plugin.ImportName value. And takes a human readable plugin name.
Parameters:
pluginType Any object defined in the plugin's package that will be used
to extract the module's package path, such as "my-modules/stats".
name The plugin's human readable name, such as "bot-statistics".
func (*RouterDefinition) ShouldNotUseRE ¶
func (router *RouterDefinition) ShouldNotUseRE(regex string) *RouterDefinition
ShouldNotUseRE registers a regex to be tested against plugins that should be disabled.
func (*RouterDefinition) ShouldUse ¶
func (router *RouterDefinition) ShouldUse(pluginFuncs ...shouldEnablePluginFunc) *RouterDefinition
ShouldUse register matchers to test against plugins to keep enabled or to disable.
type StringSet ¶
type StringSet map[string]struct{}
StringSet is a useful type for looking up strings.
func NewStringSet ¶
NewStringSet creates a new StringSet with the given strings.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
Dummy
command
|
|
|
mocks
|
|
|
mocked_disgord
Package mock_drouter is a generated GoMock package.
|
Package mock_drouter is a generated GoMock package. |