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
  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.

Configuration

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.

Connection configuration

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.

data ConnectionConfig s

The static state of an IRC server connection.

plainConnection

Arguments

:: ByteString

The hostname

-> Int

The port

-> ConnectionConfig s

Connect to a server without TLS.

data TLSConfig

How to connect to a server over TLS.

Constructors

WithDefaultConfig ByteString Int

Use Network.IRC.Conduit.defaultTLSConfig.

WithClientConfig TLSClientConfig

Use the given configuration. The hostname and port are stored as fields of the TLSClientConfig.

WithVerifier ByteString Int (CertificateStore -> ValidationCache -> ServiceID -> CertificateChain -> IO [FailedReason])

Use Network.IRC.Conduit.defaultTLSConfig, with the given certificate verifier. The certificate verifier is a function which returns a list of reasons to reject the certificate.

tlsConnection

Arguments

:: TLSConfig

How to initiate the TLS connection

-> ConnectionConfig s

Connect to a server with TLS.

Logging

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

data Origin

The origin of a message.

Constructors

FromServer

FromClient

Instances

Bounded Origin

Methods

minBound :: Origin

maxBound :: Origin

Enum Origin

Methods

succ :: Origin -> Origin

pred :: Origin -> Origin

toEnum :: Int -> Origin

fromEnum :: Origin -> Int

enumFrom :: Origin -> [Origin]

enumFromThen :: Origin -> Origin -> [Origin]

enumFromTo :: Origin -> Origin -> [Origin]

enumFromThenTo :: Origin -> Origin -> Origin -> [Origin]

Eq Origin

Methods

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

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

Ord Origin

Methods

compare :: Origin -> Origin -> Ordering

(<) :: Origin -> Origin -> Bool

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

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

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

max :: Origin -> Origin -> Origin

min :: Origin -> Origin -> Origin

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

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.

Instance configuration

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.

data InstanceConfig s

The updateable state of an IRC connection.

defaultInstanceConfig

Arguments

:: Text

The nick

-> InstanceConfig s

Construct a default IRC configuration from a nick

Writing IRC clients

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

data IRC s a

The IRC monad.

Instances

MonadState s (IRC s)

Methods

get :: IRC s s

put :: s -> IRC s ()

state :: (s -> (a, s)) -> IRC s a

Monad (IRC s)

Methods

(>>=) :: IRC s a -> (a -> IRC s b) -> IRC s b

(>>) :: IRC s a -> IRC s b -> IRC s b

return :: a -> IRC s a

fail :: String -> IRC s a

Functor (IRC s)

Methods

fmap :: (a -> b) -> IRC s a -> IRC s b

(<$) :: a -> IRC s b -> IRC s a

Applicative (IRC s)

Methods

pure :: a -> IRC s a

(<*>) :: IRC s (a -> b) -> IRC s a -> IRC s b

liftA2 :: (a -> b -> c) -> IRC s a -> IRC s b -> IRC s c

(*>) :: IRC s a -> IRC s b -> IRC s b

(<*) :: IRC s a -> IRC s b -> IRC s a

Alternative (IRC s)

Methods

empty :: IRC s a

(<|>) :: IRC s a -> IRC s a -> IRC s a

some :: IRC s a -> IRC s [a]

many :: IRC s a -> IRC s [a]

MonadPlus (IRC s)

Methods

mzero :: IRC s a

mplus :: IRC s a -> IRC s a -> IRC s a

MonadIO (IRC s)

Methods

liftIO :: IO a -> IRC s a

MonadThrow (IRC s)

Methods

throwM :: Exception e => e -> IRC s a

MonadCatch (IRC s)

Methods

catch :: Exception e => IRC s a -> (e -> IRC s a) -> IRC s a

MonadMask (IRC s)

Methods

mask :: ((forall a. IRC s a -> IRC s a) -> IRC s b) -> IRC s b

uninterruptibleMask :: ((forall a. IRC s a -> IRC s a) -> IRC s b) -> IRC s b

MonadReader (IRCState s) (IRC s)

Methods

ask :: IRC s (IRCState s)

local :: (IRCState s -> IRCState s) -> IRC s a -> IRC s a

reader :: (IRCState s -> a) -> IRC s a

send :: Message Text -> IRC s ()

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

sendBS :: Message ByteString -> IRC s ()

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

disconnect :: IRC s ()

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

reconnect :: IRC s ()

Disconnect from the server (this will wait for all messages to be sent, or a minute to pass), and then connect again.

This can be called after the client has already disconnected, in which case it will just connect again.

Like runClient and runClientWith, this will not return until the client terminates (ie, disconnects without reconnecting).

From event handlers

module Network.IRC.Client.Events

From the outside

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.

data IRCState s

The state of an IRC session.

Instances

MonadReader (IRCState s) (IRC s)

Methods

ask :: IRC s (IRCState s)

local :: (IRCState s -> IRCState s) -> IRC s a -> IRC s a

reader :: (IRCState s -> a) -> IRC s a

getIRCState :: IRC s (IRCState s)

Access the client state.

runIRCAction :: MonadIO m => IRC s a -> IRCState s -> m a

Interact with a client from the outside, by using its IRCState.

data ConnectionState

The state of the connection.

Constructors

Connected

Disconnecting

Disconnected

Instances

Bounded ConnectionState

Methods

minBound :: ConnectionState

maxBound :: ConnectionState

Enum ConnectionState

Methods

succ :: ConnectionState -> ConnectionState

pred :: ConnectionState -> ConnectionState

toEnum :: Int -> ConnectionState

fromEnum :: ConnectionState -> Int

enumFrom :: ConnectionState -> [ConnectionState]

enumFromThen :: ConnectionState -> ConnectionState -> [ConnectionState]

enumFromTo :: ConnectionState -> ConnectionState -> [ConnectionState]

enumFromThenTo :: ConnectionState -> ConnectionState -> ConnectionState -> [ConnectionState]

Eq ConnectionState

Methods

(==) :: ConnectionState -> ConnectionState -> Bool

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

Ord ConnectionState

Methods

compare :: ConnectionState -> ConnectionState -> Ordering

(<) :: ConnectionState -> ConnectionState -> Bool

(<=) :: ConnectionState -> ConnectionState -> Bool

(>) :: ConnectionState -> ConnectionState -> Bool

(>=) :: ConnectionState -> ConnectionState -> Bool

max :: ConnectionState -> ConnectionState -> ConnectionState

min :: ConnectionState -> ConnectionState -> ConnectionState

Read ConnectionState

Methods

readsPrec :: Int -> ReadS ConnectionState

readList :: ReadS [ConnectionState]

readPrec :: ReadPrec ConnectionState

readListPrec :: ReadPrec [ConnectionState]

Show ConnectionState

Methods

showsPrec :: Int -> ConnectionState -> ShowS

show :: ConnectionState -> String

showList :: [ConnectionState] -> ShowS

getConnectionState :: IRCState s -> STM ConnectionState

Get the connection state from an IRC state.

Execution

runClient

Arguments

:: MonadIO m

=> ConnectionConfig s

-> InstanceConfig s

-> s

The initial value for the user state.

-> m ()

Connect to the IRC server and run the client: receiving messages and handing them off to handlers as appropriate.

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

newIRCState

Arguments

:: MonadIO m

=> ConnectionConfig s

-> InstanceConfig s

-> s

The initial value for the user state.

-> m (IRCState s)

Construct a new IRC state

runClientWith :: MonadIO m => IRCState s -> m ()

Like runClient, but use the provided initial IRCState.

Multiple clients should not be run with the same IRCState. The utility of this is to be able to run IRC s a actions in order to interact with the client from the outside.

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

data Timeout

Exception thrown to kill the client if the timeout elapses with nothing received from the server.

Constructors

Timeout

Instances

Bounded Timeout

Methods

minBound :: Timeout

maxBound :: Timeout

Enum Timeout

Methods

succ :: Timeout -> Timeout

pred :: Timeout -> Timeout

toEnum :: Int -> Timeout

fromEnum :: Timeout -> Int

enumFrom :: Timeout -> [Timeout]

enumFromThen :: Timeout -> Timeout -> [Timeout]

enumFromTo :: Timeout -> Timeout -> [Timeout]

enumFromThenTo :: Timeout -> Timeout -> Timeout -> [Timeout]

Eq Timeout

Methods

(==) :: Timeout -> Timeout -> Bool

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

Ord Timeout

Methods

compare :: Timeout -> Timeout -> Ordering

(<) :: Timeout -> Timeout -> Bool

(<=) :: Timeout -> Timeout -> Bool

(>) :: Timeout -> Timeout -> Bool

(>=) :: Timeout -> Timeout -> Bool

max :: Timeout -> Timeout -> Timeout

min :: Timeout -> Timeout -> Timeout

Read Timeout

Methods

readsPrec :: Int -> ReadS Timeout

readList :: ReadS [Timeout]

readPrec :: ReadPrec Timeout

readListPrec :: ReadPrec [Timeout]

Show Timeout

Methods

showsPrec :: Int -> Timeout -> ShowS

show :: Timeout -> String

showList :: [Timeout] -> ShowS

Exception Timeout

Methods

toException :: Timeout -> SomeException

fromException :: SomeException -> Maybe Timeout

displayException :: Timeout -> String

Concurrency

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.

fork :: IRC s () -> IRC s ThreadId

Fork a thread which will be thrown a Disconnect exception when the client disconnects.

data Disconnect

Exception thrown to all managed threads when the client disconnects.

Constructors

Disconnect

Instances

Bounded Disconnect

Methods

minBound :: Disconnect

maxBound :: Disconnect

Enum Disconnect

Methods

succ :: Disconnect -> Disconnect

pred :: Disconnect -> Disconnect

toEnum :: Int -> Disconnect

fromEnum :: Disconnect -> Int

enumFrom :: Disconnect -> [Disconnect]

enumFromThen :: Disconnect -> Disconnect -> [Disconnect]

enumFromTo :: Disconnect -> Disconnect -> [Disconnect]

enumFromThenTo :: Disconnect -> Disconnect -> Disconnect -> [Disconnect]

Eq Disconnect

Methods

(==) :: Disconnect -> Disconnect -> Bool

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

Ord Disconnect

Methods

compare :: Disconnect -> Disconnect -> Ordering

(<) :: Disconnect -> Disconnect -> Bool

(<=) :: Disconnect -> Disconnect -> Bool

(>) :: Disconnect -> Disconnect -> Bool

(>=) :: Disconnect -> Disconnect -> Bool

max :: Disconnect -> Disconnect -> Disconnect

min :: Disconnect -> Disconnect -> Disconnect

Read Disconnect

Methods

readsPrec :: Int -> ReadS Disconnect

readList :: ReadS [Disconnect]

readPrec :: ReadPrec Disconnect

readListPrec :: ReadPrec [Disconnect]

Show Disconnect

Methods

showsPrec :: Int -> Disconnect -> ShowS

show :: Disconnect -> String

showList :: [Disconnect] -> ShowS

Exception Disconnect

Methods

toException :: Disconnect -> SomeException

fromException :: SomeException -> Maybe Disconnect

displayException :: Disconnect -> String

Lenses

module Network.IRC.Client.Lens

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.