README
¶
ken 
⚠️ Attention
This package is still in a very early state of development and the API might get breaking changes until first official release.
剣 (ken - japanese for Sword) - A cutting edge (haha), prototype, object-oriented and highly modular slash command handler for Discordgo.
This work-in-progress slash command handler is designed to be used in future versions of shinpuru.
If you are interested how to use this package, see the basic example. In this example, you can see how to use middlewares.
Example Usage
package main
// imports ...
type TestCommand struct{}
var _ ken.Command = (*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) Type() discordgo.ApplicationCommandType {
return discordgo.ChatApplicationCommand
}
func (c *TestCommand) Options() []*discordgo.ApplicationCommandOption {
return []*discordgo.ApplicationCommandOption{}
}
func (c *TestCommand) Run(ctx *ken.Ctx) (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.
© 2021 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 ¶
- Variables
- type Command
- type CommandOption
- type CommandOptions
- type Ctx
- func (c *Ctx) Channel() (*discordgo.Channel, error)
- func (c *Ctx) Defer() (err error)
- func (c *Ctx) FollowUp(wait bool, data *discordgo.WebhookParams) (fum *FollowUpMessage)
- func (c *Ctx) FollowUpEmbed(emb *discordgo.MessageEmbed) (fum *FollowUpMessage)
- func (c *Ctx) FollowUpError(content, title string) (fum *FollowUpMessage)
- func (c *Ctx) Get(key string) (v interface{})
- func (c *Ctx) Guild() (*discordgo.Guild, error)
- func (c *Ctx) HandleSubCommands(handler ...SubCommandHandler) (err error)
- func (c *Ctx) Options() CommandOptions
- func (c *Ctx) Respond(r *discordgo.InteractionResponse) (err error)
- func (c *Ctx) User() (u *discordgo.User)
- type DmCapable
- type EmbedColors
- type FollowUpMessage
- type Ken
- type Middleware
- type MiddlewareAfter
- type MiddlewareBefore
- type ObjectInjector
- type ObjectMap
- type ObjectProvider
- type Options
- type SubCommandCtx
- type SubCommandHandler
Constants ¶
This section is empty.
Variables ¶
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 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.
Description() string
// Version returns the commands semantic version.
Version() string
// Type returns the commands command type.
Type() discordgo.ApplicationCommandType
// Options returns an array of application
// command options.
Options() []*discordgo.ApplicationCommandOption
// 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 *Ctx) (err error)
}
Command defines a callable slash command.
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 *Ctx) *discordgo.Channel
ChannelValue is a utility function for casting option value to channel 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 Ctx ¶
type Ctx struct {
ObjectMap
// Session holds the discordgo session instance.
Session *discordgo.Session
// Event provides the InteractionCreate event
// instance.
Event *discordgo.InteractionCreate
// Command provides the called command instance.
Command Command
// contains filtered or unexported fields
}
Ctx holds the invokation context of a command.
func (*Ctx) Channel ¶
Channel tries to fetch the channel object from the contained channel ID using the specified state manager.
func (*Ctx) Defer ¶
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.
func (*Ctx) FollowUp ¶
func (c *Ctx) FollowUp(wait bool, data *discordgo.WebhookParams) (fum *FollowUpMessage)
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.
func (*Ctx) FollowUpEmbed ¶
func (c *Ctx) FollowUpEmbed(emb *discordgo.MessageEmbed) (fum *FollowUpMessage)
FollowUpEmbed is shorthand for FollowUp with an embed payload as passed.
func (*Ctx) FollowUpError ¶
func (c *Ctx) FollowUpError(content, title string) (fum *FollowUpMessage)
FollowUpError is shorthand for FollowUpEmbed with an error embed as message with the passed content and title.
func (*Ctx) Get ¶
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) Guild ¶
Channel 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 ...SubCommandHandler) (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.
func (*Ctx) Options ¶ added in v0.2.0
func (c *Ctx) Options() CommandOptions
Options returns the application command data options with additional functionality methods.
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 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) 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.
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 ¶
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) RegisterCommands ¶
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 ¶
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) Unregister ¶
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 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 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
// 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)
}
Options holds configurations for Ken.
type SubCommandCtx ¶ added in v0.5.0
SubCommandCtx wraps the current command Ctx and with the called sub command name and scopes the command options to the options of the called sub command.
func (*SubCommandCtx) Options ¶ added in v0.5.0
func (c *SubCommandCtx) Options() CommandOptions
Options returns the options array of the called sub command.
type SubCommandHandler ¶ added in v0.5.0
type SubCommandHandler struct {
Name string
Run func(ctx *SubCommandCtx) error
}
SubCommandHandler is the handler function used to handle sub command calls.
Source Files
Directories