Nosedrum.TextCommand.Predicates (nosedrum v0.6.0) View Source

Built-in command predicates and predicate evaluation.

Nosedrum.TextCommand.predicates/0 allows commands to specify a set of conditions that must be met before a command is invoked, effectively allowing you to deny access to certain access. For instance, allowing every user on your server to issue a ban command may not be desirable.

For using the Nosedrum.TextCommand.predicates/0 callback, you can either define your own predicates or use those provided by this module.

Link to this section Summary

Types

evaluation_result()

The result of a predicate evaluation, determining whether the command invocation should proceed or abort.

predicate()

A condition that must pass before a command is invoked.

Evaluation

evaluate(message, predicates)

Lazily evaluate all given predicates and return the result.

Predicates

guild_only(arg1)

Check whether the command was invoked on a guild.

has_permission(permission)

Check whether the message author has the given permission.

Link to this section Types

evaluation_result()

(since 0.2.0)

Specs

evaluation_result() :: :passthrough | {:noperm, any()} | {:error, any()}

The result of a predicate evaluation, determining whether the command invocation should proceed or abort.

The values represent the following:

:passthrough if the predicate permits the command to be invoked.
{:noperm, any()} if the predicate does not permit the command to be invoked.
{:error, any()} if the predicate could not determine its result.

On :passthrough, invokers will continue with predicate checking and finally invoke the command. On :noperm or :error, command execution is aborted.

predicate()

(since 0.2.0)

Specs

predicate() :: (Nostrum.Struct.Message.t() -> evaluation_result())

A condition that must pass before a command is invoked.

Example

defmodule MyBot.Predicates do
  alias Nostrum.Struct.Message

  def guild_only(%Message{guild_id: nil}) do
    {:error, "This command can only be used on guilds."}
  end

  def guild_only(_msg), do: :passthrough
end

Link to this section Evaluation

evaluate(message, predicates)

(since 0.2.0)

Specs

evaluate(Nostrum.Struct.Message.t(), [predicate()]) :: evaluation_result()

Lazily evaluate all given predicates and return the result.

While usually used by command invokers, you can use this function if you need to manually evaluate the result of predicates.

Return value

If all predicates returned :passthrough, :passthrough is returned. Otherwise, the error of the first predicate returning one is returned.

Link to this section Predicates

guild_only(arg1)

(since 0.2.0)

Check whether the command was invoked on a guild.

Note that has_permission/1 already checks whether a command was invoked on a guild and this predicate does not need to be stack with it.

has_permission(permission)

(since 0.2.0)

Specs

has_permission(Nostrum.Permission.t()) :: predicate()

Check whether the message author has the given permission.

This does not directly return an evaluation_result/0: it returns a function allowing you to use this in your Nosedrum.TextCommand.predicates/0 callback.

When evaluation fails, an error with a description of the required permission is returned, or another error when the permission could not be checked on the author - for example, because the guild or member was not found in the cache.

Example

defmodule MyBot.Cogs.Ban do
  @behaviour Nosedrum.TextCommand

  def usage, do: ["ban <member>"]
  def description, do: "Ban the given `member`."
  def predicates, do: [Nosedrum.TextCommand.Predicates.has_permission(:ban_members)]
  def command(msg, [target]) do
    # ... 🔨
  end
end