bort

README

Bort is an IRC bot with plugin capability, written in the Go programming language.

The bot consists of the bort command, which handles the IRC connection, and the bortplug command, which handles plugins. The bortplug command can be stopped, recompiled with different or reconfigured plugins, and restarted while the bort command stays commected to the IRC server.

Plugins may implement commands, respond to matched text, or push messages asynchronously. Plugins are compiled into the bortplug command. To enable a plugin, add import _ "plugin_import_path" to cmd/bortplug/plugins.go.

Bort looks for a JSON configuration file in ~/.config/bort/bort.conf, which can be overridden with a command line parameter. Bort prioritizes command line parameter values, followed by configuration file, and finally, default values. Plugins have access to the configuration file data, and may look for values of an appropriate key.

See the documentation for more information.

Documentation

Overview

Package bort provides the base for an IRC bot with plugin capability.

The bot consists of the bort command, which handles the IRC connection, and the bortplug command, which handles plugins. The bortplug command can be stopped, recompiled with different or reconfigured plugins, and restarted while the bort command stays commected to the IRC server.

Plugins may implement commands, respond to matched text, or push messages asynchronously. Plugins are compiled into the bortplug command. To enable a plugin, add 'import _ "plugin_import_path"' to cmd/bortplug/plugins.go.

Bort looks for a JSON configuration file in ~/.config/bort/bort.conf, which can be overridden with a command line parameter. Bort prioritizes command line parameter values, followed by configuration file, and finally, default values. Plugins have access to the configuration file data, and may look for values of an appropriate key.

Index

• Constants
• func GetConfig(cfg interface{}) error
• func LoadConfig(cfg interface{}, cfgFile string) error
• func PluginInit(outboxSize uint)
• func Push(msg *Message) error
• func RegisterCommand(cmd, help string, handle HandleFunc) error
• func RegisterMatcher(types MessageType, match string, handle HandleFunc) (uint64, error)
• func RegisterSetup(fn SetupFunc)
• func UnregisterCommand(cmd string) bool
• func UnregisterMatcher(id uint64) bool
• type HandleFunc
• type Message
• type MessageType
• type Plugin
  • func (p *Plugin) Process(in *Message, msgs *[]Message) error
  • func (p *Plugin) Pull(dummy struct{}, msgs *[]Message) error
• type SetupFunc

Constants

const (
	// default address for bort/bortplug communication
	DefaultAddress = ":8075"
)

Functions

func GetConfig

func GetConfig(cfg interface{}) error

GetConfig populates cfg with data from the configuration file

func LoadConfig

func LoadConfig(cfg interface{}, cfgFile string) error

LoadConfig loads the given or default config file

func PluginInit

func PluginInit(outboxSize uint)

PluginInit calls plugin setup functions, sets up the push queue, and generates plugin help text.

func Push

func Push(msg *Message) error

Push enqueues an outgoing message pushed by a plugin.

func RegisterCommand

func RegisterCommand(cmd, help string, handle HandleFunc) error

RegisterCommand registers a command handler for the given name. help is a one line description of the plugin's purpose.

func RegisterMatcher

func RegisterMatcher(types MessageType, match string, handle HandleFunc) (uint64, error)

RegisterMatcher registers a match handler for the given regular expression. types is a bitmask that specifies which message types to consider. The text matched (or that of the first capturing group, if any) will be placed in the Match field of the message passed to handle.

func RegisterSetup

func RegisterSetup(fn SetupFunc)

RegisterSetup registers a function to be run once bort has connected and joined. Plugins should typically call this from init() to ensure fn called.

func UnregisterCommand

func UnregisterCommand(cmd string) bool

UnregisterCommand unrigesters the command handler for the given name, if found, and returns whether a handler was removed.

func UnregisterMatcher

func UnregisterMatcher(id uint64) bool

UnregisterMatcher unrigesters the match handler for the given ID, if found, and returns whether a handler was removed.

Types

type HandleFunc

type HandleFunc func(in, out *Message) error

HandleFunc provides an interface for handling IRC messages.

type Message

type Message struct {
	// incoming and outgoing
	Type    MessageType
	Context string
	Text    string
	// ignored for outgoing
	Nick    string
	User    string
	Host    string
	IRCCmd  string
	Params  []string
	Command string
	Args    string
	Match   string
}

Message contains all data needed to deal with incoming and outgoing IRC messages.

type MessageType

type MessageType int

MessageType is a bitmapped IRC message type.

const (
	None    MessageType = iota
	PrivMsg MessageType = 1 << iota
	Action
	Join
	Part
	All MessageType = 1<<iota - 1
)

message types

type Plugin

type Plugin struct{}

Plugin provides RPC calls for bort to pass messages to bortplug for handling, and to retrieve pending push messages.

func (*Plugin) Process

func (p *Plugin) Process(in *Message, msgs *[]Message) error

Process inspects and processes an incoming message.

func (*Plugin) Pull

func (p *Plugin) Pull(dummy struct{}, msgs *[]Message) error

Pull fetches queued messages pushed by plugins.

type SetupFunc

type SetupFunc func() error

SetupFunc provides a means for plugins to initialize themselves