Nosedrum.TextCommand.Storage behaviour (nosedrum v0.6.0) View Source

Storages contain commands and are used by command invokers to look up commands.

How you start a storage is up to the module itself - what is expected is that storage modules implement the behaviours documented in this module.

The public-facing API of storage modules takes an optional argument, the storage process or other information used to identify the storage such as an ETS table name.

Link to this section Summary

Types

command_group()

A single command module or mapping of subcommand names to command groups.

command_path()

The "invocation path" of the command.

Callbacks

add_command(path, command, storage)

Add a new command under the given path.

all_commands(storage)

Return a mapping of command names to command_group/0s.

lookup_command(name, storage)

Look up a command group under the specified name.

remove_command(path, storage)

Remove the command under the given path.

Link to this section Types

command_group()

Specs

command_group() ::
  module()
  | %{
      optional(:default) => command_group(),
      required(String.t()) => command_group()
    }

A single command module or mapping of subcommand names to command groups.

In addition to subcommand names, the key :default can be specified by the module. :default should be invoked when none of the subcommands in the map match.

command_path()

Specs

command_path() :: [String.t() | :default, ...]

The "invocation path" of the command.

The public-facing API of storage modules should use this in order to allow users to identify the command they want to operate on.

Usage

To identify a single command, use a single element list, such as ["echo"]. To identify a subcommand, use a pair, such as ["infraction", "search"]. To identify the default subcommand invoked when no matching subcommand is found, specify the group name first, then :default, such as ["tags", :default].

Link to this section Callbacks

add_command(path, command, storage)

Specs

add_command(path :: command_path(), command :: module(), storage :: reference()) ::
  :ok | {:error, String.t()}

Add a new command under the given path.

If a command has the c:Nosedrum.TextCommand.aliases/0 callback defined, they will also be added under path. If the command already exists, no error should be returned.

all_commands(storage)

Specs

all_commands(storage :: reference()) :: %{
  required(String.t()) => command_group()
}

Return a mapping of command names to command_group/0s.

For top-level commands, the value should be a string, otherwise, a mapping of subcommand names to subcommand modules as described on command_group/0s documentation should be returned.

lookup_command(name, storage)

Specs

lookup_command(name :: String.t(), storage :: reference()) ::
  command_group() | nil

Look up a command group under the specified name.

If the command was not found, nil should be returned.

remove_command(path, storage)

Specs

remove_command(path :: command_path(), storage :: reference()) ::
  :ok | {:error, String.t()}

Remove the command under the given path.

If a command has the c:Nosedrum.TextCommand.aliases/0 callback defined, they will also be removed under path. If the command does not exist, no error should be returned.