irc-client-0.4.4.2: An IRC client library.

Copyright(c) 2016 Michael Walker
LicenseMIT
MaintainerMichael Walker <mike@barrucadu.co.uk>
Stabilityexperimental
PortabilityOverloadedStrings
Safe HaskellNone
LanguageHaskell2010

Network.IRC.Client

Contents

Description

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.

Synopsis

Initialisation

connect Source #

Arguments

:: MonadIO m 
=> ByteString

The hostname

-> Int

The port

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s) 

Connect to a server without TLS.

connectWithTLS Source #

Arguments

:: MonadIO m 
=> ByteString

The hostname

-> Int

The port

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s) 

Connect to a server with TLS.

connectWithTLSConfig Source #

Arguments

:: MonadIO m 
=> TLSClientConfig

The TLS config

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s) 

Connect to a server with TLS using the given TLS config.

connectWithTLSVerify Source #

Arguments

:: MonadIO m 
=> (CertificateStore -> ValidationCache -> ServiceID -> CertificateChain -> IO [FailedReason])

The certificate verifier. Returns an empty list if the cert is good.

-> ByteString

The hostname

-> Int

The port

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s) 

Connect to a server with TLS using the given certificate verifier.

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

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 () Source #

Like start, but use the provided initial state.

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

like start but for clients with state.

Logging

data Origin Source #

The origin of a message.

Constructors

FromServer 
FromClient 

connect' Source #

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' Source #

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.

connectWithTLSConfig' Source #

Arguments

:: MonadIO m 
=> (Origin -> ByteString -> IO ())

The message logger

-> TLSClientConfig

The TLS config

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s) 

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

connectWithTLSVerify' Source #

Arguments

:: MonadIO m 
=> (Origin -> ByteString -> IO ())

The message logger

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

The certificate verifier. Returns an empty list if the cert is good.

-> ByteString

The hostname

-> Int

The port

-> NominalDiffTime

The flood cooldown

-> m (ConnectionConfig s) 

Connect to a server with TLS using the given certificate verifier, with the provided logging function.

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

Print messages to stdout, with the current time.

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

Append messages to a file, with the current time.

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

Do no logging.

Interaction

send :: UnicodeMessage -> StatefulIRC s () Source #

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

sendBS :: IrcMessage -> StatefulIRC s () Source #

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

disconnect :: StatefulIRC s () Source #

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

Defaults

defaultIRCConf :: Text -> InstanceConfig s Source #

Construct a default IRC configuration from a nick

defaultOnConnect :: StatefulIRC s () Source #

The default connect handler: set the nick.

defaultOnDisconnect :: StatefulIRC s () Source #

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

defaultEventHandlers :: [EventHandler s] Source #

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

Utilities

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.