ircx

README

ircx

This repo has been archived because in the go-irc v4.0.0 release, the additional features provided here were merged back in to the main repo as experimental features.

Import Paths

All development happens on the master branch and when features are considered stable enough, a new release will be tagged.

Example

package main

import (
	"log"
	"net"

	"github.com/go-irc/irc.v4"
	"github.com/go-irc/ircx.v0"
)

func main() {
	conn, err := net.Dial("tcp", "chat.freenode.net:6667")
	if err != nil {
		log.Fatalln(err)
	}

	config := ircx.ClientConfig{
		Nick: "i_have_a_nick",
		Pass: "password",
		User: "username",
		Name: "Full Name",
		Handler: ircx.HandlerFunc(func(c *ircx.Client, m *irc.Message) {
			if m.Command == "001" {
				// 001 is a welcome event, so we join channels there
				c.Write("JOIN #bot-test-chan")
			} else if m.Command == "PRIVMSG" && c.FromChannel(m) {
				// Create a handler on all messages.
				c.WriteMessage(&irc.Message{
					Command: "PRIVMSG",
					Params: []string{
						m.Params[0],
						m.Trailing(),
					},
				})
			}
		}),
	}

	// Create the client
	client := ircx.NewClient(conn, config)
	err = client.Run()
	if err != nil {
		log.Fatalln(err)
	}
}

Major Version Changes

v1

Initial release (In progress)

Documentation

Index

• type ChannelState
• type Client
  • func NewClient(rwc io.ReadWriteCloser, config ClientConfig) *Client
  • func (c *Client) CapAvailable(capName string) bool
  • func (c *Client) CapEnabled(capName string) bool
  • func (c *Client) CapRequest(capName string, required bool)
  • func (c *Client) CurrentNick() string
  • func (c *Client) FromChannel(m *irc.Message) bool
  • func (c *Client) Run() error
  • func (c *Client) RunContext(ctx context.Context) error
• type ClientConfig
• type Handler
• type HandlerFunc
  • func (f HandlerFunc) Handle(c *Client, m *irc.Message)
• type ISupportTracker
  • func NewISupportTracker() *ISupportTracker
  • func (t *ISupportTracker) GetList(key string) ([]string, bool)
  • func (t *ISupportTracker) GetMap(key string) (map[string]string, bool)
  • func (t *ISupportTracker) GetPrefixMap() (map[rune]rune, bool)
  • func (t *ISupportTracker) GetRaw(key string) (string, bool)
  • func (t *ISupportTracker) Handle(msg *irc.Message) error
  • func (t *ISupportTracker) IsEnabled(key string) bool
• type Tracker
  • func NewTracker(isupport *ISupportTracker) *Tracker
  • func (t *Tracker) GetChannel(name string) *ChannelState
  • func (t *Tracker) Handle(msg *irc.Message) error
  • func (t *Tracker) ListChannels() []string

Types

type ChannelState

type ChannelState struct {
	Name  string
	Topic string
	Users map[string]struct{}
}

ChannelState represents the current state of a channel, including the name, topic, and all users in it.

type Client

type Client struct {
	*irc.Conn

	ISupport *ISupportTracker
	Tracker  *Tracker
	// contains filtered or unexported fields
}

Client is a wrapper around irc.Conn which is designed to make common operations much simpler. It is safe for concurrent use.

func NewClient

func NewClient(rwc io.ReadWriteCloser, config ClientConfig) *Client

NewClient creates a client given an io stream and a client config.

func (*Client) CapAvailable

func (c *Client) CapAvailable(capName string) bool

CapAvailable allows you to check if a CAP is available on this server. Note that it will not be populated until after the CAP handshake is done, so it is recommended to wait to check this until after a message like 001.

func (*Client) CapEnabled

func (c *Client) CapEnabled(capName string) bool

CapEnabled allows you to check if a CAP is enabled for this connection. Note that it will not be populated until after the CAP handshake is done, so it is recommended to wait to check this until after a message like 001.

func (*Client) CapRequest

func (c *Client) CapRequest(capName string, required bool)

CapRequest allows you to request IRCv3 capabilities from the server during the handshake. The behavior is undefined if this is called before the handshake completes so it is recommended that this be called before Run. If the CAP is marked as required, the client will exit if that CAP could not be negotiated during the handshake.

func (*Client) CurrentNick

func (c *Client) CurrentNick() string

CurrentNick returns what the nick of the client is known to be at this point in time.

func (*Client) FromChannel

func (c *Client) FromChannel(m *irc.Message) bool

FromChannel takes a Message representing a PRIVMSG and returns if that message came from a channel or directly from a user.

func (*Client) Run

func (c *Client) Run() error

Run starts the main loop for this IRC connection. Note that it may break in strange and unexpected ways if it is called again before the first connection exits.

func (*Client) RunContext

func (c *Client) RunContext(ctx context.Context) error

RunContext is the same as Run but a context.Context can be passed in for cancelation.

type ClientConfig

type ClientConfig struct {
	// General connection information.
	Nick string
	Pass string
	User string
	Name string

	// If this is set to true, the ISupport value on the client struct will be
	// non-nil.
	EnableISupport bool

	// If this is set to true, the Tracker value on the client struct will be
	// non-nil.
	EnableTracker bool

	// Connection settings
	PingFrequency time.Duration
	PingTimeout   time.Duration

	// SendLimit is how frequent messages can be sent. If this is zero,
	// there will be no limit.
	SendLimit time.Duration

	// SendBurst is the number of messages which can be sent in a burst.
	SendBurst int

	// Handler is used for message dispatching.
	Handler Handler
}

ClientConfig is a structure used to configure a Client.

type Handler

type Handler interface {
	Handle(*Client, *irc.Message)
}

Handler is a simple interface meant for dispatching a message from a Client connection.

type HandlerFunc

type HandlerFunc func(*Client, *irc.Message)

HandlerFunc is a simple wrapper around a function which allows it to be used as a Handler.

func (HandlerFunc) Handle

func (f HandlerFunc) Handle(c *Client, m *irc.Message)

Handle calls f(c, m).

type ISupportTracker

type ISupportTracker struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

ISupportTracker tracks the ISUPPORT values returned by servers and provides a convenient way to access them.

From http://www.irc.org/tech_docs/draft-brocklesby-irc-isupport-03.txt

005 RPL_ISUPPORT.

func NewISupportTracker

func NewISupportTracker() *ISupportTracker

NewISupportTracker creates a new tracker instance with a set of sane defaults if the server is missing them.

func (*ISupportTracker) GetList

func (t *ISupportTracker) GetList(key string) ([]string, bool)

GetList will check for list ISupport values.

func (*ISupportTracker) GetMap

func (t *ISupportTracker) GetMap(key string) (map[string]string, bool)

GetMap will check for map ISupport values.

func (*ISupportTracker) GetPrefixMap

func (t *ISupportTracker) GetPrefixMap() (map[rune]rune, bool)

GetPrefixMap gets the mapping of mode to symbol for the PREFIX value. Unfortunately, this is fairly specific, so it can only be used with PREFIX.

func (*ISupportTracker) GetRaw

func (t *ISupportTracker) GetRaw(key string) (string, bool)

GetRaw will get the raw ISupport values.

func (*ISupportTracker) Handle

func (t *ISupportTracker) Handle(msg *irc.Message) error

Handle needs to be called for all 005 IRC messages, but it is fine to call it with all.

func (*ISupportTracker) IsEnabled

func (t *ISupportTracker) IsEnabled(key string) bool

IsEnabled will check for boolean ISupport values.

type Tracker

type Tracker struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Tracker provides a convenient interface to track users, the channels they are in, and what modes they have in those channels.

func NewTracker

func NewTracker(isupport *ISupportTracker) *Tracker

NewTracker creates a new tracker instance.

func (*Tracker) GetChannel

func (t *Tracker) GetChannel(name string) *ChannelState

GetChannel will look up the ChannelState for a given channel name. It will return nil if the channel is unknown.

func (*Tracker) Handle

func (t *Tracker) Handle(msg *irc.Message) error

Handle needs to be called for all 001, 332, 353, JOIN, TOPIC, PART, KICK, QUIT, and NICK messages, but it is fine to call it with all. Note that this will not handle calling the underlying ISupportTracker's Handle method.

func (*Tracker) ListChannels

func (t *Tracker) ListChannels() []string

ListChannels will list the names of all known channels.