PACKAGE DOCUMENTATION
package irc
import "github.com/kballard/goirc/irc"
Package irc implements the IRC protocol and provides callback support.
CONSTANTS
const (
// Invoked when the connection is established with the server.
// It is not safe to send messages to the server in response to this. No
// login has been performed yet.
// Args: (*Conn)
INIT = "irc:init"
// Invoked when the server login has finished. It is now safe to send
// messages to the server.
// Args: (*Conn)
CONNECTED = "irc:connected"
// Invoked when the connection with the server is terminated.
// Args: (*Conn)
DISCONNECTED = "irc:disconnected"
// Invoked for privmsgs that encode CTCP ACTIONs.
// Args: (*Conn, Line)
// The Line will have 1 arg, which is the action text.
// Line.Dst will contain the original target of the PRIVMSG.
ACTION = "irc:action"
// Invoked for privmsgs that encode CTCP messages.
// Args: (*Conn, Line)
// The Line will have 1 or 2 args, the first is the CTCP command, the
// second is the remainder, if any.
// Line.Dst will contain the original target of the PRIVMSG.
CTCP = "irc:ctcp"
// Invoked for notices that encode CTCP messages.
// Args: (*Conn, Line)
// The Line will have 1 or 2 args, the first is the CTCP command, the
// second is the remainder, if any.
// Line.Dst will contain the original target of the NOTICE.
CTCPREPLY = "irc:ctcpreply"
)
Special callbacks emitted by the library.
TYPES
type Config struct {
Host string
Port uint // if 0, 6667 is used, or 6697 if SSL
Password string
SSL bool // set to true to use SSL
SSLConfig *tls.Config
Nick string
User string
RealName string
Timeout time.Duration // timeout for the Connect. 0 means no timeout.
AllowFlood bool // set to true to disable flood protection
PingInterval time.Duration // defaults to 3 minutes, set to -1 to disable
// Init is called immediately after the connection is established but
// before logging in. This is the right place to set up handlers.
// If Init is called, Connect() will not return an error.
// Required.
Init func(HandlerRegistry)
// NickInUse is called when the chosen nickname is already in use.
// Optional.
// It's also given the 3-digit error code provided by the server,
// e.g. 432 indicates invalid characters in the nick, and 433 indicates
// the nickname was already in use.
// It must return a new nickname.
// If nil, the default behavior of appending a _ is uesd.
NickInUse func(oldnick string, errcode int) string
}
Config represents the configuration used to set up a server connection.
After being passed to Connect(), the Config object can be thrown away.
type Conn struct {
// contains filtered or unexported fields
}
Conn represents a connection to a single IRC server. The only way to get
one of these is through a callback. If a callback wants to pass this to
another goroutine, it must call the SafeConn() method and use that
instead.
func (c *Conn) Action(dst, msg string)
Send an action to the server.
func (c *Conn) AddHandler(event string, f func(*Conn, Line)) callback.CallbackIdentifier
AddHandler adds a handler for an IRC command. The return value can be
passed to RemoveHandler() later.
func (c *Conn) CTCP(dst, command, args string)
Send a CTCP message to the server.
func (c *Conn) CTCPReply(dst, command, args string)
Send a CTCP reply to the server.
func (c *Conn) Connected() bool
Connected returns whether the Conn is currently connected. When the Conn
disconnects from the server, it still processes any outstanding lines or
invokes.
func (c *Conn) DefaultCTCPHandler(line Line)
DefaultCTCPHandler processes an incoming CTCP message with some default
behavior. For example, it will respond to PING, TIME, and VERSION
requests. This function is called by default if no handler is registered
for CTCP. If one is registered for CTCP, you may call this function
yourself in order to invoke default behavior.
func (c *Conn) Join(channels, keys []string)
Send a JOIN to the server.
func (c *Conn) Me() User
Me returns the User object that represents the client. The Nick is
guaranteed to be correct. The User/Host portions may not be.
func (c *Conn) Nick(newnick string)
Send a NICK to the server.
func (c *Conn) Notice(dst, msg string)
Send a NOTICE to the server.
func (c *Conn) Part(channels []string, msg string)
send a PART to the server.
func (c *Conn) Privmsg(dst, msg string)
Send a PRIVMSG to the server.
func (c *Conn) Quit(msg string)
Send a QUIT to the server.
func (c *Conn) Raw(msg string)
Send a raw line to the server.
func (c *Conn) RemoveHandler(ident callback.CallbackIdentifier)
RemoveHandler removes a previously-added handler.
func (c *Conn) SafeConn() SafeConn
SafeConn returns a SafeConn object that can be passed to another
goroutine. Note, despite the SafeConn object itself being thread-safe,
this method may only be called from the connection's goroutine.
func (c *Conn) Server() string
Returns the host:port pair for the server.
func (c *Conn) Shutdown()
Forcibly terminates the connection.
type HandlerRegistry interface {
AddHandler(name string, f func(*Conn, Line)) callback.CallbackIdentifier
RemoveHandler(callback.CallbackIdentifier)
}
type Line struct {
Src User
Command string
Args []string
Raw string
Time time.Time
// Dst is only filled in for the special commands such as ACTION, CTCP, and
// CTCPReply. It denotes the target the PRIVMSG/NOTICE was sent to.
Dst string
// contains filtered or unexported fields
}
func (l *Line) SrcIsMe() bool
SrcIsMe returns if the Src is the same as Me.
type SafeConn interface {
// Me returns the user at the time the SafeConn was created
Me() User
// Server returns the host:port pair that identifies the server
Server() string
// Connected returns whether the connection is still connected
Connected() bool
// Invoke runs the given function on the connection's goroutine
Invoke(func(*Conn)) bool
// AddHandler is the same as Conn.AddHandler
AddHandler(name string, f func(*Conn, Line)) callback.CallbackIdentifier
// RemoveHandler is the same as Conn.RemoveHandler
RemoveHandler(callback.CallbackIdentifier)
// Conn methods
Raw(line string) bool
Privmsg(dst, msg string) bool
Action(dst, msg string) bool
Notice(dst, msg string) bool
CTCP(dst, command, args string) bool
CTCPReply(dst, command, args string) bool
Quit(msg string) bool
Nick(newnick string) bool
Join(channels, keys []string) bool
Part(channels []string, msg string) bool
}
SafeConn is a set of methods that may be called from any goroutine. They
mostly mirror methods from Conn directly, but with a bool return value.
This return value is false if the connection was already closed, or true
if the write succeeded (note: this does not mean the server successfully
received the message).
func Connect(config Config) (SafeConn, error)
Connect initiates a connection to an IRC server identified by the
Config. It returns once the connection has been established. If a
connection could not be established, an error is returned.
type User struct {
// Nick, User, and Host will only be present if the user is of the form
// nick[!user]@host Notably, a server host sender will have all three fields
// as the empty string.
Nick, User, Host string
Raw string
}
func (u User) Ident() string
Returns the user@host string, or just host if no user, or "" if this
isn't a user.
func (u User) String() string
Returns the user's nickname, or the raw string if there is no nickname.