ircb

README

ircb

** broken **

friendly channel bot

• karma system
• http title parser
• bot master must be identified with services (uses NickServ ACC)

help

See docs and GoDoc and visit ##ircb on Freenode for help

usage

quick setup (requires Go to compile):

1. log in to the user you would like to use ircb with,
2. change directory to the path you would like ircb to live (can be empty)

curl https://raw.githubusercontent.com/aerth/ircb/master/makefile > makefile
make
vim config.json
./ircb

authentication

send two private messages to bot: /msg bot !help and /msg bot $upgrade

the first message from master, ircb will check if user is identified with services if so, you will be 'authenticated' for 5 minutes

the second command, it will try to fetch newest source code and rebuild and redeploy itself if fails, should private message master reason

Plugin system

See Plugin Repository for current list

Plugins must be unique name and package import path

Currently can't be unloaded

Plugins can do unknown things

Install new plugin 'skeleton' with master command $fetch skeleton

Load compiled plugin 'new.so' with master command $plugin new

Documentation

Index

• Constants
• Variables
• func DefaultCommandMap() map[string]Command
• func DefaultMasterMap() map[string]Command
• type Command
• type Config
  • func ConfigFromJSON(b []byte) (*Config, error)
  • func NewDefaultConfig() *Config
  • func (c Config) Marshal() ([]byte, error)
  • func (config *Config) NewConnection() *Connection
  • func (cfg Config) Parse(input string) *IRC
• type Connection
  • func (c *Connection) AddCommand(name string, fn Command)
  • func (c *Connection) AddMasterCommand(name string, fn Command)
  • func (c *Connection) Close() error
  • func (c *Connection) Connect() (err error)
  • func (c *Connection) Database() *bolt.DB
  • func (c *Connection) Diamond() *diamond.System
  • func (c *Connection) MarshalConfig() []byte
  • func (c *Connection) MasterCheck()
  • func (c *Connection) RemoveCommand(name string)
  • func (c *Connection) RemoveMasterCommand(name string)
  • func (c *Connection) Respawn()
  • func (c *Connection) Send(irc IRC)
  • func (c *Connection) SendMaster(format string, i ...interface{})
  • func (c *Connection) Write(b []byte) (n int, err error)
• type IRC
  • func Parse(input string) *IRC
  • func (irc IRC) Encode() []byte
  • func (irc *IRC) Reply(c *Connection, s string)
  • func (irc *IRC) ReplyUser(c *Connection, s string)
• type PluginInitFunc

Constants

const (
	Green     = "\x033"
	Red       = "\x035"
	Purple    = "\x036"
	Yellow    = "\x038"
	GreenBold = "\x039"
)

Variables

var ErrNoPlugin = fmt.Errorf("plugin not found")

ErrNoPlugin when plugin is not found

var ErrNoPluginSupport = fmt.Errorf("no plugin support")

ErrNoPluginSupport when compiled with no CGO or without 'plugins' tag

var ErrPluginInv = fmt.Errorf("invalid plugin")

ErrPluginInv when plugin does not have proper Init func

var LoadPlugin = func(c *Connection, s string) error {
	return ErrNoPluginSupport
}

LoadPlugin loads the named plugin file This is a stub, and should be replaced if ircb is built with plugin support

Functions

func DefaultCommandMap

func DefaultCommandMap() map[string]Command

DefaultCommandMap returns default command map

func DefaultMasterMap

func DefaultMasterMap() map[string]Command

DefaultMasterMap returns default master command map

Types

type Command

type Command func(c *Connection, irc *IRC)

Command is what executes using a parsed IRC message irc message '!echo arg1 arg2' gets parsed as:

'irc.Command = echo', 'irc.CommandArguments = []string{"arg1","arg2"}

Command will be executed if it is in CommandMap or MasterMap Map Commands before connecting:

ircb.CommandMap
ircb.DefaultCommandMaps() // load defaults, optional.
ircb.CommandMap["echo"] = CommandEcho
// Add a new command called hello, executed with !hello

!hello responds in channel, using name of user commander

ircb.CommandMap["hello"] = func(c *Connection, irc *IRC){
	irc.Reply(c, fmt.Sprintf("hello, %s!", irc.ReplyTo))
	}
// Command parser will deal with authentication.
// This makes adding new master commands easy:
ircb.MasterMap["stat"] = func(c *Connection, irc.*IRC){
	irc.ReplyUser(c, fmt.Sprintf("lines received: %v", c.lines))
}

Reply with irc.ReplyUser (for /msg reply) or irc.Reply (for channel)

type Config

type Config struct {
	Host          string // in the form 'host:port'
	Nick          string
	Master        string // in the form 'master:prefix'
	CommandPrefix string
	Channels      string // comma separated channels to autojoin
	UseSSL        bool
	InvalidSSL    bool
	ParseLinks    bool
	Define        bool
	Verbose       bool
	Karma         bool
	Diamond       bool   // use diamond system
	DiamondSocket string // path to socket
	Database      string // path to boltdb (can be empty to use bolt.db)
	AuthMode      int    // 0 ACC (freenode, recommended), 1 STATUS, -1 none
}

Config holds configurable variables for ircb client

func ConfigFromJSON

func ConfigFromJSON(b []byte) (*Config, error)

ConfigFromJSON loads a new config from json encoded bytes. It starts with a NewDefaultConfig, so not all fields must be present in json code.

func NewDefaultConfig

func NewDefaultConfig() *Config

NewDefaultConfig returns the default config, minimal changes would be Host,Nick,Master for typical usage.

func (Config) Marshal

func (c Config) Marshal() ([]byte, error)

Marshal into json encoded bytes from config values

func (*Config) NewConnection

func (config *Config) NewConnection() *Connection

NewConnection returns an unconnected client from the given config

func (Config) Parse

func (cfg Config) Parse(input string) *IRC

Parse a command in context of nickname, command prefix Does not handle master command parsing

type Connection

type Connection struct {
	Log        *log.Logger
	HTTPClient *http.Client       // customize user agent, proxy, tls, redirects, etc
	CommandMap map[string]Command // map of command names to Command functions
	MasterMap  map[string]Command // map of master command names to Command functions
	// contains filtered or unexported fields
}

Connection will be divided into:

Client
Connection

func (*Connection) AddCommand

func (c *Connection) AddCommand(name string, fn Command)

AddCommand adds a new public command, named 'name' to the CommandMap

func (*Connection) AddMasterCommand

func (c *Connection) AddMasterCommand(name string, fn Command)

AddMasterCommand adds a new master command, named 'name' to the MasterMap

func (*Connection) Close

func (c *Connection) Close() error

Close all connections and databases, remove diamond.socket

func (*Connection) Connect

func (c *Connection) Connect() (err error)

Connect dials the host

func (*Connection) Database

func (c *Connection) Database() *bolt.DB

Database returns ircb's database system, will be nil if not connected

func (*Connection) Diamond

func (c *Connection) Diamond() *diamond.System

Diamond returns ircb's diamond system, will be nil if not connected or not configured with 'Diamond: true'

func (*Connection) MarshalConfig

func (c *Connection) MarshalConfig() []byte

MarshalConfig encodes the connection's config as JSON

func (*Connection) MasterCheck

func (c *Connection) MasterCheck()

MasterCheck sends a private message to NickServ to authenticate master user

-1 no auth mode
0 default, freenode and oragono ACC style
1 STATUS style

func (*Connection) RemoveCommand

func (c *Connection) RemoveCommand(name string)

RemoveCommand removes a public command, named 'name' to the CommandMap

func (*Connection) RemoveMasterCommand

func (c *Connection) RemoveMasterCommand(name string)

RemoveMasterCommand adds a new public command, named 'name' to the CommandMap

func (*Connection) Respawn

func (c *Connection) Respawn()

Respawn closes connections after executing self, can be called at any time.

func (*Connection) Send

func (c *Connection) Send(irc IRC)

Send IRC message (uses To and Message fields)

func (*Connection) SendMaster

func (c *Connection) SendMaster(format string, i ...interface{})

SendMaster sends formatted text to master user

func (*Connection) Write

func (c *Connection) Write(b []byte) (n int, err error)

Write to irc connection, adding '\r\n'

type IRC

type IRC struct {
	Raw       string   // As received
	Verb      string   // Using 'Verb' because we took 'Command' :)
	ReplyTo   string   // From user or channel
	To        string   // can be c.config.Nick
	Channel   string   // From channel (can be user)
	IsCommand bool     // Is a public command
	IsWhisper bool     // Is not from channel
	Message   string   // Parsed message (can still include command prefix)
	Command   string   // Parsed command (stripped of command prefix)
	Arguments []string // Parsed arguments (can be nil)

}

IRC is a parsed message received from IRC server

func Parse

func Parse(input string) *IRC

Parse input string into IRC struct. To parse fully, use config method cfg.Parse(input string)

:Name COMMAND parameter list

Where list could begin with ':', which states the rest of list is just one item Sending, we use this format:

:COMMAND argument :string\r\n
:PRIVMSG ##ircb :hello world\r\n

func (IRC) Encode

func (irc IRC) Encode() []byte

Encode prepares an IRC message to be sent to server Uses only the To and Message fields, so it is easy to write an IRC such as:

irc := IRC{To: "##ircb", Message: "hello"}
c.Send(irc)
c.Send(IRC{To:"username", Message:"hello"})

func (*IRC) Reply

func (irc *IRC) Reply(c *Connection, s string)

Reply replies to an irc message, preferring a channel

func (*IRC) ReplyUser

func (irc *IRC) ReplyUser(c *Connection, s string)

ReplyUser doesnt send to #channel, only sends

type PluginInitFunc

type PluginInitFunc (func(c *Connection) error)

PluginInitFunc gets called when plugin is loaded. Init(c *Connection) error