ken

package module
v0.20.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 25, 2024 License: MIT Imports: 14 Imported by: 26

README

ken   GitHub tag (latest by date) Go Report Card

Warning
This package is still in an early state of development and future updates might introduce breaking changes to the API until the first official release.

剣 (ken - japanese for Sword) - A cutting edge (haha), object-oriented and highly modular Discord application commands and interaction handler for Discordgo.

For basic usage examples, see the basic example section. Examples on how to use middlewares can be found here.

This package was primarily written with the motivation to use it in my Discord bot shinpuru. So some design decision might be influenced by that.

All you need to know

Why should you use this package?

ken tries to provide an "everything in the kitchen skink" framework to simplify and speed up bot development using the Discord interaction API. It also tries to provide a great developer experience while giving you full control over the underlying event data and API interactions – just in the style of discordgo itself.

Also, ken provides a higly modular middleware pipeline to control who can use commands and how they should be handled.

Things you can do with ken:

High modularity

The command-registration and middleware system is built so that you can add whatever functionality you want to your command structure and handle it all in your middleware which can be called before and/or after command execution. The only thing required is that your commands implements one of the provided command interfaes:

Command Pipeline

In the middleware example, you can take a look at how to implement custom functionality in your command structure and add middleware functions to handle these.

Via options you can also specify a custom state handler, if you are using something like dgrs for example.

Quality of Life Implementations

ken passes a single Context object to the command handlers which contains everything you need. It allows you to access raw discordgo.InteractionCreate event data, the Command instance which has been called, the discordgo.Session, as well as many utility functions.

For example, you can easily respond to the event by using the Respond method to send a response to an interaction. Defer does the same but sends a defer response so you can send follow-up messages afterwards with a delay.

Speaking of follow-up messages, there are some simple functions like FollowUp, FollowUpEmbed or FollowUpError to make building these follow-up messages easier. These functions return a single FollowUpMessage object so that you can chain calls like DeleteAfter to delete the follow-up message after a given timespan. 🤯

The Ctx also allows you to handle sub-commands using HandleSubCommands. Simply pass a name and handler function as SubCommandHandler to build your sub-command tree. The sub-command handlers are passed a specialized SubCommandCtx, which scopes the Options method to the options of the sub-command. So you can handle options like you would in a top-level command. In this example you can see a practical implementation of sub-commands.

Performance

To avoid registering and unregistering commands everytime the bot restarts, ken allows to cache commands using a CommandStore. Although disabled by default, the provided default implementation LocalCommandStore can be used. It stores the commands in a file which will be tried to read from on the next startup. You can also implement your own store, with Redis for example.

ken uses sync.Pool as object pools for the command context which are used for command and sub-command execution. This is done to avoid creating a new context object for each command execution which would put strain on the garbage collector, especially on high command execution frequencies.

Example Usage

package main

// imports ...

type TestCommand struct{}

var _ ken.SlashCommand = (*TestCommand)(nil)

func (c *TestCommand) Name() string {
	return "ping"
}

func (c *TestCommand) Description() string {
	return "Basic Ping Command"
}

func (c *TestCommand) Version() string {
	return "1.0.0"
}

func (c *TestCommand) Options() []*discordgo.ApplicationCommandOption {
	return []*discordgo.ApplicationCommandOption{}
}

func (c *TestCommand) Run(ctx ken.Context) (err error) {
	err = ctx.Respond(&discordgo.InteractionResponse{
		Type: discordgo.InteractionResponseChannelMessageWithSource,
		Data: &discordgo.InteractionResponseData{
			Content: "Pong!",
		},
	})
	return
}

func main() {
	token := os.Getenv("TOKEN")

	session, err := discordgo.New("Bot " + token)
	if err != nil {
		panic(err)
	}
	defer session.Close()

	k := ken.New(session)
	k.RegisterCommands(
		new(commands.TestCommand),
	)

	defer k.Unregister()

	err = session.Open()
	if err != nil {
		panic(err)
	}

	sc := make(chan os.Signal, 1)
	signal.Notify(sc, syscall.SIGINT, syscall.SIGTERM, os.Interrupt, os.Kill)
	<-sc
}

You can also find a "real world" implementation in my Discord Bot shinpuru, where ken is used as main slash command framework.

FAQ

Why do my commands not show up in Discord?

This may have multiple reasons.

  1. Check if you invited your Bot with the applications.commands OAuth2 scope. This option was added for bots to be permitted to create slash commands for a guild. When you already invited your bot before that, the bot will not be able to register slash commands. To fix this, simply kick the bot and re-invite it with an invite link containing the required applications.commands scope.

    Pro-Tip: You can go to the OAuth2 Page in the Discord Application settings to generate a suitable invite link.

  2. When a command needs to be created (if you start the bot with a newly added command), It may take up to 15-30 minutes (based on personal experience) until the command shows up in Guilds. After that (when CommandStore is enabled), commands are re-used and updated, which does not take that much time.

    Pro-Tip: To create a command, you just need to specify a valid name, description and options and add it to ken's handler register. After that, start the bot in the background and then implement the command logic to bridge the time until the command shows up to test it.

  3. As I have experienced personally, sometimes, you might need to restart your Discord client until commands show op on Guilds. And sometimes you even need to kick and re-invite the bot so that they show up. I don't really know if this is a registration issue on ken's site. If you know more about that, please let me know!

Why do I get the error command name is invalid?

Discord has some very strong restrictions to the naming of commands and command options. The name of a command, sub command or command option must be unique and must match the regex ^[a-z0-9-_]{1,32}$¹.

If you are not familiar with regex, the name must match the following conditions:

  • It must only contain lowercase letters, numbers, dashes and underscores.
  • It must be at least 1 character and at most 32 characters long.

¹ The pattern described in the Discord docs ^[\w-]{1,32}$ is actually not accurate, because you can not use uppercase letters in names, but you can use underscores.

Projects using ken

If you used ken in your project, feel free to add it here with a pull request. 😉

© 2022 Ringo Hoffmann (zekro Development).
Covered by the MIT Licence.

Documentation

Overview

Package ken provides an object-oriented and highly modular slash command handler for discordgo.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrEmptyCommandName         = errors.New("command name can not be empty")
	ErrCommandAlreadyRegistered = errors.New("command with the same name has already been rgistered")
	ErrInvalidMiddleware        = errors.New("the instance must implement MiddlewareBefore, MiddlewareAfter or both")
	ErrNotDMCapable             = errors.New("The executed command is not able to be executed in DMs")
)

Functions

This section is empty.

Types

type AutoCompleteOptions added in v0.20.0 

type AutoCompleteOptions struct {
	// contains filtered or unexported fields
}

func (AutoCompleteOptions) GetInput added in v0.20.0 

func (t AutoCompleteOptions) GetInput(optionName string) (value string, ok bool)

func (AutoCompleteOptions) Name added in v0.20.0 

func (t AutoCompleteOptions) Name() string

type AutocompleteCommand added in v0.19.0 

type AutocompleteCommand interface {
	// Autocomplete will be called every time an autocomplete input event has veen received
	// for the registered command. It is getting passed a context which contains the event
	// data.
	//
	// Return the choises that shall be displayed or an error if something went wrong
	// during fetching the choises.
	//
	// The context object should not be used after the handler call has been completed.
	Autocomplete(ctx *AutocompleteContext) ([]*discordgo.ApplicationCommandOptionChoice, error)
}

AutocompleteCommand can be implemented by your command to enable autocomplete support for your command options.

type AutocompleteContext added in v0.19.0 

type AutocompleteContext struct {
	ObjectMap
	// contains filtered or unexported fields
}

AutocompleteContext provides easy acces to the underlying event data.

func (*AutocompleteContext) Channel added in v0.19.0 

func (t *AutocompleteContext) Channel() (*discordgo.Channel, error)

Channel tries to fetch the channel object from the contained channel ID using the specified state manager.

func (*AutocompleteContext) Event added in v0.19.0 

func (t *AutocompleteContext) Event() *discordgo.InteractionCreate

Event returns the underlying InteractionCreate event.

func (*AutocompleteContext) Get added in v0.20.0 

func (c *AutocompleteContext) Get(key string) (v interface{})

Get either returns an instance from the internal object map - if existent. Otherwise, the object is looked up in the specified dependency provider, if available. When no object was found in either of both maps, nil is returned.

func (*AutocompleteContext) GetData added in v0.19.0 

func (t *AutocompleteContext) GetData() discordgo.ApplicationCommandInteractionData

GetData returns the ApplicationCommandInteractionData of the internal event.

func (*AutocompleteContext) GetInput added in v0.19.0 

func (t *AutocompleteContext) GetInput(optionName string) (value string, ok bool)

GetInput takes the name of a command option and returns the input value from the event for that option.

If ok is false, no value could be found for the given option.

func (*AutocompleteContext) GetKen added in v0.19.0 

func (t *AutocompleteContext) GetKen() *Ken

GetKen returns the Ken instance.

func (*AutocompleteContext) GetSession added in v0.19.0 

func (t *AutocompleteContext) GetSession() *discordgo.Session

GetSession returns the Discordgo Session instance.

func (*AutocompleteContext) Guild added in v0.19.0 

func (t *AutocompleteContext) Guild() (*discordgo.Guild, error)

Guild tries to fetch the guild object from the contained guild ID using the specified state manager.

func (*AutocompleteContext) Member added in v0.19.0 

func (t *AutocompleteContext) Member() (u *discordgo.Member)

Member returns the user object of the event caller. It may be nil if no member has been set to the event.

func (*AutocompleteContext) ResetState added in v0.19.0 

func (t *AutocompleteContext) ResetState()

func (*AutocompleteContext) SubCommand added in v0.20.0 

func (t *AutocompleteContext) SubCommand(name ...string) AutoCompleteOptions

SubCommand returns the sub command options for any of the given sub command or sub command group. If no command name is passed, the sub command options are returned from the first sub command found in the event.

func (*AutocompleteContext) User added in v0.19.0 

func (t *AutocompleteContext) User() (u *discordgo.User)

User returns the user object of the event caller. It may be nil if no user has been set to the event.

type Command 

type Command interface {
	// Name returns the unique name of the command.
	Name() string

	// Description returns a brief text which concisely
	// describes the commands purpose.
	//
	// Currently, this is ignored by user and message
	// commands, because the API currently does not
	// support descriptions for these types of
	// application commands.
	Description() string

	// Run is called on command invokation getting
	// passed the invocation context.
	//
	// When something goes wrong during command
	// execution, you can return an error which is
	// then handled by Ken's OnCommandError handler.
	Run(ctx Context) (err error)
}

Command specifies the base interface for an application command.

type CommandHandler added in v0.20.0 

type CommandHandler interface {
	Type() discordgo.ApplicationCommandOptionType
	OptionName() string
	RunHandler(ctx SubCommandContext) error
}

CommandHandler defines either a SubCommandHandler or a SubCommandGroup.

type CommandInfo added in v0.7.0 

type CommandInfo struct {
	ApplicationCommand *discordgo.ApplicationCommand `json:"application_command"`
	Implementations    map[string][]interface{}      `json:"implementations"`
}

CommandInfo contains the parsed application command structure of a command as well as additional method implementations. This also includes external implementations aside from the Command interface.

func (CommandInfo) String added in v0.7.0 

func (c CommandInfo) String() string

String returns the parsed JSON data of the CommandInfo.

type CommandInfoList added in v0.7.0 

type CommandInfoList []*CommandInfo

CommandInfoList is a slice of CommandInfo elements.

func (CommandInfoList) String added in v0.7.0 

func (c CommandInfoList) String() string

String returns the parsed JSON data of the CommandInfoList.

type CommandOption added in v0.3.0 

type CommandOption struct {
	*discordgo.ApplicationCommandInteractionDataOption
}

CommandOption wraps a ApplicationCommandInteractionDataOption to provide additional functionalities and method overrides.

func (*CommandOption) ChannelValue added in v0.3.0 

func (o *CommandOption) ChannelValue(ctx Context) *discordgo.Channel

ChannelValue is a utility function for casting option value to channel object.

The object is taken from the specified state instance.

func (*CommandOption) RoleValue added in v0.3.0 

func (o *CommandOption) RoleValue(ctx Context) *discordgo.Role

RoleValue is a utility function for casting option value to role object.

The object is taken from the specified state instance.

func (*CommandOption) StringValue added in v0.8.0 

func (o *CommandOption) StringValue() (v string)

StringValue is a utility function for casting option value to string.

Because you can not pass multiline string entries to slash commands, this converts `\n` in a message to an actual line break.

func (*CommandOption) UserValue added in v0.3.0 

func (o *CommandOption) UserValue(ctx Context) *discordgo.User

UserValue is a utility function for casting option value to user object.

The object is taken from the specified state instance.

type CommandOptions added in v0.2.0 

type CommandOptions []*discordgo.ApplicationCommandInteractionDataOption

CommandOptions provides additional functionailities to an array of ApplicationCommandInteractionDataOptions.

func (CommandOptions) Get added in v0.2.0 

func (co CommandOptions) Get(i int) *CommandOption

Get safely returns an options from command options by index.

func (CommandOptions) GetByName added in v0.2.0 

func (co CommandOptions) GetByName(name string) (opt *CommandOption)

GetByName returns an option by name.

This should only be used on required options.

func (CommandOptions) GetByNameOptional added in v0.2.0 

func (co CommandOptions) GetByNameOptional(name string) (opt *CommandOption, ok bool)

GetByNameOptional returns an option by name. If the option with the name does not exist, the returned value for ok is false.

This should be used for non-required options.

func (CommandOptions) Options added in v0.2.0 

func (co CommandOptions) Options(i int) CommandOptions

Options returns wrapped underlying options of a sub command by ID.

type ComponentAssembler added in v0.15.0 

type ComponentAssembler interface {

	// AddActionsRow adds an Action Row component to
	// the message. Use the builder passed by the
	// build function to assemble the components of
	// the Action Row.
	//
	// If you pass once as `true`, after the first
	// interaction inside the Action Row, all handlers
	// of the Action Row children are removed as well
	// as the Action Row component itself from the message.
	AddActionsRow(build func(b ComponentAssembler), once ...bool) ComponentAssembler

	// Add appends the passed message component to the
	// message with the given handler called on
	// interaction with the component.
	//
	// If you pass once as `true`, the handler is
	// removed after interaction with the component
	// as well as the component itself from the message.
	Add(
		component discordgo.MessageComponent,
		handler ComponentHandlerFunc,
		once ...bool,
	) ComponentAssembler
}

ComponentAssembler helps to build the message component tree.

type ComponentBuilder added in v0.15.0 

type ComponentBuilder struct {
	// contains filtered or unexported fields
}

ComponentBuilder helps to build the message component tree, attaches the components to the given message and registers the interaction handlers for the given components.

func (*ComponentBuilder) Add added in v0.15.0 

func (t *ComponentBuilder) Add(
	component discordgo.MessageComponent,
	handler ComponentHandlerFunc,
	once ...bool,
) *ComponentBuilder

Add appends the passed message component to the message with the given handler called on interaction with the component.

If you pass once as `true`, the handler is removed after interaction with the component as well as the component itself from the message.

func (*ComponentBuilder) AddActionsRow added in v0.15.0 

func (t *ComponentBuilder) AddActionsRow(build func(b ComponentAssembler), once ...bool) *ComponentBuilder

AddActionsRow adds an Action Row component to the message. Use the builder passed by the build function to assemble the components of the Action Row.

If you pass once as `true`, after the first interaction inside the Action Row, all handlers of the Action Row children are removed as well as the Action Row component itself from the message.

func (*ComponentBuilder) Build added in v0.15.0 

func (t *ComponentBuilder) Build() (unreg func() error, err error)

Build attaches the registered messgae components to the specified message and registers the interaction handlers to the handler registry.

It returns an unregister function which can be called to remove all message components appendet and and all interaction handler registered with this builder.

func (*ComponentBuilder) Condition added in v0.17.1 

func (t *ComponentBuilder) Condition(cond ComponentHandlerFunc) *ComponentBuilder

Condition sets a condition handler which needs to be met so that the component handler is activated.

type ComponentContext added in v0.15.0 

type ComponentContext interface {
	ContextResponder

	// GetData returns the underlying
	// MessageComponentInteractionData.
	GetData() discordgo.MessageComponentInteractionData

	// OpenModal opens a new modal with the given
	// title, content and components built with the
	// passed build function. A channel is returned
	// which will receive a ModalContext when the user
	// has interacted with the modal.
	OpenModal(
		title string,
		content string,
		build func(b ComponentAssembler),
	) (<-chan ModalContext, error)
}

ComponentContext gives access to the underlying MessageComponentInteractionData and gives the ability to open a Modal afterwards.

type ComponentHandler added in v0.15.0 

type ComponentHandler struct {
	// contains filtered or unexported fields
}

ComponentHandler keeps a registry of component handler callbacks to be executed when a given component has been interacted with.

func NewComponentHandler added in v0.15.0 

func NewComponentHandler(ken *Ken) *ComponentHandler

NewComponentHandler returns a new instance of ComponentHandler using the given instance of Ken.

func (*ComponentHandler) Add added in v0.15.0 

func (t *ComponentHandler) Add(messageId, channelId string) *ComponentBuilder

Add returns a new ComponentBuilder which attaches the added components to the given message by messageId and channelId on build.

func (*ComponentHandler) AppendToMessage added in v0.15.0 

func (t *ComponentHandler) AppendToMessage(
	messageId string,
	channelId string,
	components []discordgo.MessageComponent,
) error

AppendToMessage edits the given message by messageId and channelId which adds the passed message components to the message.

func (*ComponentHandler) Register added in v0.15.0 

func (t *ComponentHandler) Register(customId string, handler ComponentHandlerFunc) func()

Register registers a raw ComponentHandlerFunc which is fired when the component with the specified customId has been interacted with.

Te returned function unregisters the specified handler from the registry but does not remove the added message components from the message.

Registering a handler twice on the smae customId overwrites the previously registered handler function.

func (*ComponentHandler) Unregister added in v0.15.0 

func (t *ComponentHandler) Unregister(customId ...string)

Unregister removes one or more handlers from the registry set to the given customId(s) of the message component(s).

func (*ComponentHandler) UnregisterDiscordHandler added in v0.15.0 

func (t *ComponentHandler) UnregisterDiscordHandler()

UnregisterDiscordHandler removes the Discord event handler function from the internal DiscordGo Session.

type ComponentHandlerFunc added in v0.15.0 

type ComponentHandlerFunc func(ctx ComponentContext) bool

ComponentHandleFunc is the handler function for message component interactions. It is getting passed a ComponentContext which contians the interaction event data and can be used to respond to the interaction.

A boolean is returned to indicate the success of the execution of the handler.

type Context added in v0.13.0 

type Context interface {
	ContextResponder
	ObjectProvider
	safepool.ResetState

	// Channel tries to fetch the channel object from the contained
	// channel ID using the specified state manager.
	Channel() (*discordgo.Channel, error)

	// Channel tries to fetch the guild object from the contained
	// guild ID using the specified state manager.
	Guild() (*discordgo.Guild, error)

	// Options returns the application command data options
	// with additional functionality methods.
	Options() CommandOptions

	// SlashCommand returns the contexts Command as a
	// SlashCommand interface.
	SlashCommand() (cmd SlashCommand, ok bool)

	// UserCommand returns the contexts Command as a
	// UserCommand interface.
	UserCommand() (cmd UserCommand, ok bool)

	// MessageCommand returns the contexts Command as a
	// MessageCommand interface.
	MessageCommand() (cmd MessageCommand, ok bool)

	// HandleSubCommands takes a list of sub command handles.
	// When the command is executed, the options are scanned
	// for the sib command calls by their names. If one of
	// the registered sub commands has been called, the specified
	// handler function is executed.
	//
	// If the call occured, the passed handler function is
	// getting passed the scoped sub command Ctx.
	//
	// The SubCommandCtx passed must not be stored or used
	// after command execution.
	HandleSubCommands(handler ...CommandHandler) (err error)

	// GetKen returns the root instance of Ken.
	GetKen() *Ken

	// GetCommand returns the command instance called.
	GetCommand() Command
}

Context defines the implementation of an interaction command context passed to the command handler.

type ContextResponder added in v0.15.0 

type ContextResponder interface {

	// Respond to an interaction event with the given
	// interaction response payload.
	//
	// When an interaction has already been responded to,
	// the response will be edited instead on execution.
	Respond(r *discordgo.InteractionResponse) (err error)

	// RespondMessage is shorthand for Respond with a simple
	// message as response content.
	RespondMessage(message string) (err error)

	// RespondEmbed is shorthand for Respond with an
	// embed payload as passed.
	RespondEmbed(emb *discordgo.MessageEmbed) (err error)

	// RespondError is shorthand for RespondEmbed with an
	// error embed as message with the passed content and
	// title.
	RespondError(content, title string) (err error)

	// FollowUp creates a follow up message to the
	// interaction event and returns a FollowUpMessage
	// object containing the created message as well as
	// an error instance, if an error occurred.
	//
	// This way it allows to be chained in one call with
	// subsequent FollowUpMessage method calls.
	FollowUp(wait bool, data *discordgo.WebhookParams) (fumb *FollowUpMessageBuilder)

	// FollowUpEmbed is shorthand for FollowUp with a simple
	// message as response content.
	FollowUpMessage(message string) (fumb *FollowUpMessageBuilder)

	// FollowUpEmbed is shorthand for FollowUp with an
	// embed payload as passed.
	FollowUpEmbed(emb *discordgo.MessageEmbed) (fumb *FollowUpMessageBuilder)

	// FollowUpError is shorthand for FollowUpEmbed with an
	// error embed as message with the passed content and
	// title.
	FollowUpError(content, title string) (fumb *FollowUpMessageBuilder)

	// Defer is shorthand for Respond with an InteractionResponse
	// of the type InteractionResponseDeferredChannelMessageWithSource.
	//
	// It should be used when the interaction response can not be
	// instantly returned.
	Defer() (err error)

	// GetEphemeral returns the current emphemeral state
	// of the command invokation.
	GetEphemeral() bool

	// SetEphemeral sets the emphemeral state of the command
	// invokation.
	//
	// Ephemeral can be set to true which will
	// send all subsequent command responses
	// only to the user which invoked the command.
	SetEphemeral(v bool)

	// GetSession returns the current Discordgo session instance.
	GetSession() *discordgo.Session

	// GetEvent returns the InteractionCreate event instance which
	// invoked the interaction command.
	GetEvent() *discordgo.InteractionCreate

	// User returns the User object of the executor either from
	// the events User object or from the events Member object.
	User() (u *discordgo.User)
}

ContextResponder defines the implementation of an interaction context with functionalities to respond to the interaction, to set the ephemeral state and to retrieve the nested session and event.

type Ctx 

type Ctx struct {
	ObjectMap

	// Command provides the called command instance.
	Command Command
	// contains filtered or unexported fields
}

Ctx holds the invokation context of a command.

The Ctx must not be stored or used after command execution.

func (*Ctx) Channel 

func (c *Ctx) Channel() (*discordgo.Channel, error)

Channel tries to fetch the channel object from the contained channel ID using the specified state manager.

func (*Ctx) Defer 

func (c *Ctx) Defer() (err error)

func (*Ctx) FollowUp 

func (c *Ctx) FollowUp(wait bool, data *discordgo.WebhookParams) (fumb *FollowUpMessageBuilder)

func (*Ctx) FollowUpEmbed 

func (c *Ctx) FollowUpEmbed(emb *discordgo.MessageEmbed) (fumb *FollowUpMessageBuilder)

func (*Ctx) FollowUpError 

func (c *Ctx) FollowUpError(content, title string) (fumb *FollowUpMessageBuilder)

func (*Ctx) FollowUpMessage added in v0.20.0 

func (c *Ctx) FollowUpMessage(message string) (fumb *FollowUpMessageBuilder)

func (*Ctx) Get 

func (c *Ctx) Get(key string) (v interface{})

Get either returns an instance from the internal object map - if existent. Otherwise, the object is looked up in the specified dependency provider, if available. When no object was found in either of both maps, nil is returned.

func (*Ctx) GetCommand added in v0.13.0 

func (c *Ctx) GetCommand() Command

GetCommand returns the command instance called.

func (*Ctx) GetEphemeral added in v0.13.0 

func (c *Ctx) GetEphemeral() bool

func (*Ctx) GetEvent added in v0.13.0 

func (c *Ctx) GetEvent() *discordgo.InteractionCreate

func (*Ctx) GetKen added in v0.13.0 

func (c *Ctx) GetKen() *Ken

GetKen returns the root instance of Ken.

func (*Ctx) GetSession added in v0.13.0 

func (c *Ctx) GetSession() *discordgo.Session

func (*Ctx) Guild 

func (c *Ctx) Guild() (*discordgo.Guild, error)

Guild tries to fetch the guild object from the contained guild ID using the specified state manager.

func (*Ctx) HandleSubCommands added in v0.6.0 

func (c *Ctx) HandleSubCommands(handler ...CommandHandler) (err error)

HandleSubCommands takes a list of sub command handles. When the command is executed, the options are scanned for the sib command calls by their names. If one of the registered sub commands has been called, the specified handler function is executed.

If the call occured, the passed handler function is getting passed the scoped sub command Ctx.

The SubCommandCtx passed must not be stored or used after command execution.

func (*Ctx) MessageCommand added in v0.11.0 

func (c *Ctx) MessageCommand() (cmd MessageCommand, ok bool)

MessageCommand returns the contexts Command as a MessageCommand interface.

func (*Ctx) Options added in v0.2.0 

func (c *Ctx) Options() CommandOptions

Options returns the application command data options with additional functionality methods.

func (*Ctx) ResetState added in v0.19.0 

func (c *Ctx) ResetState()

func (*Ctx) Respond 

func (c *Ctx) Respond(r *discordgo.InteractionResponse) (err error)

func (*Ctx) RespondEmbed added in v0.10.0 

func (c *Ctx) RespondEmbed(emb *discordgo.MessageEmbed) (err error)

func (*Ctx) RespondError added in v0.10.0 

func (c *Ctx) RespondError(content, title string) (err error)

func (*Ctx) RespondMessage added in v0.19.0 

func (c *Ctx) RespondMessage(message string) (err error)

func (*Ctx) SetEphemeral added in v0.13.0 

func (c *Ctx) SetEphemeral(v bool)

func (*Ctx) SlashCommand added in v0.11.0 

func (c *Ctx) SlashCommand() (cmd SlashCommand, ok bool)

SlashCommand returns the contexts Command as a SlashCommand interface.

func (*Ctx) User 

func (c *Ctx) User() (u *discordgo.User)

User returns the User object of the executor either from the events User object or from the events Member object.

func (*Ctx) UserCommand added in v0.11.0 

func (c *Ctx) UserCommand() (cmd UserCommand, ok bool)

UserCommand returns the contexts Command as a UserCommand interface.

type DmCapable 

type DmCapable interface {
	// IsDmCapable returns true if the command can
	// be used in DMs.
	IsDmCapable() bool
}

DmCapable extends a command to specify if it is able to be executed in DMs or not.

type EmbedColors 

type EmbedColors struct {
	// Default defines the default embed color used when
	// no other color is specified.
	Default int
	// Error specifies the embed color of error embeds.
	Error int
}

EmbedColors lets you define custom colors for embeds.

type EphemeralCommand added in v0.12.1 

type EphemeralCommand struct{}

EphemeralCommand can be added to your command to make all command responses ephemeral. This means, that all responses to the command from the bot will only be received by the sender of the command.

func (EphemeralCommand) ResponsePolicy added in v0.12.1 

func (EphemeralCommand) ResponsePolicy() ResponsePolicy

type FollowUpMessage 

type FollowUpMessage struct {
	*discordgo.Message

	// Error contains the error instance of
	// error occurrences during method execution.
	Error error
	// contains filtered or unexported fields
}

FollowUpMessage wraps an interaction follow up message and collected errors.

func (*FollowUpMessage) AddComponents added in v0.15.0 

func (m *FollowUpMessage) AddComponents() *ComponentBuilder

AddComponents returns a new component builder to add message components with handlers to the FollowUpMessage.

func (*FollowUpMessage) Delete 

func (m *FollowUpMessage) Delete() (err error)

Delete removes the follow up message.

func (*FollowUpMessage) DeleteAfter 

func (m *FollowUpMessage) DeleteAfter(d time.Duration) *FollowUpMessage

DeleteAfter queues a deletion of the follow up message after the specified duration.

func (*FollowUpMessage) Edit 

func (m *FollowUpMessage) Edit(data *discordgo.WebhookEdit) (err error)

Edit overwrites the given follow up message with the data specified.

func (*FollowUpMessage) EditEmbed added in v0.7.1 

func (m *FollowUpMessage) EditEmbed(emb *discordgo.MessageEmbed) (err error)

EditEmbed is shorthand for edit with the passed embed as WebhookEdit data.

func (*FollowUpMessage) HasError added in v0.15.0 

func (m *FollowUpMessage) HasError() bool

HasError returns true if the value of Error is not nil.

func (*FollowUpMessage) UnregisterComponentHandlers added in v0.18.0 

func (m *FollowUpMessage) UnregisterComponentHandlers() error

UnregisterComponentHandlers removes all handlers of attached componets from the register.

type FollowUpMessageBuilder added in v0.18.0 

type FollowUpMessageBuilder struct {
	// contains filtered or unexported fields
}

FollowUpMessageBuilder builds a followup message interaction response.

func (*FollowUpMessageBuilder) AddComponents added in v0.18.0 

func (b *FollowUpMessageBuilder) AddComponents(cb func(*ComponentBuilder)) *FollowUpMessageBuilder

AddComponents is getting passed a builder function where you can attach message components and handlers which will be applied to the followup message when sent.

func (*FollowUpMessageBuilder) Send added in v0.18.0 

func (b *FollowUpMessageBuilder) Send() *FollowUpMessage

Send builds the followup message and sends it as response to the interaction.

type GuildScopedCommand added in v0.15.0 

type GuildScopedCommand interface {
	Guild() string
}

GuildScopedCommand can be implemented by your commands to scope them to specific guilds.

The command then will be only registered on the guild returned by the Guild method.

type IKen added in v0.17.0 

type IKen interface {
	Components() *ComponentHandler
	GetCommandInfo(keyTransformer ...KeyTransformerFunc) (cis CommandInfoList)
	RegisterCommands(cmds ...Command) (err error)
	RegisterMiddlewares(mws ...interface{}) (err error)
	Session() *discordgo.Session
	Unregister() (err error)
}

type Ken 

type Ken struct {
	// contains filtered or unexported fields
}

Ken is the handler to register, manage and life-cycle commands as well as middlewares.

func New 

func New(s *discordgo.Session, options ...Options) (k *Ken, err error)

New initializes a new instance of Ken with the passed discordgo Session s and optional Options.

If no options are passed, default parameters will be applied.

func (*Ken) Components added in v0.15.0 

func (k *Ken) Components() *ComponentHandler

Components returns the component handler.

func (*Ken) GetCommandInfo added in v0.7.0 

func (k *Ken) GetCommandInfo(keyTransformer ...KeyTransformerFunc) (cis CommandInfoList)

GetCommandInfo returns a list with information about all registered commands.

This call is defaultly cached after first execution because it uses reflection to inspect external implementations. Because this can be performance straining when the method is called frequently, the result is cached until the number of commands changes.

If you want to disable this behavior, you can set Config.DisableCommandInfoCache to true on intializing Ken.

func (*Ken) RegisterCommands 

func (k *Ken) RegisterCommands(cmds ...Command) (err error)

RegisterCommands registers the passed commands to the command register.

Keep in mind that commands are registered by Name, so there can be only one single command per name.

func (*Ken) RegisterMiddlewares 

func (k *Ken) RegisterMiddlewares(mws ...interface{}) (err error)

RegisterMiddlewares allows to register passed commands to the middleware callstack.

Therefore, you can register MiddlewareBefore, which is called before the command handler is executed, or MiddlewareAfter, which is called directly after the command handler has been called. Of course, you can also implement both interfaces in the same middleware.

The middleware call order is determined by the order of middleware registration in each area ('before' or 'after').

func (*Ken) Session added in v0.16.0 

func (k *Ken) Session() *discordgo.Session

Session returns the internal Discordgo session.

func (*Ken) Unregister 

func (k *Ken) Unregister() (err error)

Unregister should be called to cleanly unregister all registered slash commands from the discord backend.

This can be skipped if you are using a CommandStore.

type KeyTransformerFunc added in v0.17.0 

type KeyTransformerFunc func(string) string

type MessageCommand added in v0.11.0 

type MessageCommand interface {
	Command

	// TypeMessage is used to differenciate between
	// UserCommand and MessageCommand which have
	// the same structure otherwise.
	//
	// This method must only be implemented and
	// will never be called by ken, so it can be
	// completely empty.
	TypeMessage()
}

MessageCommand defines a callable message command.

type MessageComponent added in v0.17.0 

type MessageComponent struct {
	discordgo.MessageComponent
}

func (MessageComponent) GetValue added in v0.17.0 

func (t MessageComponent) GetValue() string

func (MessageComponent) IsEmpty added in v0.17.0 

func (t MessageComponent) IsEmpty() bool

type Middleware 

type Middleware interface {
	MiddlewareBefore
	MiddlewareAfter
}

Middleware combines MiddlewareBefore and MiddlewareAfter.

type MiddlewareAfter 

type MiddlewareAfter interface {
	// After is called after a command has been executed.
	//
	// It is getting passed the Ctx which was also passed
	// to the command Run handler. Also, the method is
	// getting passed potential errors which were returned
	// from the executed command to be custom handled.
	//
	// The error returned is finally passed to the
	// OnCommandError handler.
	After(ctx *Ctx, cmdError error) (err error)
}

MiddlewareAfter specifies a middleware which is called after the execution of a command.

type MiddlewareBefore 

type MiddlewareBefore interface {
	// Before is called before a command is executed.
	// It is getting passed the same context as which
	// will be passed to the command. So you are able
	// to attach or alter data of the context.
	//
	// Ctx contains an ObjectMap which can be used to
	// pass data to the command.
	//
	// The method returns a bool which specifies if
	// the subsequent command should be executed. If
	// it is set to false, the execution will be
	// canceled.
	//
	// The error return value is either bubbled up to
	// the OnCommandError, when next is set to false.
	// Otherwise, the error is passed to OnCommandError
	// but the execution continues.
	Before(ctx *Ctx) (next bool, err error)
}

MiddlewareBefore specifies a middleware which is called before the execution of a command.

type ModalContext added in v0.17.0 

type ModalContext interface {
	ContextResponder

	// GetData returns the underlying
	// ModalSubmitInteractionData.
	GetData() discordgo.ModalSubmitInteractionData

	// GetComponentByID tries to find a message component
	// by CustomID in the response data and returns it
	// wrapped into MessageComponent.
	//
	// The returned MessageComponent will contain a nil
	// value for the wrapped discordgo.MessageComponent
	// if it could not be found in the response.
	//
	// Subsequent method calls to MessageComponent will
	// not fail though to ensure the ability to chain
	// method calls.
	GetComponentByID(customId string) MessageComponent
}

ModalContext provides access to the underlying ModalSubmitInteractionData and some utility methods to access component data from the response.

type ModalHandlerFunc added in v0.17.0 

type ModalHandlerFunc func(ctx ModalContext) bool

type ObjectInjector 

type ObjectInjector interface {
	// Set stores the given object by given
	// key.
	Set(key string, obj interface{})
}

ObjectInjector specifies an instance which allows storing an object by string key.

type ObjectMap 

type ObjectMap interface {
	ObjectProvider
	ObjectInjector

	// Purge cleans all stored objects and
	// keys from the provider.
	Purge()
}

ObjectMap combines ObjectProvider and ObjectInjector.

type ObjectProvider 

type ObjectProvider interface {
	// Get returns a stored object by its
	// key, if existent.
	Get(key string) interface{}
}

ObjectProvider specifies an instance providing objects by string key.

type Options 

type Options struct {
	// State specifies the state manager to be used.
	// When not specified, the default discordgo state
	// manager is used.
	State state.State
	// CommandStore specifies a storage instance to
	// cache created commands.
	CommandStore store.CommandStore
	// DependencyProvider can be used to inject dependencies
	// to be used in a commands or middlewares Ctx by
	// a string key.
	DependencyProvider ObjectProvider
	// EmbedColors lets you define custom colors for embeds.
	EmbedColors EmbedColors
	// DisableCommandInfoCache disabled caching
	// the result of Ken#GetCommandInfo() after
	// first call of the method.
	//
	// Only disable if you change information of
	// a command during runtime.
	DisableCommandInfoCache bool
	// OnSystemError is called when a recoverable
	// system error occurs inside Ken's lifecycle.
	OnSystemError func(context string, err error, args ...interface{})
	// OnCommandError is called when an error occurs
	// during middleware or command execution.
	OnCommandError func(err error, ctx *Ctx)
	// OnEventError is called when any other user
	// event based error occured.
	OnEventError func(context string, err error)
}

Options holds configurations for Ken.

type ResponsePolicy added in v0.12.1 

type ResponsePolicy struct {
	// When set to true, the command response will
	// only be received by the sender of the command.
	//
	// This sets the `Ephemeral` flag of the `Context`
	// to true before any middleware is invoked. So,
	// you are able to modify the ephemeral flag either
	// in your middleware or directly in your command
	// logic, if you desire.
	Ephemeral bool
}

ResponsePolicy describes rules for context followups and responses.

type ResponsePolicyCommand added in v0.12.1 

type ResponsePolicyCommand interface {
	ResponsePolicy() ResponsePolicy
}

ResponsePolicyCommand defines a command which provides a ResponsePolicy.

type SlashCommand added in v0.11.0 

type SlashCommand interface {
	Command

	// Version returns the commands semantic version.
	Version() string

	// Options returns an array of application
	// command options.
	Options() []*discordgo.ApplicationCommandOption
}

SlashCommand defines a callable slash command.

type SubCommandContext added in v0.17.0 

type SubCommandContext interface {
	Context

	// GetSubCommandName returns the sub command
	// name which has been invoked.
	GetSubCommandName() string
}

SubCommandContext wraps the current command Context and with the called sub command name and scopes the command options to the options of the called sub command.

The SubCommandCtx must not be stored or used after command execution.

type SubCommandGroup added in v0.20.0 

type SubCommandGroup struct {
	Name       string
	SubHandler []CommandHandler
}

SubCommandGroup is the handler used to group sub commands.

func (SubCommandGroup) OptionName added in v0.20.0 

func (t SubCommandGroup) OptionName() string

func (SubCommandGroup) RunHandler added in v0.20.0 

func (t SubCommandGroup) RunHandler(ctx SubCommandContext) error

func (SubCommandGroup) Type added in v0.20.0 

func (t SubCommandGroup) Type() discordgo.ApplicationCommandOptionType

type SubCommandHandler added in v0.5.0 

type SubCommandHandler struct {
	Name string
	Run  func(ctx SubCommandContext) error
}

SubCommandHandler is the handler function used to handle sub command calls.

func (SubCommandHandler) OptionName added in v0.20.0 

func (t SubCommandHandler) OptionName() string

func (SubCommandHandler) RunHandler added in v0.20.0 

func (t SubCommandHandler) RunHandler(ctx SubCommandContext) error

func (SubCommandHandler) Type added in v0.20.0 

func (t SubCommandHandler) Type() discordgo.ApplicationCommandOptionType

type UserCommand added in v0.11.0 

type UserCommand interface {
	Command

	// TypeUser is used to differenciate between
	// UserCommand and MessageCommand which have
	// the same structure otherwise.
	//
	// This method must only be implemented and
	// will never be called by ken, so it can be
	// completely empty.
	TypeUser()
}

UserCommand defines a callable user command.

Source Files

View all Source files

Directories

Path Synopsis
examples
autocomplete
autocomplete/commands
basic
basic/commands
cmdinfo
cmdinfo/commands
components
components/commands
guildscoped
guildscoped/commands
help
help/commands
middlewares
middlewares/commands
middlewares/middlewares
modals
modals/commands
ratelimit
ratelimit/commands
subcommandgroups
subcommandgroups/commands
subcommands
subcommands/commands
usermsgcommands
usermsgcommands/commands
middlewares
cmdhelp
ratelimit
ratelimit/v2

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.