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

Documentation

Index

• Constants
• func RunBot(settings *BotSettings) error
• type Bot
  • func (bot *Bot) GetServiceData(srvName string, key string) string
  • func (bot *Bot) RegisterCommand(cmd *Command) error
  • func (bot *Bot) RegisterCommandPrefix(prefix string) 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
• type BotSettings
• type Command
• type CommandActionFunc
• type CommandPermission
  • func NewCommandPermission() CommandPermission
• type Context
  • func NewContext(bot *Bot, ds *discordgo.Session, sig chan os.Signal) *Context
• type DuplicateCommandError
  • func (e DuplicateCommandError) Error() string
• type DuplicateCommandPrefixError
  • func (e DuplicateCommandPrefixError) 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

Constants

const DefaultCommandPrefix = "!"

Functions

func RunBot

func RunBot(settings *BotSettings) error

Types

type Bot

type Bot struct {
	*BotSettings
	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

Get a data value from existing services

func (*Bot) RegisterCommand

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

func (*Bot) RegisterCommandPrefix

func (bot *Bot) RegisterCommandPrefix(prefix string) error

func (*Bot) RegisterEventHook

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

func (*Bot) RegisterService

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

func (*Bot) Run

func (bot *Bot) Run() error

func (*Bot) SetServiceData

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

type BotSettings

type BotSettings struct {
	Token string

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

	// Every option here is added to an array of accepted prefixes later
	// So you can set values in CommandPrefix and/or CommandPrefixes at the same time
	// This also regards the option CommandInvokedByMention
	CommandPrefix           string
	CommandPrefixes         []string
	CommandInvokedByMention bool
}

BotSettings contains the definition of bot behavior. It is used for creating the actual bot.

type Command

type Command struct {
	// Name of the command
	Name string

	// Aliases for the command
	Aliases []string

	// Description of what the command does
	Description string

	// Check if this command is deactivated
	Deactivated bool

	// Command behavior
	Action CommandActionFunc

	// Command permissions
	Permission CommandPermission
}

Command is the interface that every bot command must implement.

type CommandActionFunc

type CommandActionFunc func(ctx *Context, m *discordgo.Message, content string) error

CommandActionFunc is the action to execute when a command is called.

type CommandPermission

type CommandPermission struct {
	// Used for specific User banning on a per command basis
	BannedUserIDs []string // *discordgo.User.ID

	// Users that has been given access to a command even though they do not have the required role.
	AllowedUserIDs []string // *discordgo.User.ID

	// What roles can run this command
	AllowedRoles []string // *discordgo.GuildRole.Role.ID
}

Designed to handle X guilds per bot instance

func NewCommandPermission

func NewCommandPermission() CommandPermission

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 DuplicateCommandError

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

Duplicate command error

func (DuplicateCommandError) Error

func (e DuplicateCommandError) Error() string

type DuplicateCommandPrefixError

type DuplicateCommandPrefixError struct {
	Prefix string
}

Duplicate command prefix error

func (DuplicateCommandPrefixError) Error

func (e DuplicateCommandPrefixError) Error() string

type DuplicateEventHookError

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

Duplicate event hook error

func (DuplicateEventHookError) Error

func (e DuplicateEventHookError) Error() string

type DuplicateServiceError

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

Duplicate event hook error

func (DuplicateServiceError) Error

func (e DuplicateServiceError) Error() string

type EventHandlerFunc

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

EventHandlerFunc handles a discord event and returns whether it handles the event type and if an error occured.

type EventHook

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

	// Description of what the hook does
	Description string

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

	// Check if this hook is deactivated
	Deactivated bool

	// Command behavior
	OnEvent EventHandlerFunc
}

Hook 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
}

type ServiceActionFunc

type ServiceActionFunc func(ctx *Context) error

CommandActionFunc is the action to execute when a command is called.

type TooShortCommandPrefixError

type TooShortCommandPrefixError struct {
	Prefix string
}

Too short command prefix error

func (TooShortCommandPrefixError) Error

func (e TooShortCommandPrefixError) Error() string