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

var FooPlugin = {
    name: "ctcp-finger",
    init: function (client, deps) {
        return {
            handlers: {
                "!foo": function (command) {
                    return "bar.";
                }
            }
        };
    },

    // Technically not needed, since Tennu provides
    // these before it even tries to load your plugins.
    requires: ["subscriber", "messages", "commands"]
};

module.exports = FooPlugin;

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 the control plugin, you would pass command-ignore-list: [["say", "control"]].

Hooks

commandMiddleware

This hook was added in v4.6.0. Allowing Responses (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.

// Inside an 'admin' style plugin's init function.

return {
    commandMiddleware: function (command) {
        if (adminOnlyCommands.indexOf(command.command) !== -1) {
            return isCalledByAdmin(command).then(function (isCalledByAdmin) {
                if (isCalledByAdmin) {
                    return command;
                } else {
                    return "Permission denied.";
                }
            });
        } else {
            return command;
        }
    },

    ...
};

Here's an example you can use right now (copy and paste) that will log every command that goes through.

var CommandInspectionPlugin = {
    init: function (client) {
        return {
            commandMiddleware: function (command) {
                client.debug("What the command looks like right now.");
                client.debug(require("util").inspect(command));

                // Return the command so that other middleware and the handler can handle it.
                return command;
            }
        };
    }
};

For a final example, by returning undefined, you can just have the client ignore the command minus any previous middleware handling.

var IgnoreAtroPlugin = {
    init: function (client) {
        return {
            commandMiddleware: function (command) {
                // No, Havvy hasn't had any issues with somebody named Atro, really! [/s]
                if (command.nickname === "Atro") {
                    return;
                } else {
                    return command;
                }
            }
        };
    }
};

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.