Network.IRC.Client

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

run :: ByteString -> Int -> Text -> IO ()
run host port nick = do
  conn <- connect host port 1
  let cfg = defaultIRCConf nick
  let cfg' = cfg { _eventHandlers = yourCustomEventHandlers : _eventHandlers cfg }
  start 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.

Initialisation

connect

Arguments

:: MonadIO m

=> ByteString

The hostname

-> Int

The port

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s)

Connect to a server without TLS.

connectWithTLS

Arguments

:: MonadIO m

=> ByteString

The hostname

-> Int

The port

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s)

Connect to a server with TLS.

start :: MonadIO m => ConnectionConfig () -> InstanceConfig () -> m ()

Run the event loop for a server, receiving messages and handing them off to handlers as appropriate. Messages will be logged to stdout.

start' :: MonadIO m => IRCState s -> m ()

Like start, but use the provided initial state.

startStateful :: MonadIO m => ConnectionConfig s -> InstanceConfig s -> s -> m ()

like start but for clients with state.

Logging

data Origin

The origin of a message.

Constructors

FromServer

FromClient

Instances

Eq Origin

Methods

(==) :: Origin -> Origin -> Bool

(/=) :: Origin -> Origin -> Bool

Read Origin

Methods

readsPrec :: Int -> ReadS Origin

readList :: ReadS [Origin]

readPrec :: ReadPrec Origin

readListPrec :: ReadPrec [Origin]

Show Origin

Methods

showsPrec :: Int -> Origin -> ShowS

show :: Origin -> String

showList :: [Origin] -> ShowS

connect'

Arguments

:: MonadIO m

=> (Origin -> ByteString -> IO ())

The message logger

-> ByteString

The hostname

-> Int

The port

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s)

Connect to a server without TLS, with the provided logging function.

connectWithTLS'

Arguments

:: MonadIO m

=> (Origin -> ByteString -> IO ())

The message logger

-> ByteString

The hostname

-> Int

The port

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s)

Connect to a server with TLS, with the provided logging function.

stdoutLogger :: Origin -> ByteString -> IO ()

Print messages to stdout, with the current time.

fileLogger :: FilePath -> Origin -> ByteString -> IO ()

Append messages to a file, with the current time.

noopLogger :: a -> b -> IO ()

Do no logging.

Interaction

send :: UnicodeMessage -> StatefulIRC s ()

Send a message as UTF-8, using TLS if enabled. This blocks if messages are sent too rapidly.

sendBS :: IrcMessage -> StatefulIRC s ()

Send a message, using TLS if enabled. This blocks if messages are sent too rapidly.

disconnect :: StatefulIRC s ()

Disconnect from the server, properly tearing down the TLS session (if there is one).

Defaults

defaultIRCConf :: Text -> InstanceConfig s

Construct a default IRC configuration from a nick

defaultOnConnect :: StatefulIRC s ()

The default connect handler: set the nick.

defaultOnDisconnect :: StatefulIRC s ()

The default disconnect handler: do nothing. You might want to override this with one which reconnects.

defaultEventHandlers :: [EventHandler s]

The default event handlers, the following are included:

• respond to server PING messages with a PONG;
• respond to CTCP PING requests with a CTCP PONG;
• respond to CTCP VERSION requests with the version string;
• respond to CTCP TIME requests with the system time;
• update the nick upon receiving the welcome message, in case the server modifies it;
• mangle the nick if the server reports a collision;
• update the channel list on JOIN and KICK.

These event handlers are all exposed through the Network.IRC.Client.Handlers module, so you can use them directly if you are building up your InstanceConfig from scratch.

If you are building a bot, you may want to write an event handler to process messages representing commands.

Types

module Network.IRC.Client.Types

Utilities

module Network.IRC.Client.Utils

rawMessage

Arguments

:: ByteString

The command

-> [ByteString]

The arguments

-> IrcMessage

Construct a raw message.

toByteString :: IrcMessage -> ByteString

Encode an IRC message into a single bytestring suitable for sending to the server.