nosedrum

v0.2.0

nosedrum v0.2.0 Nosedrum.Predicates View Source

Built-in command predicates and predicate evaluation.

Nosedrum.Command.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.Command.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

Link to this type

evaluation_result() View Source (since 0.2.0) 
evaluation_result() :: :passthrough | {:error, String.t()}

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.
  • {:error, reason} if the predicate does not permit the command to be invoked, or if the predicate could not determine its result.
Link to this type

predicate() View Source (since 0.2.0) 
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

Link to this function

evaluate(message, predicates) View Source (since 0.2.0) 
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

Link to this function

guild_only(arg1) View Source (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.

Link to this function

has_permission(permission) View Source (since 0.2.0) 
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.Command.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.Command

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