README
¶
go-irc
This package was originally created to only handle message parsing, but has since been expanded to include a small abstraction around a connection and a simple client.
This library is not designed to hide any of the IRC elements from you. If you just want to build a simple chat bot and don't want to deal with IRC in particular, there are a number of other libraries which provide a more full featured client if that's what you're looking for.
This library is meant to stay as simple as possible so it can be a building block for other packages.
This library aims for API compatibility whenever possible. New functions and other additions will most likely not result in a major version increase unless they break the API. This library aims to follow the semver recommendations mentioned on gopkg.in.
Import Paths
All development happens on the master branch and when features are
considered stable enough, a new release will be tagged.
As a result of this, there are multiple import locations.
gopkg.in/irc.v2should be used to develop against the commits tagged as stablegithub.com/go-irc/ircshould be used to develop against the master branch
Development
In order to run the tests, make sure all submodules are up to date. If you are just using this library, these are not needed.
Example
package main
import (
"log"
"net"
"github.com/belak/irc"
)
func main() {
conn, err := net.Dial("tcp", "chat.freenode.net:6667")
if err != nil {
log.Fatalln(err)
}
config := irc.ClientConfig{
Nick: "i_have_a_nick",
Pass: "password",
User: "username",
Name: "Full Name",
Handler: irc.HandlerFunc(func(c *irc.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" && m.FromChannel() {
// Create a handler on all messages.
c.WriteMessage(&irc.Message{
Command: "PRIVMSG",
Params: []string{
m.Params[0],
m.Trailing(),
},
})
}
}),
}
// Create the client
client := irc.NewClient(conn, config)
err = client.Run()
if err != nil {
log.Fatalln(err)
}
}
Major Version Changes
v1
Initial release
v2
- CTCP messages will no longer be rewritten. The decision was made that this library should pass through all messages without mangling them.
- Remove Message.FromChannel as this is not always accurate, while Client.FromChannel should always be accurate.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrZeroLengthMessage is returned when parsing if the input is // zero-length. ErrZeroLengthMessage = errors.New("irc: Cannot parse zero-length message") // ErrMissingDataAfterPrefix is returned when parsing if there is // no message data after the prefix. ErrMissingDataAfterPrefix = errors.New("irc: No message data after prefix") // ErrMissingDataAfterTags is returned when parsing if there is no // message data after the tags. ErrMissingDataAfterTags = errors.New("irc: No message data after tags") // ErrMissingCommand is returned when parsing if there is no // command in the parsed message. ErrMissingCommand = errors.New("irc: Missing message command") )
Functions ¶
Types ¶
type Client ¶
type Client struct {
*Conn
// contains filtered or unexported fields
}
Client is a wrapper around Conn which is designed to make common operations much simpler.
func NewClient ¶
func NewClient(rw io.ReadWriter, config ClientConfig) *Client
NewClient creates a client given an io stream and a client config.
func (*Client) CurrentNick ¶
CurrentNick returns what the nick of the client is known to be at this point in time.
func (*Client) FromChannel ¶ added in v1.1.0
FromChannel takes a Message representing a PRIVMSG and returns if that message came from a channel or directly from a user.
type ClientConfig ¶
type ClientConfig struct {
// General connection information.
Nick string
Pass string
User string
Name string
// 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 ¶
Handler is a simple interface meant for dispatching a message from a Client connection.
type HandlerFunc ¶
HandlerFunc is a simple wrapper around a function which allows it to be used as a Handler.
type Message ¶
type Message struct {
// Each message can have IRCv3 tags
Tags
// Each message can have a Prefix
*Prefix
// Command is which command is being called.
Command string
// Params are all the arguments for the command.
Params []string
}
Message represents a line parsed from the server
func MustParseMessage ¶
MustParseMessage calls ParseMessage and either returns the message or panics if an error is returned.
func ParseMessage ¶
ParseMessage takes a message string (usually a whole line) and parses it into a Message struct. This will return nil in the case of invalid messages.
type Prefix ¶
type Prefix struct {
// Name will contain the nick of who sent the message, the
// server who sent the message, or a blank string
Name string
// User will either contain the user who sent the message or a blank string
User string
// Host will either contain the host of who sent the message or a blank string
Host string
}
Prefix represents the prefix of a message, generally the user who sent it
func ParsePrefix ¶
ParsePrefix takes an identity string and parses it into an identity struct. It will always return an Prefix struct and never nil.
type Reader ¶
type Reader struct {
// DebugCallback is called for each incoming message. The name of this may
// not be stable.
DebugCallback func(string)
// contains filtered or unexported fields
}
Reader is the incoming side of a connection. The data will be buffered, so do not re-use the io.Reader used to create the irc.Reader.
func NewReader ¶
NewReader creates an irc.Reader from an io.Reader. Note that once a reader is passed into this function, you should no longer use it as it is being used inside a bufio.Reader so you cannot rely on only the amount of data for a Message being read when you call ReadMessage.
func (*Reader) ReadMessage ¶
ReadMessage returns the next message from the stream or an error.
type TagValue ¶
type TagValue string
TagValue represents the value of a tag.
func ParseTagValue ¶
ParseTagValue parses a TagValue from the connection. If you need to set a TagValue, you probably want to just set the string itself, so it will be encoded properly.
type Tags ¶
Tags represents the IRCv3 message tags.
func ParseTags ¶
ParseTags takes a tag string and parses it into a tag map. It will always return a tag map, even if there are no valid tags.
type Writer ¶
type Writer struct {
// DebugCallback is called for each outgoing message. The name of this may
// not be stable.
DebugCallback func(line string)
// contains filtered or unexported fields
}
Writer is the outgoing side of a connection.
func (*Writer) Write ¶
Write is a simple function which will write the given line to the underlying connection.
func (*Writer) WriteMessage ¶
WriteMessage writes the given message to the stream
Source Files