unison

README

Unison

Unison is a framework for Discord chat bots written in Go.

It is currently used to power the stackguru bot for the /r/Nootropics Discord server.

Written and maintained by @s1kx and @sciencefyll.

Features

• Configurable bot modes
• Custom commands
• Custom event hooks
• Access control

Project status

The different labels of this repository.

• Bug
• Question
• Enhancement
• Help wanted
• Duplicate
• Invalid
• Won't fix

Requirements

• Go version 1.5 or higher
• Glide for installing dependencies

Development

Collaborators and pull requests are very welcome.

We use the following guidelines:

• Semantic Versioning
• Git flow as outlined in this article
• GitHub scrum workflow

Documentation

Index

• func Run(settings *Config) error
• type Bot
  • func (bot *Bot) GetServiceData(srvName string, key string) string
  • func (bot *Bot) GetState(guildID string) (state.Type, error)
  • func (bot *Bot) RegisterCommand(cmd *Command) error
  • func (bot *Bot) RegisterEventHook(hook *EventHook) error
  • func (bot *Bot) RegisterService(srv *Service) error
  • func (bot *Bot) Run() error
  • func (bot *Bot) SetServiceData(srvName string, key string, val string) string
  • func (bot *Bot) SetState(guildID string, st state.Type) error
• type Command
• type CommandAction
• type Config
• type Context
  • func NewContext(bot *Bot, ds *discordgo.Session, sig chan os.Signal) *Context
• type DiscordPermissionFlags
• type DiscordPermissions
  • func NewDiscordPermissionsDiscordgoWrapper(flags int, err error) (*DiscordPermissions, error)
  • func (dp *DiscordPermissions) Add(flags DiscordPermissionFlags)
  • func (dp *DiscordPermissions) Get() DiscordPermissionFlags
  • func (dp *DiscordPermissions) HasRequiredPermissions(permission *DiscordPermissions) bool
  • func (dp *DiscordPermissions) Remove(flags DiscordPermissionFlags)
  • func (dp *DiscordPermissions) Set(flags DiscordPermissionFlags)
  • func (dp *DiscordPermissions) ToStr() string
• type DuplicateCommandError
  • func (e DuplicateCommandError) Error() string
• type DuplicateEventHookError
  • func (e DuplicateEventHookError) Error() string
• type DuplicateServiceError
  • func (e DuplicateServiceError) Error() string
• type EventHandlerFunc
• type EventHook
• type Service
• type ServiceActionFunc
• type TooShortCommandPrefixError
  • func (e TooShortCommandPrefixError) Error() string

Functions

func Run

func Run(settings *Config) error

Run start the bot. Connect to discord, setup commands, hooks and services.

Types

type Bot

type Bot struct {
	*Config
	Discord *discordgo.Session

	User *discordgo.User
	// contains filtered or unexported fields
}

Bot is an active bot session.

func (*Bot) GetServiceData

func (bot *Bot) GetServiceData(srvName string, key string) string

GetServiceData a data value from existing services

func (*Bot) GetState

func (bot *Bot) GetState(guildID string) (state.Type, error)

GetState retrieves the state for given guild

func (*Bot) RegisterCommand

func (bot *Bot) RegisterCommand(cmd *Command) error

RegisterCommand ...

func (*Bot) RegisterEventHook

func (bot *Bot) RegisterEventHook(hook *EventHook) error

RegisterEventHook ...

func (*Bot) RegisterService

func (bot *Bot) RegisterService(srv *Service) error

RegisterService ...

func (*Bot) Run

func (bot *Bot) Run() error

Run Start the bot instance

func (*Bot) SetServiceData

func (bot *Bot) SetServiceData(srvName string, key string, val string) string

SetServiceData update or set a new value for a given service key

func (*Bot) SetState

func (bot *Bot) SetState(guildID string, st state.Type) error

SetState updates state for given guild

type Command

type Command struct {
	// Name is the command title used to trigger the CommandAction
	Name string

	// Usage is a description of the command goal
	Usage string

	// Flags are optionals and bools that can be used in triggering the command
	Flags interface{} // used to generate a *arg.Parser

	// Action is the func run to execute the command
	Action CommandAction

	// Sub commands
	SubCommands []*Command

	// Deactivated true if the command should be ignored and viewed as "dead"
	Deactivated bool

	// Set the minimum required permissions for this command
	//	This level is inherited into each subcommand and must be overwritten if else is desired
	//	https://discordapp.com/developers/docs/topics/permissions
	Permissions DiscordPermissions

	// mutex since we don't create new command instances for each request
	sync.RWMutex // TODO: should Command.Flags be copied after parsing, and send as an interface argument?
	// contains filtered or unexported fields
}

Command struct holds all the command details

type CommandAction

type CommandAction func(ctx *Context, msg *discordgo.Message, request string) error

CommandAction command logic to be executed

type Config

type Config struct {
	Token         string
	CommandPrefix []string
	BotState      state.Type

	// DisableMentionTrigger when true, bot commands won't execute when using mention as prefix
	DisableMentionTrigger bool

	Commands   []*Command
	EventHooks []*EventHook
	Services   []*Service
}

Config contains the definition of bot behavior. It is used while creating/setting up the actual bot.

type Context

type Context struct {
	Bot                *Bot
	Discord            *discordgo.Session
	SystemInteruptChan chan os.Signal
}

Context is a type that is passed to every handler in a bot application. It can be used to refer back to main components.

func NewContext

func NewContext(bot *Bot, ds *discordgo.Session, sig chan os.Signal) *Context

NewContext Create a new context class for the discord bot This will also hold a signal for system interupts

type DiscordPermissionFlags

type DiscordPermissionFlags uint64

DiscordPermissionFlags limits member accessability to discord guilds/channels functionality

https://discordapp.com/developers/docs/topics/permissions

type DiscordPermissions

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

func NewDiscordPermissionsDiscordgoWrapper

func NewDiscordPermissionsDiscordgoWrapper(flags int, err error) (*DiscordPermissions, error)

func (*DiscordPermissions) Add

func (dp *DiscordPermissions) Add(flags DiscordPermissionFlags)

func (*DiscordPermissions) Get

func (dp *DiscordPermissions) Get() DiscordPermissionFlags

func (*DiscordPermissions) HasRequiredPermissions

func (dp *DiscordPermissions) HasRequiredPermissions(permission *DiscordPermissions) bool

func (*DiscordPermissions) Remove

func (dp *DiscordPermissions) Remove(flags DiscordPermissionFlags)

func (*DiscordPermissions) Set

func (dp *DiscordPermissions) Set(flags DiscordPermissionFlags)

func (*DiscordPermissions) ToStr

func (dp *DiscordPermissions) ToStr() string

type DuplicateCommandError

type DuplicateCommandError struct {
	Existing *Command
	New      *Command
	Name     string
}

DuplicateCommandError command error

func (DuplicateCommandError) Error

func (e DuplicateCommandError) Error() string

type DuplicateEventHookError

type DuplicateEventHookError struct {
	Existing *EventHook
	New      *EventHook
	Name     string
}

DuplicateEventHookError event hook error

func (DuplicateEventHookError) Error

func (e DuplicateEventHookError) Error() string

type DuplicateServiceError

type DuplicateServiceError struct {
	Existing *Service
	New      *Service
	Name     string
}

DuplicateServiceError service error

func (DuplicateServiceError) Error

func (e DuplicateServiceError) Error() string

type EventHandlerFunc

type EventHandlerFunc func(ctx *Context, ev *events.DiscordEvent, self bool) (handled bool, err error)

EventHandlerFunc handles a discord event and returns whether it handles the event type and if an error occured. self is true if event was fired by bot. eg bot sent a message to someone.

type EventHook

type EventHook struct {
	// Name of the hook
	Name string

	// Description of what the hook does
	Usage string

	// Events that the hook should react to
	Events []events.EventType

	// Check if this hook is deactivated
	Deactivated bool

	// Command behavior
	OnEvent EventHandlerFunc
}

EventHook interface for anything that is supposed to react on a event, besides commands.

type Service

type Service struct {
	Name string

	Description string

	Deactivated bool

	Action ServiceActionFunc

	Data map[string]string // store realtime data here
}

Service struct used to create new services

type ServiceActionFunc

type ServiceActionFunc func(ctx *Context) error

ServiceActionFunc is the action to execute when a service runs.

type TooShortCommandPrefixError

type TooShortCommandPrefixError struct {
	Prefix string
}

TooShortCommandPrefixError short command prefix error

func (TooShortCommandPrefixError) Error

func (e TooShortCommandPrefixError) Error() string