goirc

GoIRC can automatically track the state of all nicks in the channels the client is present in. This feature is disabled by default to save resources.

To enable it, call EnableStateTracking(). To disable it, call DisableStateTracking().

Warning: Do not enable or disable state tracking while already connected to an IRC server, as this will likely result in an inconsistent state and produce warnings to STDERR.

c.EnableStateTracking()
// ... later
c.DisableStateTracking()

To acquire the GoIRC client framework, use the following Go command:

go get github.com/fluffle/goirc/client

You can create a client in two ways: using a quick helper for simple connections or manually configuring a Config object for more control.

Simple Client

Use irc.SimpleClient("nick") for a basic setup.

Configured Client

Use irc.NewConfig("nick") to customize settings such as SSL, server address, and nickname generation logic, then pass the config to irc.Client(cfg).

// Simple client
c := irc.SimpleClient("nick")

// Configured client
cfg := irc.NewConfig("nick")
cfg.SSL = true
cfg.SSLConfig = &tls.Config{ServerName: "irc.freenode.net"}
cfg.Server = "irc.freenode.net:7000"
cfg.NewNick = func(n string) string { return n + "^" }
c = irc.Client(cfg)

GoIRC uses an event-driven model. You can register handlers for specific events using the HandleFunc method on the client instance. Common events include irc.CONNECTED and irc.DISCONNECTED.

Handlers receive a *irc.Conn (the connection object) and a *irc.Line (the raw IRC message line).

c.HandleFunc(irc.CONNECTED, func(conn *irc.Conn, line *irc.Line) {
    conn.Join("#channel")
})

quit := make(chan bool)
c.HandleFunc(irc.DISCONNECTED, func(conn *irc.Conn, line *irc.Line) {
    quit <- true
})

There are two primary ways to initiate a connection:

1. Connect(): Uses the server address defined in the client's configuration.
2. ConnectTo(server): Connects to a specific server address provided as an argument, overriding the configured server.

Note: If using a SimpleClient, you must set the Server field in the configuration before calling Connect().

// Using configured server
if err := c.Connect(); err != nil {
    // handle error
}

// Using specific server address
if err := c.ConnectTo("irc.freenode.net"); err != nil {
    // handle error
}

Use irc.SimpleClient(nickname, username) to create a new IRC client instance. This is a high-level constructor that sets up a client with the provided nickname and username.

To enable tracking of user presence and channel membership, call c.EnableStateTracking() on the returned client.

c := irc.SimpleClient("GoTest", "gotest")
c.EnableStateTracking()

To gracefully exit an IRC session, use c.Quit(reason). To abruptly terminate the connection, use c.Close().

// Graceful quit with a reason
c.Quit("Goodbye!")

// Immediate close
c.Close()

The client provides methods to interact with the IRC server:

• c.Join(channel): Joins a specific channel.
• c.Part(channel): Parts from a specific channel.
• c.Privmsg(target, message): Sends a private message to a user or a message to a channel.

c.Join("#go-nuts")
c.Part("#go-nuts")
c.Privmsg("#go-nuts", "Hello world!")

The c.Config() method returns access to the client's configuration settings. For example, you can toggle the Flood boolean to control how the client handles rapid message sending.

c.Config().Flood = true

If EnableStateTracking() has been called, you can use c.StateTracker().IsOn(channel, username) to check if a specific user is currently present in a specific channel. It returns a boolean indicating presence.

// Returns true if username is in channelname
_, userIsOn := c.StateTracker().IsOn("#channel", "nickname")

If you need to send a command that is not covered by the high-level API, use c.Raw(command) to send a raw string directly to the server.

c.Raw("NOTICE #channel :test message")