Lingo.Bot.Commands (Lingo v0.4.2)

Copy Markdown View Source

Declaring application commands, imported by use Lingo.Bot. Each declared command is handled in Lingo.Bot.handle_command/2.

Summary

Functions

Declares a slash command. Handle it in Lingo.Bot.handle_command/2.

Declares the app's entry point command, which opens its Activity from the App Launcher. An app has at most one, and it's always global, so registering for guilds leaves it out.

Declares a message context menu command (right click on a message). Handle it in Lingo.Bot.handle_command/2; the message is ctx.target_id.

Declares a user context menu command (right click on a user). Handle it in Lingo.Bot.handle_command/2; the user is ctx.target_id.

Functions

command(name, description, opts \\ [])

(macro)

Declares a slash command. Handle it in Lingo.Bot.handle_command/2.

Options:

  • :options - the command's options, built with Lingo.Bot.Options
  • :default_member_permissions - permissions a member needs by default, as a bitfield (see Lingo.Permissions.from_list/1)
  • :nsfw - only usable in age-restricted channels
  • :integration_types - where it can be installed: 0 guild, 1 user
  • :contexts - where it can be used: 0 guild, 1 bot DM, 2 private channel
  • :name_localizations, :description_localizations - maps of locale to text
  • :checks - what must hold for the command to run, checked before Lingo.Bot.handle_command/2: :guild_only, :dm_only, :nsfw, :owner_only (the app's owner, or its team's owner, admins and developers), {:permissions, perms} (the member's, in the channel), {:bot_permissions, perms}, or a function like &MyBot.allowed?/1 getting the context and returning true or :ok to pass, false or {:error, message} to fail. Permission checks fail as :guild_only outside a guild. See Lingo.CheckError for what happens when one fails. They don't replace :default_member_permissions, which also hides the command from members without them.
  • :cooldown - {uses, per_ms}, {uses, per_ms, scope} or [uses: n, per: ms, scope: s]: at most uses per per_ms for each :user (the default), :member, :guild, :channel, or :globally. The window starts at the first use. A function like &MyBot.cooldown/1 decides for each use: it gets the context and returns a cooldown, or nil for none (for owners, premium users...). Cooldowns count per node.

For example:

command "ban", "Bans a member",
  options: [user(:member, "Who", required: true)],
  checks: [:guild_only, {:permissions, [:ban_members]}, {:bot_permissions, [:ban_members]}],
  cooldown: {1, 5_000}

entry_point_command(name, description, opts \\ [])

(macro)

Declares the app's entry point command, which opens its Activity from the App Launcher. An app has at most one, and it's always global, so registering for guilds leaves it out.

Enabling Activities makes Discord create one named "Launch", and registering keeps that one while the bot declares none: declare it only to change it.

Takes the options of command/3 except :options, plus :handler: :discord_launch_activity (the default) has Discord launch the Activity itself, and :app_handler sends the command to Lingo.Bot.handle_command/2, to answer with Lingo.Context.launch_activity/1 or anything else.

message_command(name, opts \\ [])

(macro)

Declares a message context menu command (right click on a message). Handle it in Lingo.Bot.handle_command/2; the message is ctx.target_id.

Takes the same options as command/3, except :options and :description_localizations.

user_command(name, opts \\ [])

(macro)

Declares a user context menu command (right click on a user). Handle it in Lingo.Bot.handle_command/2; the user is ctx.target_id.

Takes the same options as command/3, except :options and :description_localizations.