A simple IRC client library. Typical usage will be of this form:

run :: ByteString -> Int -> Text -> IO ()
run host port nick = do
  let conn = plainConnection host port
  let cfg  = defaultInstanceConfig nick & handlers %~ (yourCustomEventHandlers:)
  runClient conn cfg ()

You shouldn't really need to tweak anything other than the event handlers, as everything has been designed to be as simple as possible.

The configuration is logically split into two parts: the connection configuration (the ConnectionConfig type) and the instance configuration (the InstanceConfig type).

• Connection configuration details how to connect to the IRC server, and cannot be modified after the client has started (although it can be read).
• Instance configuration is everything else: the client's nick, and version, handlers for received messages, and so on. It can be modified after the client has started.

The following values can be changed with the exported lenses:

• username (default: "irc-client"). The username sent to the server in the "USER" command.
• realname (default: "irc-client"). The real name sent to the server in the "USER" command.
• password (default: Nothing). If set, the password sent to the server in the "PASS" command.
• flood (default: 1). The minimum time between sending messages, to avoid flooding.
• timeout (default: 300). The amount of time to wait for a message from the server before locally timing out.
• onconnect (default: defaultOnConnect). The action to perform after sending the "USER" and "PASS" commands.
• ondisconnect (default: defaultOnDisconnect). The action to perform after disconnecting from the server
• logfunc (default: noopLogger). The function to log received and sent messages.

The logging functions are told whether the message came from the server or the client, and are given the raw bytestring.

The following values can be changed with the exported lenses:

• nick. The nick that defaultOnConnect sends to the server. This is also modified during runtime by the welcomeNick and nickMangler default event handlers.
• channels (default: []). The channels that joinOnWelcome joins. This is also modified during runtime by the joinHandler default event handler.
• version (default: "irc-client-$VERSION"). The version that ctcpVersionHandler sends.
• handlers (default: defaultEventHandlers). The list of event handlers.
• ignore (default: []). The ignore list, events from matching nicks are not handled.

With this library, IRC clients are mostly composed of event handlers. Event handlers are monadic actions operating in the IRC monad.

The ConnectionConfig, InstanceConfig, and some other stuff are combined in the IRCState type. This can be used to interact with a client from the outside, by providing a way to run IRC s a actions.

If an IRCState is constructed with newIRCState and a client started with runClientWith, then runIRCAction can be used to interact with that client.

If the client times out from the server, the Timeout exception will be thrown, killing it.

A client can manage a collection of threads, which get thrown the Disconnect exception whenever the client disconnects for any reason (including a call to reconnect). These can be created from event handlers to manage long-running tasks.