sugo

README

Sugo

Sugo is a command-based bot framework built on top of discordgo. There are no dependencies other then discordgo and stdlib.

The idea of the project is to make simple wrapper around discordgo that allows fast and easy building of the commands-based bots without too much of a boilerplate code.

The project is on rather early stages of development, so until first release there will be little effort to keep commands API backwards-compatible. Please, fork or checkout a commit that works for you.

If you are worried about API being broken, please use one of the released versions instead of regular go get github.com/diraven/sugo.

If you have something to share, discuss or propose - please, do not hesitate to do so via issues.

Quickstart

The simpler command would look like the following:

package main

import (
	"github.com/diraven/sugo"
)

// Make a command.
var cmd = &sugo.Command{
	Trigger:     "ping",
	Description: "just responds with pong!",
	Execute: func(req *sugo.Request) error {
		_, err := req.RespondInfo("", "pong!")
		return err
	},
}

func main() {
	// Create new bot instance.
	bot := sugo.New()

	// Set bot trigger (not required, by default the bot will react to the messages starting with the bot @mention).
	bot.DefaultTrigger = "."

	// Initialize modules.
	if err := bot.AddCommand(cmd); err != nil {
		log.Println(err)
		return
	}

	// Start the bot.
	if err := bot.Startup("TOKEN"); err != nil {
		bot.HandleError(err)
	}
}

Advanced Usage

Underlying *discordgo.Session access

You may need it to perform numerous API interactions such as assigning user roles etc. Inside commands it is available via Sugo instance req.Sugo.Session, see godoc for details.

Warning: req.Sugo.Session will be nil until bot starts up.

Custom embeds

If you need some custom message type and regular req.Respond* is not enough, you can send messages directly using lower level *discordgo.Session, like this:

package main

import (
	"github.com/diraven/sugo"
	"github.com/bwmarrin/discordgo"
)

// Make a command.
var cmd = &sugo.Command{
	Trigger:     "ping",
	Description: "just responds with pong!",
	Execute: func(req *sugo.Request) error {
		embed := &discordgo.MessageEmbed{
			Title: "Command Response",
			Description: "Pong!",
			Color: sugo.ColorDefault,
		}
		
		_, err := req.Sugo.Session.ChannelMessageSendEmbed(req.Channel.ID, embed)
		return err
	},
}

func main() {
	// Create new bot instance.
	bot := sugo.New()

	// Add command.
	bot.AddCommand(cmd)

	// Start the bot.
	if err := bot.Startup("TOKEN"); err != nil {
		bot.HandleError(err)
	}
}

See discordgo documentation for additional details.

Permissions

Command can be restricted to the users that have specified discord permissions.

For example if you want the command to be restricted to users that can ban members AND add reactions, command declaration will look like this:

package main

import (
	"github.com/diraven/sugo"
	"github.com/bwmarrin/discordgo"
)

// Make a command.
var cmd = &sugo.Command{
	Trigger:     "ping",
	Description: "just responds with pong!",
	PermissionsRequired: discordgo.PermissionBanMembers | discordgo.PermissionAddReactions,
	Execute: func(req *sugo.Request) error {
		_, err := req.RespondInfo("", "pong!")
		return err
	},
}

func main() {
	// Create new bot instance.
	bot := sugo.New()

	// Add command.
	bot.AddCommand(cmd)

	// Start the bot.
	if err := bot.Startup("TOKEN"); err != nil {
		bot.HandleError(err)
	}
}

More info

See godoc and command modules examples.

Typical bot initialization would look like the following:

package main

import (
	"github.com/diraven/sugo"
	"github.com/diraven/sugo/examples/test"
	"github.com/diraven/sugo/examples/help"
	"github.com/diraven/sugo/examples/info"
)

func main() {
	// Create new bot instance.
	bot := sugo.New()

	// Set bot trigger.
	bot.DefaultTrigger = "."

	// Initialize modules.
	if err := test.Init(bot); err != nil {
		log.Println(err)
		return
	}
	if err := help.Init(bot); err != nil {
		log.Println(err)
		return
	}
	if err := info.Init(bot); err != nil {
		log.Println(err)
		return
	}

	// Start the bot.
	if err := bot.Startup("TOKEN"); err != nil {
		bot.HandleError(err)
	}
}

Compile and run your bot, then try to write something like .test responses in the channel bot has both read and write access to.

Documentation

Overview

Package sugo is a discord bot framework written in go.

Index

• Constants
• type Command
  • func (c *Command) GetPath() (value string)
  • func (c *Command) GetSubcommandsTriggers(sg *Instance, req *Request) []string
• type Instance
  • func New() *Instance
  • func (sg *Instance) AddCommand(c *Command)
  • func (sg *Instance) AddRequestMiddleware(m RequestMiddleware)
  • func (sg *Instance) AddResponseMiddleware(m ResponseMiddleware)
  • func (sg *Instance) AddShutdownHandler(handler shutdownHandler)
  • func (sg *Instance) AddStartupHandler(handler startupHandler)
  • func (sg *Instance) FindCommand(req *Request, q string) (*Command, error)
  • func (sg *Instance) HandleError(req *Request, err error)
  • func (sg *Instance) Shutdown()
  • func (sg *Instance) Startup(token string) (err error)
• type Request
  • func (req *Request) AddReaction(reaction emoji) (err error)
  • func (req *Request) GetGuild() (*discordgo.Guild, error)
  • func (req *Request) IsChannelDM() bool
  • func (req *Request) IsChannelDefault() bool
  • func (req *Request) NewResponse(respType responseType, title string, text string) (resp *Response)
  • func (req *Request) PlainTextResponse(text string) (resp *Response)
  • func (req *Request) SimpleResponse(text string) (resp *Response)
• type RequestMiddleware
• type Response
  • func (resp *Response) Send() (m *discordgo.Message, err error)
  • func (resp *Response) SendDM() (m *discordgo.Message, err error)
• type ResponseMiddleware

Constants

const (
	ResponsePlainText responseType = "plain_text"
	ResponseDefault   responseType = "default"
	ResponseInfo      responseType = "info"
	ResponseSuccess   responseType = "success"
	ResponseWarning   responseType = "warning"
	ResponseDanger    responseType = "danger"
)

const ColorDanger = 0xd9534f

ColorDanger is red-ish.

const ColorDefault = 0x636c72

ColorDefault is gray-ish.

const ColorInfo = 0x5bc0de

ColorInfo is light-blue-ish.

const ColorPrimary = 0x0275d8

ColorPrimary is dark-blue-ish.

const ColorSuccess = 0x5cb85c

ColorSuccess is green-ish.

const ColorWarning = 0xf0ad4e

ColorWarning is yellow-ish.

const (
	ReactionOk emoji = "👌"
)

const VERSION = "0.6.2"

VERSION contains current version of the Instance framework.

Types

type Command

type Command struct {
	// Trigger is a sequence of symbols message should start with to match with the command.
	Trigger string
	// Description should contain short command description.
	Description string
	// HasParams specifies if command can have additional parameters in Request string.
	HasParams bool
	// PermissionsRequired specifies permissions set required by the command.
	PermissionsRequired int
	// RequireGuild specifies if this command works in guild chats only.
	RequireGuild bool
	// Execute method is executed if Request string matches the given command.
	Execute func(req *Request) (*Response, error)
	// SubCommands contains all subcommands of the given command.
	SubCommands []*Command
	// contains filtered or unexported fields
}

Command struct describes basic command type.

func (*Command) GetPath

func (c *Command) GetPath() (value string)

GetPath returns sequence of triggers from outermost (via the sequence of parents) to the given one.

func (*Command) GetSubcommandsTriggers

func (c *Command) GetSubcommandsTriggers(sg *Instance, req *Request) []string

GetSubcommandsTriggers return all subcommands triggers of the given command available for given user.

type Instance

type Instance struct {
	// Trigger specifies what should message start with for the bot to consider it to be command.
	DefaultTrigger string
	// HelpTrigger specifies what should message start with for the bot to consider it to be help command.
	HelpTrigger string
	// Session is a *discordgo.Session bot is wrapped around.
	Session *discordgo.Session
	// Self contains a giscordgo.User instance of the bot.
	Self *discordgo.User
	// RootCommand is a bot root meta-command.
	RootCommand *Command

	// IsTriggered should return true if the bot is to react to command and false otherwise.
	IsTriggered func(req *Request) (triggered bool)
	// ErrorHandler is the function that receives and handles all the errors. Keep in mind that *Request can be nil
	// if error handler is called outside of command request scope.
	ErrorHandler func(req *Request, err error)
	// contains filtered or unexported fields
}

Instance struct describes bot.

func New

func New() *Instance

New creates new bot instance.

func (*Instance) AddCommand

func (sg *Instance) AddCommand(c *Command)

AddCommand adds command to the bot's commands list.

func (*Instance) AddRequestMiddleware

func (sg *Instance) AddRequestMiddleware(m RequestMiddleware)

AddRequestMiddleware adds request middleware.

func (*Instance) AddResponseMiddleware

func (sg *Instance) AddResponseMiddleware(m ResponseMiddleware)

AddResponseMiddleware adds response middleware.

func (*Instance) AddShutdownHandler

func (sg *Instance) AddShutdownHandler(handler shutdownHandler)

AddShutdownHandler adds function that will be called on bot shutdown.

func (*Instance) AddStartupHandler

func (sg *Instance) AddStartupHandler(handler startupHandler)

AddStartupHandler adds function that will be called on bot startup.

func (*Instance) FindCommand

func (sg *Instance) FindCommand(req *Request, q string) (*Command, error)

FindCommand searches for the command in the modules registered.

func (*Instance) HandleError

func (sg *Instance) HandleError(req *Request, err error)

HandleError handles unexpected errors that were returned unhandled elsewhere.

func (*Instance) Shutdown

func (sg *Instance) Shutdown()

Shutdown sends Shutdown signal to the bot's Shutdown channel.

func (*Instance) Startup

func (sg *Instance) Startup(token string) (err error)

Startup starts the bot up.

type Request

type Request struct {
	Ctx     context.Context
	Sugo    *Instance
	Message *discordgo.Message
	Channel *discordgo.Channel
	Command *Command
	Query   string
}

Request contains message context data along with some helpers to retrieve more information.

func (*Request) AddReaction

func (req *Request) AddReaction(reaction emoji) (err error)

ReactOk adds "ok" emoji to the command message.

func (*Request) GetGuild

func (req *Request) GetGuild() (*discordgo.Guild, error)

GetGuild allows to retrieve *discordgo.Guild from Request. Will not work and will throw error for channels that have no guild such as DirectMessages or GroupDirectMessages channels, so you probably want to check those beforehand.

func (*Request) IsChannelDM

func (req *Request) IsChannelDM() bool

IsChannelDM returns true if channel is DirectMessages (or GroupDirectMessages) channel and false otherwise.

func (*Request) IsChannelDefault

func (req *Request) IsChannelDefault() bool

IsChannelDefault returns true if channel is Guild's default channel and false otherwise.

func (*Request) NewResponse

func (req *Request) NewResponse(respType responseType, title string, text string) (resp *Response)

Respond responds (via DM if viaDM is set to true) with the Text or Embed provided. If both provided - only Text is responded with.

func (*Request) PlainTextResponse

func (req *Request) PlainTextResponse(text string) (resp *Response)

PlainTextResponse creates a raw text response.

func (*Request) SimpleResponse

func (req *Request) SimpleResponse(text string) (resp *Response)

SimpleResponse creates a default embed response.

type RequestMiddleware

type RequestMiddleware func(*Request) error

type Response

type Response struct {
	Type    responseType
	Request *Request
	Text    string
	Embed   *discordgo.MessageEmbed
	Emoji   discordgo.Emoji
}

func (*Response) Send

func (resp *Response) Send() (m *discordgo.Message, err error)

Send sends a Response into the channel Request was sent in.

func (*Response) SendDM

func (resp *Response) SendDM() (m *discordgo.Message, err error)

SendDM sends a Response to the user DirectMessages channel.

type ResponseMiddleware

type ResponseMiddleware func(*Response) error