astral

package module
v2.0.0-...-6a7c878 Latest Latest
Warning

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

 Go to latest Published: Jan 30, 2024 License: ISC Imports: 17 Imported by: 0

README

Astral

A command router for discordgo with a few twists.

Heavily inspired by dgrouter, but based off the command system used in Astra.

Importing/Installing

go get meow.tf/astral

import "meow.tf/astral/router"

Signatures

Astral supports signatures, which are a command and arguments defined in a single string.

Example:

command <something> <#channel> [optional]

This defines a command command, with required argument something, channel argument channel, and optional optional.

Middleware

Each route can have middleware assigned to back out/stop execution of a command. This is useful for injecting parameters, checking conditions (Permissions, NSFW), etc.

See the "middleware" folder for examples.

Examples

A basic example showing the usage and middleware is available under examples/basic

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNoUser    = errors.New("no user found")
	ErrNoChannel = errors.New("no channel found")
	ErrNoRole    = errors.New("no role found")
)
View Source 
var (
	ErrUnknownOption   = errors.New("unknown option")
	ErrNotAutocomplete = errors.New("option is not registered to autocomplete")
)
View Source 
var (
	ErrEmptyText = errors.New("text is empty")
)
View Source 
var (
	UsageError = errors.New("usage")
)

Functions

func RegisterCommands 

func RegisterCommands(r *Route, s *state.State, appID discord.AppID) ([]discord.Command, error)

RegisterCommands registers all sub routes as interaction/slash commands

func RegisterGuildCommands 

func RegisterGuildCommands(r *Route, s *state.State, appID discord.AppID, guildID discord.GuildID) ([]discord.Command, error)

RegisterGuildCommands registers all sub routes as interaction/slash commands to a guild

Types

type Argument 

type Argument struct {
	Index       int
	Name        string
	Description string
	Required    bool
	Type        ArgumentType
	Choices     []StringChoice
	Min         interface{}
	Max         interface{}
	// contains filtered or unexported fields
}

Argument type contains defined arguments, parsed from the command signature

func (*Argument) Autocomplete 

func (a *Argument) Autocomplete(f AutocompleteHandler) *Argument

Autocomplete registers an autocomplete handler for this argument

type ArgumentType 

type ArgumentType int
const (
	ArgumentTypeBasic ArgumentType = iota
	ArgumentTypeInt
	ArgumentTypeFloat
	ArgumentTypeBool
	ArgumentTypeEmoji
	ArgumentTypeUserMention
	ArgumentTypeChannelMention
	ArgumentTypeRole
)

func (ArgumentType) DiscordType 

func (t ArgumentType) DiscordType() discord.CommandOptionType

DiscordType returns the Discord CommandOptionType for an argument

type AutocompleteChoice 

type AutocompleteChoice struct {
	Name  string
	Value string
}

type AutocompleteHandler 

type AutocompleteHandler func(*Context, discord.AutocompleteOption) []StringChoice

AutocompleteHandler is a handler for autocomplete events.

type Context 

type Context struct {
	*VariableBag

	Session        *state.State
	Event          *gateway.MessageCreateEvent
	Interaction    *gateway.InteractionCreateEvent
	Guild          *discord.Guild
	Channel        *discord.Channel
	Message        discord.Message
	User           discord.User
	Prefix         string
	Command        string
	ArgumentString string
	Arguments      map[string]interface{}
	ArgumentCount  int
	// contains filtered or unexported fields
}

Context is the base "context" object. It contains all fields that are present on both Messages and Interactions.

func ContextFrom 

func ContextFrom(state *state.State, event *gateway.MessageCreateEvent, r *Route, args []string) (*Context, error)

ContextFrom creates a new MessageContext from the session and event

func ContextFromInteraction 

func ContextFromInteraction(state *state.State, event *gateway.InteractionCreateEvent, r *Route) (*Context, error)

ContextFromInteraction creates a new Context from an interaction event

func (*Context) Acknowledge 

func (c *Context) Acknowledge() error

func (*Context) Arg 

func (c *Context) Arg(name string) string

Arg finds and returns a named argument as a string

func (*Context) BoolArg 

func (c *Context) BoolArg(name string) bool

BoolArg finds and returns a named bool argument

func (*Context) ChannelArg 

func (c *Context) ChannelArg(name string) *discord.Channel

ChannelArg finds and returns a named Channel argument

func (*Context) ChannelArgType 

func (c *Context) ChannelArgType(name string, t discord.ChannelType) *discord.Channel

ChannelArgType finds and returns Channel argument with a specified type

func (*Context) EmojiArg 

func (c *Context) EmojiArg(name string) *discord.Emoji

EmojiArg finds and returns an argument as an emoji

func (*Context) FloatArg 

func (c *Context) FloatArg(name string) float64

FloatArg finds and returns a named float argument

func (*Context) IntArg 

func (c *Context) IntArg(name string) int64

IntArg finds and returns a named int argument

func (*Context) Reply 

func (c *Context) Reply(text string) (*discord.Message, error)

func (*Context) ReplyEmbed 

func (c *Context) ReplyEmbed(embed *discord.Embed) (*discord.Message, error)

func (*Context) ReplyFile 

func (c *Context) ReplyFile(name string, r io.Reader) (*discord.Message, error)

func (*Context) ReplyTo 

func (c *Context) ReplyTo(to discord.UserID, text string) (*discord.Message, error)

func (*Context) Replyf 

func (c *Context) Replyf(format string, a ...interface{}) (*discord.Message, error)

func (*Context) Respond 

func (c *Context) Respond(r Response) (*discord.Message, error)

func (*Context) RoleArg 

func (c *Context) RoleArg(name string) *discord.Role

RoleArg finds and returns a named Role argument

func (*Context) Send 

func (c *Context) Send(text string) (*discord.Message, error)

func (*Context) SendFile 

func (c *Context) SendFile(name string, r io.Reader) (*discord.Message, error)

func (*Context) Sendf 

func (c *Context) Sendf(format string, a ...interface{}) (*discord.Message, error)

func (*Context) Usage 

func (c *Context) Usage(usage ...string) (*discord.Message, error)

func (*Context) UserArg 

func (c *Context) UserArg(name string) *discord.User

UserArg finds and returns a named User argument

type FindOpts 

type FindOpts struct {
	Path      []string
	MatchCase bool
}

FindOpts represents options for FindComplex. Default is just Path in Find.

type Handler 

type Handler func(*Context)

Handler is a command handler.

type InteractionResponder 

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

func (*InteractionResponder) Acknowledge 

func (m *InteractionResponder) Acknowledge() error

func (*InteractionResponder) Reply 

func (m *InteractionResponder) Reply(text string) (*discord.Message, error)

Reply with a user mention

func (*InteractionResponder) ReplyEmbed 

func (m *InteractionResponder) ReplyEmbed(embed *discord.Embed) (*discord.Message, error)

ReplyEmbed replies to a user with an embed object

func (*InteractionResponder) ReplyFile 

func (m *InteractionResponder) ReplyFile(name string, r io.Reader) (*discord.Message, error)

ReplyFile replies to a user with a file object

func (*InteractionResponder) ReplyTo 

func (m *InteractionResponder) ReplyTo(to discord.UserID, text string) (*discord.Message, error)

ReplyTo replies to a specific user

func (*InteractionResponder) Replyf 

func (m *InteractionResponder) Replyf(format string, a ...interface{}) (*discord.Message, error)

Replyf Builds a message and replies with formatted text

func (*InteractionResponder) Respond 

func (m *InteractionResponder) Respond(r Response) (*discord.Message, error)

Respond replies to a user by serializing Response

func (*InteractionResponder) Send 

func (m *InteractionResponder) Send(text string) (*discord.Message, error)

Send text to the originating channel

func (*InteractionResponder) SendFile 

func (m *InteractionResponder) SendFile(name string, r io.Reader) (*discord.Message, error)

SendFile sends a file by name and the data from r

func (*InteractionResponder) Sendf 

func (m *InteractionResponder) Sendf(format string, a ...interface{}) (*discord.Message, error)

Sendf Sends formattable text to the originating channel

func (*InteractionResponder) Usage 

func (m *InteractionResponder) Usage(usage ...string) (*discord.Message, error)

Usage builds and shows command usage

type InvalidValueError 

type InvalidValueError struct {
	Argument string
	Value    interface{}
}

InvalidValueError is an error type thrown when a value is invalid/unknown

func (InvalidValueError) Error 

func (i InvalidValueError) Error() string

Error constructs a string for the error with the argument and value

type MessageResponder 

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

func (*MessageResponder) Acknowledge 

func (m *MessageResponder) Acknowledge() error

func (*MessageResponder) Reply 

func (m *MessageResponder) Reply(text string) (*discord.Message, error)

Reply to a message

func (*MessageResponder) ReplyEmbed 

func (m *MessageResponder) ReplyEmbed(embed *discord.Embed) (*discord.Message, error)

ReplyEmbed replies to a user with an embed object

func (*MessageResponder) ReplyFile 

func (m *MessageResponder) ReplyFile(name string, r io.Reader) (*discord.Message, error)

ReplyFile replies to a user with a file object

func (*MessageResponder) ReplyTo 

func (m *MessageResponder) ReplyTo(to discord.UserID, text string) (*discord.Message, error)

ReplyTo replies to a specific user

func (*MessageResponder) Replyf 

func (m *MessageResponder) Replyf(format string, a ...interface{}) (*discord.Message, error)

Replyf Builds a message and replies with formatted text

func (*MessageResponder) Respond 

func (m *MessageResponder) Respond(r Response) (*discord.Message, error)

Respond replies to a user by serializing Response

func (*MessageResponder) Send 

func (m *MessageResponder) Send(text string) (*discord.Message, error)

Send text to the originating channel

func (*MessageResponder) SendFile 

func (m *MessageResponder) SendFile(name string, r io.Reader) (*discord.Message, error)

SendFile sends a file by name and the data from r

func (*MessageResponder) Sendf 

func (m *MessageResponder) Sendf(format string, a ...interface{}) (*discord.Message, error)

Sendf Sends formattable text to the originating channel

func (*MessageResponder) Usage 

func (m *MessageResponder) Usage(usage ...string) (*discord.Message, error)

Usage builds and shows command usage

type MiddlewareFunc 

type MiddlewareFunc func(Handler) Handler

A middleware handler

type Responder 

type Responder interface {
	Usage(usage ...string) (*discord.Message, error)
	Send(text string) (*discord.Message, error)
	Sendf(format string, a ...interface{}) (*discord.Message, error)
	SendFile(name string, r io.Reader) (*discord.Message, error)
	Reply(text string) (*discord.Message, error)
	Replyf(format string, a ...interface{}) (*discord.Message, error)
	ReplyTo(to discord.UserID, text string) (*discord.Message, error)
	ReplyEmbed(embed *discord.Embed) (*discord.Message, error)
	ReplyFile(name string, r io.Reader) (*discord.Message, error)
	Respond(r Response) (*discord.Message, error)
	Acknowledge() error
}

Responder represents an available responder This can send messages to channels, direct messages, interactions, etc.

type Response 

type Response struct {
	Content string
	Embeds  []discord.Embed
	Files   []sendpart.File
}

type Route 

type Route struct {
	Name                  string
	Usage                 string
	Description           string
	Arguments             map[string]*Argument
	ArgumentCount         int
	RequiredArgumentCount int
	// contains filtered or unexported fields
}

Route type contains information about a route, such as middleware, routes, etc

func New 

func New() *Route

New creates a new, empty route.

func (*Route) Add 

func (r *Route) Add(n *Route) *Route

Add adds a sub route to this route.

func (*Route) Alias 

func (r *Route) Alias(alias string) *Route

Alias adds an alias to the parent route for the current route.

func (*Route) Argument 

func (r *Route) Argument(name string, f func(*Argument)) *Route

Argument is a quick helper that lets you pull a route's argument into a func and modify it.

func (*Route) Autocomplete 

func (r *Route) Autocomplete(name string, f AutocompleteHandler) *Route

Autocomplete is a helper func to pass through autocomplete functions into options

func (*Route) Call 

func (r *Route) Call(ctx *Context) error

Call executes a route. Handlers are called synchronously. Sub-routes will no longer be recursed automatically, and must be found using Find(...)

func (*Route) CallAutocomplete 

func (r *Route) CallAutocomplete(ctx *Context, options []discord.AutocompleteOption) error

CallAutocomplete calls the autocomplete handler for a route's argument

func (*Route) Desc 

func (r *Route) Desc(description string) *Route

Desc sets this route's description

func (*Route) Export 

func (r *Route) Export(export bool) *Route

Export sets the route to be exported to either commands or guild commands.

func (*Route) Find 

func (r *Route) Find(path ...string) *Route

Find a route by arguments

func (*Route) FindAutocomplete 

func (r *Route) FindAutocomplete(parentRoute string, options []discord.AutocompleteOption) (*Route, []discord.AutocompleteOption)

FindAutocomplete finds a route path from an autocomplete interaction

func (*Route) FindComplex 

func (r *Route) FindComplex(opts FindOpts) *Route

FindComplex finds a route by options, including args, case sensitive matching, etc

func (*Route) FindInteraction 

func (r *Route) FindInteraction(parentRoute string, options []discord.CommandInteractionOption) *Route

FindInteraction finds a route path from a command interaction

func (*Route) Group 

func (r *Route) Group(fn func(*Route)) *Route

Group creates a temporary route to use for registering sub routes. All routes will be copied into this route, with middleware applied.

func (*Route) On 

func (r *Route) On(signature string, f Handler) *Route

On adds a handler for a specific command. Signature can be a simple command, or a string like the following: 

command <arg1> <arg2> [arg3] [#channel] [@user]

The library will automatically parse and validate the required arguments. <> means an argument will be required, [] says it's optional As well as required and optional types, you can use # and @ to signify That routes must match a valid user or channel.

func (*Route) Path 

func (r *Route) Path() []string

Path returns the route's full path

func (*Route) RegisterCommand 

func (r *Route) RegisterCommand(s *state.State, appID discord.AppID, guildID discord.GuildID) (*discord.Command, error)

RegisterCommand registers a single command, with sub routes as subcommands.

func (*Route) UpdateCommand 

func (r *Route) UpdateCommand(s *state.State, appID discord.AppID, commandID discord.CommandID, guildID discord.GuildID) (*discord.Command, error)

UpdateCommand registers a single command, with sub routes as subcommands.

func (*Route) Use 

func (r *Route) Use(f ...MiddlewareFunc) *Route

Use applies middleware to this route. All sub-routes will also inherit this middleware.

func (*Route) Validate 

func (r *Route) Validate(ctx *Context) error

Validate checks the context against the Route's defined arguments and ensures all required arguments and types are satisfied.

type StringChoice 

type StringChoice struct {
	Name  string
	Value string
}

StringChoice is a basic wrapper for name/value choices

type VariableBag 

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

func NewVariableBag 

func NewVariableBag() *VariableBag

func (*VariableBag) Get 

func (v *VariableBag) Get(key string) interface{}

Get retrieves a variable from the context

func (*VariableBag) Set 

func (v *VariableBag) Set(key string, d interface{})

Set sets a variable on the context

Source Files

View all Source files

Directories

Path Synopsis
examples
basic
cooldown

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.