Crux v2020-03-17 17:55:51Z Crux.Extensions.Command behaviour View Source

Behaviour module used to compose command pipelines.

Examples

A Simple Ping Command

  defmodule MyBot.Command.Ping do
    use Crux.Extensions.Command

    def triggers(), do: ["ping"]

    def call(command, _opts) do
      set_response(command, content: "Pong!")
    end
  end

A Simple Middleware Command

  defmodule MyBot.Middleware.FetchPicture do
    use Crux.Extensions.Command

    def call(command, opts) do
      # Default the type to :cat
      type = Keyword.get(opts, :type, :cat)

      case MyBot.Api.fetch_picture(type) do
        {:ok, picture} ->
          assign(command, :picture, picture)
        {:error, _error} ->
          command
          |> set_response(content: "An error occurred while fetching the picture.")
          # Halt the pipeline to stop any further execution of commands or middlewares
          |> halt()
      end
    end
  end

Using the Middleware Command

  defmodule MyBot.Command.Dog do
    use Crux.Extensions.Command

    def triggers(), do: ["dog"]

    # Specify the type of :dog
    def required(), do: [{MyBot.Middleware.FetchPicture, type: :dog}]

    def call(command, _opts) do
      set_response(command, content: "Your dog picture link: #{command.assigns.picture}")
    end
  end

Link to this section Summary

Types

A command module, or command module and options tuple.

A module implementing the Crux.Extensions.Command behaviour.

Options being passed to the call/2 of a command_mod/0.

t()

Represents the current state of an executing command.

Functions

Assigns an arbitrary value to an atom key, which is accessible
under the assigns field of a Command.

Halts this command, no other commands will be executed fater this one.

Sets the response content for this command.

Sets the response channel for this command.

Callbacks

Exeucting this command module.

Returns a list of required command modules to run before this one.

List of possible triggers for this command module.

Link to this section Types

A command module, or command module and options tuple.

Link to this type

command_mod() View Source
command_mod() :: module()

A module implementing the Crux.Extensions.Command behaviour.

Link to this type

command_opts() View Source
command_opts() :: term()

Options being passed to the call/2 of a command_mod/0.

The exact type is defined by the command itself.

Link to this type

t() View Source
t() :: %Crux.Extensions.Command{
  args: [String.t()],
  assigns: %{required(atom()) => term()},
  halted: boolean(),
  message: Crux.Structs.Message.t(),
  response: term(),
  response_channel: Crux.Rest.Util.channel_id_resolvable(),
  shard_id: non_neg_integer(),
  trigger: String.t()
}

Represents the current state of an executing command.

Link to this section Functions

Link to this function

assign(command, key, value) View Source
assign(t(), key :: atom(), value :: term()) :: t()

Assigns an arbitrary value to an atom key, which is accessible
under the assigns field of a Command.

Link to this function

halt(command) View Source
halt(t()) :: t()

Halts this command, no other commands will be executed fater this one.

Link to this function

set_response(command, response) View Source
set_response(t(), term()) :: t()

Sets the response content for this command.

Link to this function

set_response_channel(command, response_channel) View Source
set_response_channel(t(), Crux.Rest.Util.channel_id_resolvable() | nil) ::
  t()

Sets the response channel for this command.

Link to this section Callbacks

Link to this callback

call(t, command_opts) View Source
call(t(), command_opts()) :: t()

Exeucting this command module.

Link to this callback

required() View Source (optional)
required() :: [command_mod() | {command_mod(), command_opts()}]

Returns a list of required command modules to run before this one.

Link to this callback

triggers() View Source (optional)
triggers() :: [String.t() | nil]

List of possible triggers for this command module.

Only used and required for primarily handled commands.