Commands Plugin
This plugin is built-in.
This plugin listens to privmsg
events, determining whether it's a command invocation, creating a Command
and firing off a command event when it is. The event name is the name of the command. You can subscribe to these events using the handlers
plugin hook.
Example
Config
command-trigger: String
- The prefix to search for in PRIVMSGs in channels to determine whether the message is a command.
command-ignore-list: [String | [String]]
-
A list of commands that the handler will not be called for.
If the entry is a String, then all handler attempts will be ignored.
If the entry is an array of Strings, the first entry in that array will be the command to be ignored and the rest of the entries will be plugins to ignore that command from. For example, to ignore the
say
from thecontrol
plugin, you would passcommand-ignore-list: [["say", "control"]]
.
Hooks
commandMiddleware
This hook was added in v4.6.0. Allowing Response
s (beyond undefined
) was added in v4.7.0
The commandMiddleware
hook takes a function that gives you a Command
that you can choose to modify or not. You must either return that Command
or a Response
or a Promise of one of those values. If you return a Response
, it will end the handling of that command.
You can only have one middleware per plugin, and middlewares are added in the order plugins are loaded.
Middleware is useful for preventing commands from being executed for whatever reason. For instance, a middleware that makes certain commands admin-only could decide to return the Command if the user is an admin, and return a response of "Permission Denied" if the user is not.
Here's an example you can use right now (copy and paste) that will log every command that goes through.
For a final example, by returning undefined
, you can just have the client ignore the command minus any previous middleware handling.
Middleware can also re-order arguments and rename the command. This could be useful for aliases.
You MUST NOT change the underlying properties from Message
since that will change how other privmsg
handlers see the message.
Returning a new Command
is not possible. The check to see if you returned the Command
is an identity comparison with the Command
that was passed to your middleware function.
Exports
- isCommand(Message)
- Returns true if the Message is a command, whether it is handled or not. Otherwise returns false.
- isHandledCommand(Message)
This export was added in v4.4.0.
Returns true if the Message is a command that is handled by a command handler. Otherwise returns false.