v2

README

Sayori

Sayori is a dead simple command router based on discordgo with

• custom guild prefix support
• message parsing
• multiple command aliases
• subcommands
• middlewares

Getting Started

Installing

You can install the latest release of Sayori by using:

go get github.com/pixeltopic/sayori/v2

Then include Sayori in your application:

import sayori "github.com/pixeltopic/sayori/v2"

Usage

package main

import (
	"github.com/bwmarrin/discordgo"
	sayori "github.com/pixeltopic/sayori/v2"
)

func main() {
    dg, err := discordgo.New("Bot " + "<mydiscordtoken>")
    if err != nil {
        return
    }
    
    router := sayori.New(dg)
    
    echo := sayori.NewRoute(&Prefix{}).Do(&Echo{}).On("echo", "e")
    
    router.Has(echo)
    
    err = router.Open()
    if err != nil {
        return
    }
}

See /examples for detailed usage.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE.md file for details

Acknowledgments

• Inspired by rfrouter and dgrouter.

Documentation

Index

• type CmdContext
  • func CmdFromContext(ctx context.Context) *CmdContext
• type CmdParser
• type Commander
• type Middlewarer
• type Prefixer
• type Route
  • func NewRoute(p Prefixer) *Route
  • func (r *Route) Do(c Commander) *Route
  • func (r *Route) Find(subAlias string) *Route
  • func (r *Route) Has(subroutes ...*Route) *Route
  • func (r *Route) HasAlias(a string) bool
  • func (r *Route) IsDefault() bool
  • func (r *Route) On(aliases ...string) *Route
  • func (r *Route) Use(middlewares ...Middlewarer) *Route
• type Router
  • func New(s *discordgo.Session) *Router
  • func (r *Router) Close() error
  • func (r *Router) Has(route *Route)
  • func (r *Router) HasDefault(h interface{})
  • func (r *Router) HasOnce(route *Route)
  • func (r *Router) HasOnceDefault(h interface{})
  • func (r *Router) Open() error

Types

type CmdContext

type CmdContext struct {
	Ses    *discordgo.Session
	Msg    *discordgo.Message
	Prefix string
	Alias  []string
	Args   []string
	Err    error
}

CmdContext is an aux structure for storing invocation values extracted from a given Context to reduce boilerplate.

This need not be manually initialized; simply call CmdFromContext.

func CmdFromContext

func CmdFromContext(ctx context.Context) *CmdContext

CmdFromContext derives all Command invocation values from given Context.

type CmdParser

type CmdParser interface {
	Parse(string) ([]string, error)
}

CmdParser parses the content of a Discord message into a string slice.

Optionally implemented by Commander

type Commander

type Commander interface {
	Handle(ctx context.Context) error
	Resolve(ctx context.Context)
}

Commander is used by a route to handle Discord's Message Create events. https://discord.com/developers/docs/topics/gateway#message-create

Can optionally implement CmdParser, but is not required.

Handle is where a command's business logic should belong.

Resolve is where an error in ctx.Err can be handled, along with any other necessary cleanup. It is run if (custom) parsing fails, middleware fails, or if Handle fails.

type Middlewarer

type Middlewarer interface {
	Do(ctx context.Context) error
}

Middlewarer allows execution of a handler before Handle is executed.

Do accepts a context and returns an error. If error is nil, will execute the next Middlewarer or Handle. Otherwise, it will enter the Resolve function.

Context mutated from within a middleware will only persist within scope.

type Prefixer

type Prefixer interface {
	Load(guildID string) (string, bool)
	Default() string
}

Prefixer identifies the prefix based on the guildID and removes the prefix of the command string if matched.

Load fetches a prefix that matches the guildID and returns the prefix mapped to the guildID with an ok bool.

Default returns the default prefix

type Route

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

Route represents a command.

func NewRoute

func NewRoute(p Prefixer) *Route

NewRoute returns a new Route. If Prefixer is nil, the route's prefix will be assumed to be empty.

func (*Route) Do

func (r *Route) Do(c Commander) *Route

Do the execution of a Commander implementation when there is a Message Create event. https://discord.com/developers/docs/topics/gateway#message-create

A Commander can optionally implement CmdParser for custom parsing of message content. Parsing errors will be handled by Resolve.

No-ops if Commander is nil.

If Do is called multiple times, the previous Do call will be overwritten.

func (*Route) Find

func (r *Route) Find(subAlias string) *Route

Find the first subroute of this route matching the given subroute alias. Subroute match is prioritized by order of the subroute appends. If alias is not found, will return nil.

func (*Route) Has

func (r *Route) Has(subroutes ...*Route) *Route

Has binds subroutes to the current route. Subroutes with duplicate aliases will be prioritized in order of which they were added.

func (*Route) HasAlias

func (r *Route) HasAlias(a string) bool

HasAlias returns if the given string is a case-insensitive alias of the current route

func (*Route) IsDefault

func (r *Route) IsDefault() bool

IsDefault returns true if a route will always be executed when Discord produces a Message Create event with respect to the Prefixer (if provided).

https://discord.com/developers/docs/topics/gateway#message-create

A default route will only be executed if it is not a subroute. Any subroutes it might contain will be ignored.

func (*Route) On

func (r *Route) On(aliases ...string) *Route

On adds new identifiers for a Route. By default, aliases with whitespaces will not be matched unless a Commander also implements the CmdParser interface

func (*Route) Use

func (r *Route) Use(middlewares ...Middlewarer) *Route

Use adds middlewares to the route. Middlewares are executed in order of which they were added, and will always run immediately before the core handler. Middleware errors can be handled by Resolve.

type Router

type Router struct {
	S *discordgo.Session
}

Router maps commands to handlers.

func New

func New(s *discordgo.Session) *Router

New returns a new Router.

func (*Router) Close

func (r *Router) Close() error

Close closes a websocket and stops all listening/heartbeat goroutines.

func (*Router) Has

func (r *Router) Has(route *Route)

Has binds a Route to the Router.

func (*Router) HasDefault

func (r *Router) HasDefault(h interface{})

HasDefault binds a default discordgo event handler to the builder.

func (*Router) HasOnce

func (r *Router) HasOnce(route *Route)

HasOnce binds binds a Route to the Router, but the route will only fire at most once.

func (*Router) HasOnceDefault

func (r *Router) HasOnceDefault(h interface{})

HasOnceDefault binds a default discordgo event handler to the builder.

func (*Router) Open

func (r *Router) Open() error

Open creates a websocket connection to Discord. See: https://discordapp.com/developers/docs/topics/gateway#connecting