dgutils

README

DiscordGo Utilities

This package provides miscellaneous utilities for Discord chatbots that follow the typical prefixed command → response paradigm (I just made that up). Everyhing in this repository was written out of necessity, and may not cover your specific use case. If you have some "special needs", or wrote some code that you think would fit here, please fell free to open an issue or pull request.

This README is yet to be further expanded to include features, instalation and examples. But I'm way too lazy to do it now. Oh well...

Documentation

Index

• func IsOwner(s *discordgo.Session, guildID, userID string) (bool, error)
• func MemberHasPermissions(s *discordgo.Session, guildID, userID string, permission int) (bool, error)
• type AccessDenied
  • func (e AccessDenied) Error() string
• type ArgCountMismatch
  • func (e ArgCountMismatch) Error() string
• type Cmd
• type CmdErrorHandler
• type CmdPredicate
  • func (p CmdPredicate) Validate(s *discordgo.Session, m *discordgo.MessageCreate) bool
• type CmdPredicateFunc
• type CmdRegistry
  • func Registry() *CmdRegistry
  • func (reg *CmdRegistry) Add(name string, cmd Cmd) error
  • func (reg *CmdRegistry) Alias(name string, dest string) error
  • func (reg *CmdRegistry) Canon(name string) string
  • func (reg *CmdRegistry) Get(name string) Cmd
  • func (reg *CmdRegistry) Handle(s *discordgo.Session, msg *discordgo.MessageCreate, pfx string, ...)
  • func (reg *CmdRegistry) Handler(pfx string, errHandler CmdErrorHandler) func(*discordgo.Session, *discordgo.MessageCreate)
• type FnCmd
  • func Command(fn interface{}, help string, errHandler CmdErrorHandler) (*FnCmd, error)
  • func MustCommand(fn interface{}, help string, errHandler CmdErrorHandler) *FnCmd
  • func MustPredicatedCommand(fn interface{}, help string, errHandler CmdErrorHandler, ...) *FnCmd
  • func PredicatedCommand(fn interface{}, help string, errHandler CmdErrorHandler, ...) (cmd *FnCmd, err error)
  • func (cmd *FnCmd) ErrorHandler() CmdErrorHandler
  • func (cmd *FnCmd) Invoke(s *discordgo.Session, m *discordgo.MessageCreate, args []string) (err error)
• type UnmarshalError
  • func (e UnmarshalError) Error() string

Functions

func IsOwner

func IsOwner(s *discordgo.Session, guildID, userID string) (bool, error)

Checks if user with ID userID is owner of guild with ID guildID

func MemberHasPermissions

func MemberHasPermissions(s *discordgo.Session, guildID, userID string, permission int) (bool, error)

Checks if a given member with ID userID has permissions permission on guild with ID guildID

Types

type AccessDenied

type AccessDenied struct{}

func (AccessDenied) Error

func (e AccessDenied) Error() string

type ArgCountMismatch

type ArgCountMismatch struct {
	Expected, Got int
}

func (ArgCountMismatch) Error

func (e ArgCountMismatch) Error() string

type Cmd

type Cmd interface {
	Invoke(s *discordgo.Session, m *discordgo.MessageCreate, args []string) error
	ErrorHandler() CmdErrorHandler
}

type CmdErrorHandler

type CmdErrorHandler func(*discordgo.Session, *discordgo.MessageCreate, error)

type CmdPredicate

type CmdPredicate struct {
	Permissions            int
	AdministratorOverrides bool
	Custom                 CmdPredicateFunc
}

Describes in which condition a command may be executed. Permissions is a bitfield describing necessary user premissions for invoking the command. AdministratorOverrides defines whether a member having Adminstrator permission should bypass the predicate Custom is a function that can be used to check for logic not directly implemented by a predicate.

func (CmdPredicate) Validate

func (p CmdPredicate) Validate(s *discordgo.Session, m *discordgo.MessageCreate) bool

Verifies whether the message m satisfies the predicate

type CmdPredicateFunc

type CmdPredicateFunc func(*discordgo.Session, *discordgo.MessageCreate, CmdPredicate) bool

type CmdRegistry

type CmdRegistry struct {
	Cmds    map[string]Cmd
	Aliases map[string]string
}

func Registry

func Registry() *CmdRegistry

Creates an empty command register

func (*CmdRegistry) Add

func (reg *CmdRegistry) Add(name string, cmd Cmd) error

func (*CmdRegistry) Alias

func (reg *CmdRegistry) Alias(name string, dest string) error

func (*CmdRegistry) Canon

func (reg *CmdRegistry) Canon(name string) string

Returns the canonical name of a command

func (*CmdRegistry) Get

func (reg *CmdRegistry) Get(name string) Cmd

Returns a commend in the register, or nil if the command doesn't exist name might be a canon name or an alias

func (*CmdRegistry) Handle

func (reg *CmdRegistry) Handle(
	s *discordgo.Session,
	msg *discordgo.MessageCreate,
	pfx string,
	errHandler CmdErrorHandler,
)

Handles commands in the context of this register pfx represents a prefix string for prefixed commands errHandler is an optional error handler. If non-nil, it will be called when a command returns an error when executing. It can be overriden on a per-command basis

func (*CmdRegistry) Handler

func (reg *CmdRegistry) Handler(
	pfx string,
	errHandler CmdErrorHandler,
) func(*discordgo.Session, *discordgo.MessageCreate)

Returns a handler function, suitable to be used with discordgo.Session.AddHandler pfx represents a prefix string for prefixed commands errHandler is an optional error handler. If non-nil, it will be called when a command returns an error when executing. It can be overriden on a per-command basis

type FnCmd

type FnCmd struct {
	Help string

	Predicate  CmdPredicate
	ErrHandler CmdErrorHandler
	// contains filtered or unexported fields
}

Command backed by a Go function. Arguments are reflected and automatically converted at runtime. Predicate is an optional CmdPredicate struct describing in which conditions the command may be executed. ErrHandler is an optional error handling function that may be invoked in case the command fails to be invoked.

func Command

func Command(fn interface{}, help string, errHandler CmdErrorHandler) (*FnCmd, error)

Creates a command from a given function fn, with help as the help string, and errHandler as an optional error handler.

fn must have a *discordgo.Session as the first parameter, and *discordgo.MessageCreate as the second. Later parameters are taken as command parameters, and are converted automatically upon invocation. Valid parameter types include integer and float types, string, bool and pointers to some discordgo types (User, Channel, Role and Member), Arrays of supported types are accepted as the last argument of a function, and will behave as if the command was a variadic function.

func MustCommand

func MustCommand(fn interface{}, help string, errHandler CmdErrorHandler) *FnCmd

Same as Command, but it panics if an error is encountered

func MustPredicatedCommand

func MustPredicatedCommand(
	fn interface{},
	help string,
	errHandler CmdErrorHandler,
	predicate CmdPredicate,
) *FnCmd

Same as PredicatedCommand, but it panics if an error is encountered

func PredicatedCommand

func PredicatedCommand(
	fn interface{},
	help string,
	errHandler CmdErrorHandler,
	predicate CmdPredicate,
) (cmd *FnCmd, err error)

Same as Command, but also takes a predicate struct. Predicates may be used to limit commands to users with certain permission levels, or perform additional validation before executing a command.

func (*FnCmd) ErrorHandler

func (cmd *FnCmd) ErrorHandler() CmdErrorHandler

func (*FnCmd) Invoke

func (cmd *FnCmd) Invoke(s *discordgo.Session, m *discordgo.MessageCreate, args []string) (err error)

Invokes the command based on message creation event m with arguments args. Arguments are automatically parsed to their required type; an error is returned if it can't be done. args should not contain the command name as it's first member, but it might be empty if it is required.

type UnmarshalError

type UnmarshalError struct {
	Why error /* underlying error */
}

Argument parser failure Why (probably) has more information about what actually happened

func (UnmarshalError) Error

func (e UnmarshalError) Error() string