ircutil

README

ircutil

Utility for connecting to multiple IRC servers and storing connection details.

Developed for use with Inami IRC Bot. Check out the readme and use go get github.com/jasonpuglisi/inami-irc-bot to try it out.

Overview

Creates connections to an unlimited number of IRC networks with support for server passwords and user NickServ passwords. Runs basic validation on connection details.

Supports sending various pre-defined IRC message types, as well as raw messages (see actions.go).

Implements a command interface to be used with bots or other programs that can respond to text triggers. Also implements a data storage interface for bots or other programs to store persistent user data in a variety of scopes.

Has built-in logging functions to distinguish IRC connections/clients (see utility.go).

Documentation

Overview

Package ircutil provides utility functions for handling IRC connections and operations.

Package ircutil provides utility functions for handling IRC connections and operations.

Package ircutil provides utility functions for handling IRC connections and operations.

Index

• func AddCommand(cmdMap CmdMap, key string, cmdFunc CmdFunc)
• func EstablishConnection(client *Client) error
• func ExecCommand(client *Client, key string, command *Command, message *Message) error
• func GetClientPrefix(client *Client) string
• func GetNick(src string) string
• func IsChannel(target string) bool
• func Log(client *Client, message string)
• func Logf(client *Client, format string, a ...interface{})
• func SendJoin(client *Client, channel string, pass string)
• func SendModeUser(client *Client, modes string)
• func SendNick(client *Client, nick string)
• func SendNickRandom(client *Client)
• func SendNickservPass(client *Client, pass string)
• func SendNotice(client *Client, target string, msg string)
• func SendPart(client *Client, channel string, msg string)
• func SendPass(client *Client, pass string)
• func SendPing(client *Client, msg string)
• func SendPong(client *Client, msg string)
• func SendPrivmsg(client *Client, target string, msg string)
• func SendResponse(client *Client, src string, target string, msg string)
• func SendUser(client *Client, user string, real string)
• type Authentication
• type Client
• type CmdFunc
• type CmdMap
  • func InitCommands() CmdMap
• type Command
• type Data
• type Message
• type Server
• type Settings
• type User

Functions

func AddCommand

func AddCommand(cmdMap CmdMap, key string, cmdFunc CmdFunc)

AddCommand adds a function to a command map with a string key.

func EstablishConnection

func EstablishConnection(client *Client) error

EstablishConnection establishes a connection to the specified IRC server using the specified user information. It sends initial messages as required by the IRC protocol.

func ExecCommand

func ExecCommand(client *Client, key string, command *Command,
	message *Message) error

ExecCommand executes a command given a string key, or returns an error if the key is not a valid command.

func GetClientPrefix

func GetClientPrefix(client *Client) string

GetClientPrefix formats the client server and user ids into a prefix string that's useful terminal output.

func GetNick

func GetNick(src string) string

GetNick isolates a nickname from a source string.

func IsChannel

func IsChannel(target string) bool

IsChannel determines whether or not a target is a channel. If it is not a channel, the target will be a user.

func Log

func Log(client *Client, message string)

Log adds a client prefix and logs a message.

func Logf

func Logf(client *Client, format string, a ...interface{})

Logf formats a string, adds a client prefix, and logs a message.

func SendJoin

func SendJoin(client *Client, channel string, pass string)

SendJoin attaches to a channel with an optional password. An empty string indicates no password.

func SendModeUser

func SendModeUser(client *Client, modes string)

SendModeUser updates user modes.

func SendNick

func SendNick(client *Client, nick string)

SendNick sets or updates a nickname.

func SendNickRandom

func SendNickRandom(client *Client)

SendNickRandom sets or updates a nickname to a random one.

func SendNickservPass

func SendNickservPass(client *Client, pass string)

SendNickservPass authenticates a nickname with Nickserv.

func SendNotice

func SendNotice(client *Client, target string, msg string)

SendNotice sends a notice to a user or channel.

func SendPart

func SendPart(client *Client, channel string, msg string)

SendPart detaches from a channel with an optional message. An empty string indicates no message.

func SendPass

func SendPass(client *Client, pass string)

SendPass authenticates with a password-protected server.

func SendPing

func SendPing(client *Client, msg string)

SendPing sends a ping to a server.

func SendPong

func SendPong(client *Client, msg string)

SendPong replies to a server ping.

func SendPrivmsg

func SendPrivmsg(client *Client, target string, msg string)

SendPrivmsg sends a message to a user or channel.

func SendResponse

func SendResponse(client *Client, src string, target string, msg string)

SendResponse determines whether a message should be sent to a user or or channel, and sends the message accordingly.

func SendUser

func SendUser(client *Client, user string, real string)

SendUser sends initial user details upon server connection.

Types

type Authentication

type Authentication struct {
	// (Optional) Server password to connect to a server. Empty string for
	// none. Default: ""
	ServerPassword string `json:"serverPassword"`
	// (Optional) Nickserv password to identify user with nickserv. Empty
	// string for none. Default: ""
	Nickserv string `json:"nickserv"`
}

Authentication stores authentication credentials for servers and nicknames.

type Client

type Client struct {
	// ID of server to use in connection.
	ServerID string `json:"serverId"`
	// ID of user to use in connection.
	UserID string `json:"userId"`
	// (Optional) List of channels to join upon connection and authentication
	// (if specified). Channels must be prefixed with "#" (e.g., "#channel").
	// Channels with a password must have a space between the channel name and
	// password (e.g., "#channel pass"). Default: []
	Channels []string `json:"channels"`
	// (Optional) String of user modes to be set upon connection and
	// authentication (if specified). Must have a "+" before all modes to be
	// set and a "-" before all modes to be unset (e.g., "+i-x"). Default: ""
	Modes string `json:"modes"`
	// (Optional) List of client admin nicknames able to run commands set to
	// admin-only. Default: []
	Admins []string `json:"admins"`
	// (Optional) Authentication credentials to used in connection.
	// Defaults: All nested defaults
	Authentication `json:"authentication"`
	// Other non-configurable values.
	Data     Data
	DataFile *string
	CmdMap
	Commands []Command
	Debug    bool
	Ready    func(*Client)
	Done     chan bool
	Server   *Server
	User     *User
	Conn     net.Conn
	Nick     string
}

Client stores client/connection settings and credentials.

type CmdFunc

type CmdFunc func(*Client, *Command, *Message)

CmdFunc is a function that's executed for a command, providing necessary details to perform an action.

type CmdMap

type CmdMap map[string]CmdFunc

CmdMap is a map that stores pointers to functions which can be called using strings from config.

func InitCommands

func InitCommands() CmdMap

InitCommands returns an empty map that can store pointers to functions which may be called using strings from config.

type Command

type Command struct {
	// List of strings that will trigger the command. Triggers must not contain
	// the command symbol, as it will be checked for automatically.
	Triggers []string `json:"triggers"`
	// Function that will be executed when the command is triggered.
	Function string `json:"function"`
	// (Optional) String of arguments that must follow the command. Mandatory
	// arguments must have chevrons around them, and optional arguments must have
	// square brackets around them (e.g., "<arg1> <arg2> [arg3]"). Default: ""
	Arguments string `json:"arguments"`
	// (Optional) Command settings to override default command settings. See
	// default command settings (above) for descriptions of each setting.
	// Defaults: Default command settings
	Settings `json:"settings"`
}

Command stores command triggers, execution details, and settings, with the ability to override default settings.

type Data

type Data map[string]map[string]map[string]map[string]map[string]string

Data stores persistent information in key-value pairs.

Format: "client_prefix": { "scope": { "owner": { "data_group": {
        "key": "value" } } } }

Scope must be "user", "channel", or "client".

type Message

type Message struct {
	Source  string
	Target  string
	Trigger string
	Args    []string
}

Message stores information about the message the triggered the command.

type Server

type Server struct {
	// String ID of the server. Used to identify the server in a client. Must be
	// alphanumeric.
	ID string `json:"id"`
	// Hostname of server. Can be an IP address or domain name.
	Host string `json:"host"`
	// (Optional) Port of server. Default: 6697
	Port uint16 `json:"port"`
	// (Optional) Whether or not the server port should be connected to using
	// SSL/TLS. Default: true if port is 6697, false otherwise
	Secure bool `json:"secure"`
}

Server stores server connection settings.

type Settings

type Settings struct {
	// (Optional) Whether or not a command is case-sensitive. Default: true
	CaseSensitive bool `json:"caseSensitive"`
	// (Optional) Symbol/string that must be prefixed to a command trigger for
	// it to be detected. Default: "!"
	Symbol string `json:"symbol"`
	// (Optional) Array of places a command can be used. Contains "channel" for
	// in a channel, and/or "direct" for in a private message to the client.
	// Default: ["channel"]
	Scope []string `json:"scope"`
	// (Optional) Whether or not a command can only be used by client admins.
	// Default: false
	Admin bool `json:"admin"`
}

Settings stores command settings that can be used as defaults or overrode on a per-command basis.

type User

type User struct {
	// String ID of user. Used to identify the user in a client. Must be
	// alphanumeric.
	ID string `json:"id"`
	// Nickname of client.
	Nick string `json:"nick"`
	// (Optional) Username of client. Default: Same as nickname lowercased
	User string `json:"user"`
	// (Optional) Realname of client. Default: Same as nickname
	Real string `json:"real"`
}

User stores user settings.