Understanding Inhibitors

What the heck is an inhibitor??

Inhibitors are one of the most unique features of Gourd. Instead of simply assigning a role or a permission to each command and calling it a day, Gourd has a fully-involved Inhibitor system that can account for every type of restriction. (If I missed one, feel free to make an issue or reach out to me on Discord).

Inhibitors restrict command usage on a per-module basis. Adding an inhibitor to a module will prevent any of the module's commands from executing unless the inhibitor's condition is met. This can include restricting a module to a certain role, discord permission, or keyword (more on this later). Read on for specifics and use-cases.

Most inhibitors require a Value and Response to work correctly.

• The Value field is used in inhibitors that need an additional value, such as role IDs, or permissions required.
• The Response field is optional. If it is set, the given interface will be sent when the command gets inhibited, or when the user who invoked the command does not have the required access. It is compatible with any interface that Disgord's SendMsg() uses. (strings, embeds, files, etc)

Currently there are 5 module inhibitors:

• Nil Inhibitor
• Role Inhibitor
• Permission Inhibitor
• Keyword Inhibitor
• Owner Inhibitor

Nil Inhibitor

The Nil Inhibitor is the most straightforward of all inhibitors. If a Nil Inhibitor is added to a module, the module will not require any special permissions or roles to access. Furthermore, all modules initialized through gourd.NewModule() are automatically given a Nil Inhibitor, and can be overwritten later if desired.

Adding a Nil Inhibitor to a module:

TestModule := gourd.NewModule("Test")
inhibitor := gourd.NilInhibitor{}
TestModule.SetInhibitor(inhibitor)

// Alternate method, without using NewModule()
TestModule := &gourd.Module{
    Name: "Test",
    Inhibitor: gourd.NilInhibitor{},
}

The Nil Inhibitor has no fields, and no response.

Possible Use Cases

It's fairly self-explanatory, it makes the entire module accessible for everyone. Any kind of general commands, !ping, !info, !help, etc will all be perfectly fine using a Nil Inhibitor.

Role Inhibitor

The Role Inhibitor restricts modules based on a role. When added to a module, all commands added to the module will require the given role in order to be executed.

Adding a Role Inhibitor to a module:

TestModule := gourd.NewModule("Test")
inhibitor := gourd.RoleInhibitor{
    Value: "440952231609761793", // The string ID of the role, not the snowflake.
    Response: "You do not have the role required to use this command!",
}
TestModule.SetInhibitor(inhibitor)

// Alternate method, without using NewModule()
TestModule := &gourd.Module{
    Name: "Test",
    Inhibitor: gourd.RoleInhibitor{
        Value: "440952231609761793", // The string ID of the role, not the snowflake.
        Response: "You do not have the role required to use this command!",
    },
}

The Role Inhibitor requires the Value field to work correctly. The Value field should be the ID of the role the module is to be restricted to. If the user does not have the role, then the command will be inhibited and the Response (if not nil) will be sent.

Role Inhibitors only work inside a server, as a user cannot have a role outside a server.

Possible Use Cases

The Role Inhibitor is best used when it is necessary to restrict management duties within a server. For example, you may have a bot that takes reports or suggestions from users and funnels them into a staff-only area, but you also want certain staff members to be able to reply to or manage these reports.

Permission Inhibitor

The Permission Inhibitor restricts modules based on Discord's built-in permissions. When added to a module, the module's commands will be restricted only to those users who have the given Discord permission.

Adding a Permission Inhibitor to a module:

TestModule := gourd.NewModule("Test")
inhibitor := gourd.PermissionInhibitor{
    Value: disgord.PermissionAdministrator, // It is preferred to use disgord's permission structs, but an int will work.
    Response: "You do not have the permission to use this command!",
}
TestModule.SetInhibitor(inhibitor)

// Alternate method, without using NewModule()
TestModule := &gourd.Module{
    Name: "Test",
    Inhibitor: gourd.PermissionInhibitor{
        Value: disgord.PermissionAdministrator,
        Response: "You do not have the permission to use this command!",
    },
}

The Permission Inhibitor requires a Value to work correctly. Value should be a disgord.PermissionSomething, but using an integer in place of this will work, as long as it corresponds to a Discord permission.

Permission Inhibitors will only work from within a server, as users cannot have permissions outside of a server.

Keyword Inhibitor

Owner Inhibitor