/ 
Discord-Client-0.001
/ Discord::Client::Commands

NAME

Discord::Client::Commands - Command declarations and explicit deployment

SYNOPSIS

use Discord::Client::Commands;

# Create a local registry without network I/O.
my $commands = Discord::Client::Commands->new;

# Declare /greet with one required argument.
$commands->define(
    greet => (
        description => 'Greet someone',
        options => [
            {name => 'name', type => 'string', description => 'Name', required => 1},
        ],
        handler => sub {
            my ($interaction) = @_;
            return $interaction->reply({
                content => 'Hello, '.$interaction->option('name'),
                allowed_mentions => {parse => []},
            });
        },
    ),
);

DESCRIPTION

Stores local command declarations and handlers. "command" in Discord::Client delegates to this registry. Declaration makes no request; sync explicitly deploys commands. Startup never deploys commands.

METHODS

new

new(loop => $loop, rest => $rest, application_id => $id) returns a registry. All arguments are optional. Without loop, one is created. Deployment needs a Bot-authorized REST client.

define

define(name, description => ..., options => [...], handler => CODE) declares a slash command and returns the registry. Handlers receive an Discord::Client::Interaction; return their response Future and reply or defer explicitly. Invalid declarations throw before changing the registry. Validation covers names, descriptions, types, unique option names, nesting, choices and bounds. Required options must precede optional ones. Slash names use Discord's Unicode/lowercase rules.

Option types are subcommand, group, string, integer, boolean, user, channel, role, mentionable, number and attachment; numeric values 1–11 are accepted. Subcommands can have their own handler or use the root handler. Groups contain subcommands and have no handler. Do not mix value options and subcommands at one level.

type => 'user' or 'message' declares a context-menu command without a description or options. Its name may contain spaces and mixed case. JSON fields for localization, contexts, installation and permissions are preserved. Permission bit sets are sent as strings.

definitions

Returns a copied JSON-ready arrayref without callbacks.

application_id

Returns the configured application ID. application_id(id) sets it and returns the ID; invalid IDs throw.

component

component(custom_id => CODE) registers a button, select menu or modal handler and returns the registry. The handler receives an Interaction.

handler_for

handler_for($interaction) returns the selected callback or undef if absent. It validates invocation options and may throw for invalid arguments.

sync

# Replace this application's commands in one server.
my $deployment = $bot->commands->sync(scope => {guild_id => $guild_id});
$bot->loop->await($deployment);
$deployment->get;

Use scope => {global => 1} for global deployment; this is also the default. sync bulk-replaces slash and context-menu commands in the selected scope. Commands absent from the local declarations are removed.

sync returns a Future. Concurrent sync calls fail with state; cancellation propagates to REST. The application ID comes from construction, READY or REST discovery. Deployment needs a Bot-authorized REST client.

To deploy an example's declarations without starting its Gateway:

perl examples/sync-commands.pl examples/ping.pl
perl examples/ping.pl

Set DISCORD_BOT_TOKEN and TEST_GUILD_ID. The script deploys only to that server. Examples return their client when loaded and run only when executed directly. Use the example list to choose another command set.

close

Cancels an active synchronization and clears handlers. Returns a completed Future. An injected REST client remains caller-owned.

AUTOCOMPLETE

Set autocomplete => CODE on a string, integer or number option. Return a choice array such as [{name => 'Perl', value => 'perl'}], a Future yielding that array, or call $interaction->autocomplete explicitly. Do not combine autocomplete with fixed choices. Invocation options are checked against the declaration; autocomplete permits partial input.

LICENSE

Apache License 2.0.