ken

README

ken  

剣 (ken - japanese for Sword) - A prototype, object-oriented 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.

---

© 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 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) Respond(r *discordgo.InteractionResponse) error
  • func (c *Ctx) User() (u *discordgo.User)
• type DmCapable
• type EmbedColors
• type FollowUpMessage
  • func (m *FollowUpMessage) Delete() (err error)
  • func (m *FollowUpMessage) DeleteAfter(d time.Duration) *FollowUpMessage
  • func (m *FollowUpMessage) Edit(data *discordgo.WebhookEdit) (err error)
• type Ken
  • func New(s *discordgo.Session, options ...Options) (k *Ken)
  • func (k *Ken) RegisterCommands(cmds ...Command) (err error)
  • func (k *Ken) RegisterMiddlewares(mws ...interface{}) (err error)
  • func (k *Ken) Unregister() (err error)
• type Middleware
• type MiddlewareAfter
• type MiddlewareBefore
• type ObjectInjector
• type ObjectMap
• type ObjectProvider
• type Options

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")
)

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 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

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)

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

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) Guild

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

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

func (*Ctx) Respond

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

Respond to an interaction event with the given interaction response payload.

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.

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

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

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

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) Unregister

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

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

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
	// 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.