disgolf

README

Make Discord bots on Go with ease

About

Disgolf is lightweight Go framework for building bots on Discord.
It does all complicated things for you, keeping your code clean and helps you focus on important stuff.

Installation

To install the library you must have at least Go of version 1.15 and use master version of DiscordGo, otherwise you will end up with a lot of errors. And that's not good.

$ go get -u github.com/FedorLap2006/disgolf

Usage

For complicated usage examples you can visit our examples directory.

package main

import (
    "os"
    "signal"
    "syscall"
    "time"

    "github.com/FedorLap2006/disgolf"
    "github.com/bwmarrin/discordgo"
)

func main() {
    bot, err := disgolf.New("BOT-TOKEN")
    if err != nil {
        panic(err)
    }

    bot.Router.Register(&disgolf.Command{
        Name: "hello_world",
        Description: "Say hi to the world!",
        Handler: disgolf.CommandHandlerFunc(func(ctx *disgolf.Ctx) error {
            ctx.Respond(&discordgo.InteractionResponse {
                Type: discordgo.InteractionResponseChannelMessageWithSource,
                Data: &discordgo.InteractionResponseData{
                    Content: "Hello world!",
                },
            })
        })
    })

    err := bot.Router.Sync(bot.Session, "", "GUILD-TEST-ID")
    if err != nil {
        panic(err)
    }

    err := bot.Open()
    if err != nil {
        panic(err)
    }
    defer bot.Close()
    
    stchan := make(chan os.Signal, 1)
    signal.Notify(stchan, syscall.SIGTERM, os.Interrupt, syscall.SIGSEGV)
end:
	for {
		select {
		case <-stchan:
			break end
		default:
		}
		time.Sleep(time.Second)
	}
}

Documentation

Index

• Variables
• type Bot
  • func New(token string) (*Bot, error)
• type BulkCommandSyncer
  • func (BulkCommandSyncer) Sync(r *Router, s *discordgo.Session, application string, guild string) error
• type Command
  • func (cmd Command) ApplicationCommand() *discordgo.ApplicationCommand
  • func (cmd Command) ApplicationCommandOption() *discordgo.ApplicationCommandOption
• type CommandSyncer
• type Ctx
  • func NewCtx(s *discordgo.Session, caller *Command, i *discordgo.Interaction, ...) *Ctx
  • func (ctx *Ctx) Next()
  • func (ctx *Ctx) Respond(response *discordgo.InteractionResponse) error
  • func (ctx *Ctx) String() string
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) HandleCommand(ctx *Ctx)
• type MessageCtx
  • func NewMessageCtx(s *discordgo.Session, caller *Command, m *discordgo.Message, ...) *MessageCtx
  • func (ctx *MessageCtx) Next()
  • func (ctx *MessageCtx) Reply(content string, mention bool) (*discordgo.Message, error)
  • func (ctx *MessageCtx) ReplyComplex(message *discordgo.MessageSend, mention bool) (*discordgo.Message, error)
• type MessageHandler
• type MessageHandlerConfig
• type MessageHandlerFunc
  • func (f MessageHandlerFunc) HandleMessageCommand(ctx *MessageCtx)
• type OptionsMap
• type Router
  • func NewRouter(initial []*Command) (r *Router)
  • func (r *Router) Count() (c int)
  • func (r *Router) Get(name string) *Command
  • func (r *Router) HandleInteraction(s *discordgo.Session, i *discordgo.InteractionCreate)
  • func (r *Router) List() (list []*Command)
  • func (r *Router) MakeMessageHandler(cfg *MessageHandlerConfig) func(s *discordgo.Session, m *discordgo.MessageCreate)
  • func (r *Router) Register(cmd *Command)
  • func (r *Router) Sync(s *discordgo.Session, application, guild string) error
  • func (r *Router) Unregister(name string) (command *Command, existed bool)
  • func (r *Router) Update(name string, newcmd *Command) (cmd *Command, err error)

Variables

var (
	// ErrCommandNotExists means that the requested command does not exist.
	ErrCommandNotExists = errors.New("command not exists")
)

Types

type Bot

type Bot struct {
	*discordgo.Session

	Router *Router
}

A Bot wraps discordgo.Session with configuration and a router.

func New

func New(token string) (*Bot, error)

New constructs a Bot, from a authentication token.

type BulkCommandSyncer

type BulkCommandSyncer struct{}

BulkCommandSyncer syncs all the commands using ApplicationCommandBulkOverwrite function.

func (BulkCommandSyncer) Sync

func (BulkCommandSyncer) Sync(r *Router, s *discordgo.Session, application string, guild string) error

Sync implements CommandSyncer interface.

type Command

type Command struct {
	Name               string
	Description        string
	Options            []*discordgo.ApplicationCommandOption
	Type               discordgo.ApplicationCommandType
	Handler            Handler
	Middlewares        []Handler
	MessageHandler     MessageHandler
	MessageMiddlewares []MessageHandler

	// NOTE: nesting of more than 3 level has no effect
	SubCommands *Router
	// Custom payload for the command. Useful for module names, and such stuff.
	Custom interface{}
}

Command represents a command.

func (Command) ApplicationCommand

func (cmd Command) ApplicationCommand() *discordgo.ApplicationCommand

ApplicationCommand converts Command to discordgo.ApplicationCommand.

func (Command) ApplicationCommandOption

func (cmd Command) ApplicationCommandOption() *discordgo.ApplicationCommandOption

ApplicationCommandOption converts Command to discordgo.ApplicationCommandOption (subcommand).

type CommandSyncer

type CommandSyncer interface {
	Sync(r *Router, s *discordgo.Session, application, guild string) error
}

A CommandSyncer syncs all the commands with Discord.

type Ctx

type Ctx struct {
	*discordgo.Session `json:"-"`
	Caller             *Command                                             `json:"caller"`
	Interaction        *discordgo.Interaction                               `json:"interaction"`
	Options            OptionsMap                                           `json:"options"`
	OptionsRaw         []*discordgo.ApplicationCommandInteractionDataOption `json:"options_raw"`
	// contains filtered or unexported fields
}

Ctx is a context provided to a command. It embeds session for easier use, and contains interaction and preprocessed options.

func NewCtx

func NewCtx(s *discordgo.Session, caller *Command, i *discordgo.Interaction, parent *discordgo.ApplicationCommandInteractionDataOption, handlers []Handler) *Ctx

NewCtx constructs ctx from given parameters.

func (*Ctx) Next

func (ctx *Ctx) Next()

func (*Ctx) Respond

func (ctx *Ctx) Respond(response *discordgo.InteractionResponse) error

Respond is a wrapper for ctx.Session.InteractionRespond

func (*Ctx) String

func (ctx *Ctx) String() string

type Handler

type Handler interface {
	HandleCommand(ctx *Ctx)
}

A Handler processes the command

type HandlerFunc

type HandlerFunc func(ctx *Ctx)

HandlerFunc is a wrapper around Handler for functions

func (HandlerFunc) HandleCommand

func (f HandlerFunc) HandleCommand(ctx *Ctx)

HandleCommand implements Handler interface and calls the function with provided context

type MessageCtx

type MessageCtx struct {
	*discordgo.Session
	Caller    *Command
	Message   *discordgo.Message
	Arguments []string
	// contains filtered or unexported fields
}

MessageCtx is a context provided to message command handler. It contains the message

func NewMessageCtx

func NewMessageCtx(s *discordgo.Session, caller *Command, m *discordgo.Message, arguments []string, handlers []MessageHandler) *MessageCtx

NewMessageCtx constructs context from a message. If argdelim is not empty it is a delimiter for the arguments, otherwise the arguments are split by a space.

func (*MessageCtx) Next

func (ctx *MessageCtx) Next()

Next calls the next middleware / command handler.

func (*MessageCtx) Reply

func (ctx *MessageCtx) Reply(content string, mention bool) (*discordgo.Message, error)

Reply sends and returns a simple (content-only) message replying to the command message. If mention is true the command author is mentioned in the reply. It is a wrapper for discordgo.Session.ChannelMessageSendReply.

func (*MessageCtx) ReplyComplex

func (ctx *MessageCtx) ReplyComplex(message *discordgo.MessageSend, mention bool) (*discordgo.Message, error)

ReplyComplex sends and returns a complex (with embds, attachments, etc) message replying to the command message. If mention is true the command author is mentioned in the reply. It is a wrapper for discordgo.Session.ChannelMessageSendComplex

type MessageHandler

type MessageHandler interface {
	HandleMessageCommand(ctx *MessageCtx)
}

A MessageHandler processes the message command

type MessageHandlerConfig

type MessageHandlerConfig struct {
	// Prefixes got will respond to
	Prefixes      []string
	MentionPrefix bool

	ArgumentDelimiter string
}

type MessageHandlerFunc

type MessageHandlerFunc func(ctx *MessageCtx)

HandlerFunc is a wrapper around MessageHandler for functions

func (MessageHandlerFunc) HandleMessageCommand

func (f MessageHandlerFunc) HandleMessageCommand(ctx *MessageCtx)

HandleCommand implements MessageHandler interface and calls the function with provided context

type OptionsMap

type OptionsMap = map[string]*discordgo.ApplicationCommandInteractionDataOption

OptionsMap is an alias for map of discordgo.ApplicationCommandInteractionDataOption

type Router

type Router struct {
	// Commands is a map of registered commands.
	// Key is command name. Value is command instance.
	//
	// NOTE: it is not recommended to use it directly, use Register, Get, Update, Unregister functions instead.
	Commands map[string]*Command

	Syncer CommandSyncer
}

A Router stores all the commands and routes the interactions

func NewRouter

func NewRouter(initial []*Command) (r *Router)

NewRouter constructs a router from a set of predefined commands.

func (*Router) Count

func (r *Router) Count() (c int)

Count returns amount of commands stored

func (*Router) Get

func (r *Router) Get(name string) *Command

Get returns a command by specified name.

func (*Router) HandleInteraction

func (r *Router) HandleInteraction(s *discordgo.Session, i *discordgo.InteractionCreate)

HandleInteraction is an interaction handler passed to discordgo.Session.AddHandler.

func (*Router) List

func (r *Router) List() (list []*Command)

List returns all registered commands

func (*Router) MakeMessageHandler

func (r *Router) MakeMessageHandler(cfg *MessageHandlerConfig) func(s *discordgo.Session, m *discordgo.MessageCreate)

func (*Router) Register

func (r *Router) Register(cmd *Command)

Register registers the command.

func (*Router) Sync

func (r *Router) Sync(s *discordgo.Session, application, guild string) error

Sync wraps Router.Syncer and automatically detects application id.

func (*Router) Unregister

func (r *Router) Unregister(name string) (command *Command, existed bool)

Unregister removes a command from router

func (*Router) Update

func (r *Router) Update(name string, newcmd *Command) (cmd *Command, err error)

Update updates the command and does all behind-the-scenes work.