-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | An IRC client library. -- -- An IRC client library built atop irc-conduit. Why another IRC -- client library, you cry? I didn't really find one that did what I -- wanted (specifically, handle connecting to servers and calling event -- handlers, possibly with TLS), but which didn't implement almost a full -- IRC bot for you. That takes out all the fun! -- -- irc-conduit and irc-ctcp are my solution to the first -- part of that, this is my solution to the latter. It's a simple IRC -- client library that does the basics for you, but isn't an all-singing, -- all-dancing, fully-featured IRC application. It is a merely a -- simple library. @package irc-client @version 0.2.6.0 -- | Types for IRC clients. See also Network.IRC.Conduit and -- Network.IRC.CTCP. module Network.IRC.Client.Types type UnicodeEvent = Event Text type UnicodeSource = Source Text type UnicodeMessage = Message Text -- | The IRC monad. type IRC a = StatefulIRC () a -- | The IRC monad, with state. type StatefulIRC s a = ReaderT (IRCState s) IO a data IRCState s IRCState :: ConnectionConfig s -> TVar s -> TVar (InstanceConfig s) -> IRCState s -- | Read-only connection configuration [_connectionConfig] :: IRCState s -> ConnectionConfig s -- | Mutable user state [_userState] :: IRCState s -> TVar s -- | Mutable instance configuration in STM [_instanceConfig] :: IRCState s -> TVar (InstanceConfig s) -- | Construct a new IRC state newIRCState :: MonadIO m => ConnectionConfig s -> InstanceConfig s -> s -> m (IRCState s) -- | Access the client state. ircState :: StatefulIRC s (IRCState s) -- | Extract the connection configuration from an IRC state getConnectionConfig :: IRCState s -> ConnectionConfig s -- | Extract the instance configuration from an IRC state getInstanceConfig :: IRCState s -> TVar (InstanceConfig s) -- | Extract the user state from an IRC state getUserState :: IRCState s -> TVar s -- | Extract the current snapshot of the instance configuration from an IRC -- state getInstanceConfig' :: MonadIO m => IRCState s -> m (InstanceConfig s) -- | Access the connection config connectionConfig :: StatefulIRC s (ConnectionConfig s) -- | Access the instance config TVar instanceConfigTVar :: StatefulIRC s (TVar (InstanceConfig s)) -- | Access the instance config as it is right now. instanceConfig :: StatefulIRC s (InstanceConfig s) -- | Overwrite the instance config, even if it has changed since we looked -- at it. putInstanceConfig :: InstanceConfig s -> StatefulIRC s () -- | Access the user state. stateTVar :: StatefulIRC s (TVar s) -- | Access the user state as it is right now. state :: StatefulIRC s s -- | Set the user state. putState :: s -> StatefulIRC s () -- | The origin of a message. data Origin FromServer :: Origin FromClient :: Origin -- | The static state of an IRC server connection. data ConnectionConfig s ConnectionConfig :: (Int -> ByteString -> IO () -> Consumer (Either ByteString IrcEvent) IO () -> Producer IO IrcMessage -> IO ()) -> TBMChan IrcMessage -> ByteString -> Int -> NominalDiffTime -> StatefulIRC s () -> (Origin -> ByteString -> IO ()) -> ConnectionConfig s -- | Function to connect and start the conduits. [_func] :: ConnectionConfig s -> Int -> ByteString -> IO () -> Consumer (Either ByteString IrcEvent) IO () -> Producer IO IrcMessage -> IO () -- | Message send queue. [_sendqueue] :: ConnectionConfig s -> TBMChan IrcMessage -- | The server host. [_server] :: ConnectionConfig s -> ByteString -- | The server port. [_port] :: ConnectionConfig s -> Int -- | The minimum time between two adjacent messages. [_flood] :: ConnectionConfig s -> NominalDiffTime -- | Action to run if the remote server closes the connection. [_disconnect] :: ConnectionConfig s -> StatefulIRC s () -- | Function to log messages sent to and received from the server. [_logfunc] :: ConnectionConfig s -> Origin -> ByteString -> IO () -- | The updateable state of an IRC connection. data InstanceConfig s InstanceConfig :: Text -> Text -> Text -> [Text] -> Text -> [EventHandler s] -> [(Text, Maybe Text)] -> InstanceConfig s -- | Client nick [_nick] :: InstanceConfig s -> Text -- | Client username [_username] :: InstanceConfig s -> Text -- | Client realname [_realname] :: InstanceConfig s -> Text -- | Current channels [_channels] :: InstanceConfig s -> [Text] -- | Response to CTCP VERSION [_ctcpVer] :: InstanceConfig s -> Text -- | The registered event handlers [_eventHandlers] :: InstanceConfig s -> [EventHandler s] -- | List of nicks (optionally restricted to channels) to ignore messages -- from. No channel = global. [_ignore] :: InstanceConfig s -> [(Text, Maybe Text)] -- | Types of events which can be caught. data EventType -- | Match all events EEverything :: EventType -- | Match no events ENothing :: EventType EPrivmsg :: EventType ENotice :: EventType ECTCP :: EventType ENick :: EventType EJoin :: EventType EPart :: EventType EQuit :: EventType EMode :: EventType ETopic :: EventType EInvite :: EventType EKick :: EventType EPing :: EventType ENumeric :: EventType -- | A function which handles an event. data EventHandler s EventHandler :: Text -> EventType -> (UnicodeEvent -> StatefulIRC s ()) -> EventHandler s -- | A description of the event handler. [_description] :: EventHandler s -> Text -- | Which type to be triggered by [_matchType] :: EventHandler s -> EventType -- | The function to call. [_eventFunc] :: EventHandler s -> UnicodeEvent -> StatefulIRC s () -- | Get the type of an event. eventType :: Event a -> EventType -- | A decoded IRC message + source. data Event a :: * -> * Event :: ByteString -> Source a -> Message a -> Event a -- | The message as a bytestring. [_raw] :: Event a -> ByteString -- | The source of the message (user, channel, or server). [_source] :: Event a -> Source a -- | The decoded message. This will never be a RawMsg. [_message] :: Event a -> Message a -- | The source of an IRC message. data Source a :: * -> * -- | The message comes directly from a user. User :: NickName a -> Source a -- | The message comes from a user in a channel. Channel :: ChannelName a -> NickName a -> Source a -- | The message comes directly from the server. Server :: ServerName a -> Source a -- | A decoded IRC message. data Message a :: * -> * -- | A message, either from a user or to a channel the client is in. CTCPs -- are distinguished by starting and ending with a \001 (SOH). Privmsg :: Target a -> Either CTCPByteString a -> Message a -- | Like a privmsg, but should not provoke an automatic response. Notice :: Target a -> Either CTCPByteString a -> Message a -- | Someone has updated their nick. Nick :: NickName a -> Message a -- | Someone has joined a channel. Join :: ChannelName a -> Message a -- | Someone has left a channel. Part :: ChannelName a -> Reason a -> Message a -- | Someone has left the network. Quit :: Reason a -> Message a -- | Someone has set some channel modes or user modes. Mode :: Target a -> IsModeSet -> [ModeFlag a] -> [ModeArg a] -> Message a -- | Someone has set the topic of a channel. Topic :: ChannelName a -> a -> Message a -- | The client has been invited to a channel. Invite :: ChannelName a -> NickName a -> Message a -- | Someone has been kicked from a channel. Kick :: ChannelName a -> NickName a -> Reason a -> Message a -- | The client has received a server ping, and should send a pong asap. Ping :: ServerName a -> Maybe (ServerName a) -> Message a -- | A pong sent to the named server. Pong :: ServerName a -> Message a -- | One of the many server numeric responses. Numeric :: Int -> [NumericArg a] -> Message a -- | Never produced by decoding, but can be used to send arbitrary -- bytestrings to the IRC server. Naturally, this should only be used -- when you are confident that the produced bytestring will be a valid -- IRC message. RawMsg :: a -> Message a instance GHC.Show.Show Network.IRC.Client.Types.EventType instance GHC.Classes.Eq Network.IRC.Client.Types.EventType instance GHC.Show.Show Network.IRC.Client.Types.Origin instance GHC.Read.Read Network.IRC.Client.Types.Origin instance GHC.Classes.Eq Network.IRC.Client.Types.Origin -- | Commonly-used utility functions for IRC clients. module Network.IRC.Client.Utils -- | Update the nick in the instance configuration and also send an update -- message to the server. This doesn't attempt to resolve nick -- collisions, that's up to the event handlers. setNick :: Text -> StatefulIRC s () -- | Update the channel list in the instance configuration and also part -- the channel. leaveChannel :: Text -> Maybe Text -> StatefulIRC s () -- | Remove a channel from the list without sending a part command (be -- careful not to let the channel list get out of sync with the -- real-world state if you use it for anything!) delChan :: TVar (InstanceConfig s) -> Text -> STM () -- | Add an eventHandler addHandler :: EventHandler () -> StatefulIRC () () -- | Send a message to the source of an event. reply :: UnicodeEvent -> Text -> StatefulIRC s () -- | Construct a PRIVMSG containing a CTCP ctcp :: Text -> Text -> [Text] -> UnicodeMessage -- | Construct a NOTICE containing a CTCP ctcpReply :: Text -> Text -> [Text] -> UnicodeMessage -- | The default event handlers. Handlers are invoked concurrently when -- matching events are received from the server. module Network.IRC.Client.Handlers -- | The default event handlers, the following are included: -- -- -- -- 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. defaultEventHandlers :: [EventHandler s] -- | Respond to server PING messages with a PONG. pingHandler :: UnicodeEvent -> StatefulIRC s () -- | Respond to CTCP PING requests with a CTCP PONG. ctcpPingHandler :: UnicodeEvent -> StatefulIRC s () -- | Respond to CTCP VERSION requests with the version string. ctcpVersionHandler :: UnicodeEvent -> StatefulIRC s () -- | Respond to CTCP TIME requests with the system time. ctcpTimeHandler :: UnicodeEvent -> StatefulIRC s () -- | Update the nick upon welcome (numeric reply 001), as it may not be -- what we requested (eg, in the case of a nick too long). welcomeNick :: UnicodeEvent -> StatefulIRC s () -- | Mangle the nick if there's a collision (numeric replies 432, 433, and -- 436) when we set it nickMangler :: UnicodeEvent -> StatefulIRC s () -- | The default disconnect handler: do nothing. You might want to override -- this with one which reconnects. defaultDisconnectHandler :: StatefulIRC s () -- | 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. module Network.IRC.Client -- | Connect to a server without TLS. connect :: MonadIO m => ByteString -> Int -> NominalDiffTime -> m (ConnectionConfig s) -- | Connect to a server with TLS. connectWithTLS :: MonadIO m => ByteString -> Int -> NominalDiffTime -> m (ConnectionConfig s) -- | 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 => ConnectionConfig () -> InstanceConfig () -> m () -- | Like start, but use the provided initial state. start' :: MonadIO m => IRCState s -> m () -- | like start but for clients with state. startStateful :: MonadIO m => ConnectionConfig s -> InstanceConfig s -> s -> m () -- | The origin of a message. data Origin FromServer :: Origin FromClient :: Origin -- | Connect to a server without TLS, with the provided logging function. connect' :: MonadIO m => (Origin -> ByteString -> IO ()) -> ByteString -> Int -> NominalDiffTime -> m (ConnectionConfig s) -- | Connect to a server with TLS, with the provided logging function. connectWithTLS' :: MonadIO m => (Origin -> ByteString -> IO ()) -> ByteString -> Int -> NominalDiffTime -> m (ConnectionConfig s) -- | Print messages to stdout, with the current time. stdoutLogger :: Origin -> ByteString -> IO () -- | Append messages to a file, with the current time. fileLogger :: FilePath -> Origin -> ByteString -> IO () -- | Do no logging. noopLogger :: a -> b -> IO () -- | Send a message as UTF-8, using TLS if enabled. This blocks if messages -- are sent too rapidly. send :: UnicodeMessage -> StatefulIRC s () -- | Send a message, using TLS if enabled. This blocks if messages are sent -- too rapidly. sendBS :: IrcMessage -> StatefulIRC s () -- | Disconnect from the server, properly tearing down the TLS session (if -- there is one). disconnect :: StatefulIRC s () -- | Construct a default IRC configuration from a nick defaultIRCConf :: Text -> InstanceConfig s -- | The default disconnect handler: do nothing. You might want to override -- this with one which reconnects. defaultDisconnectHandler :: StatefulIRC s () -- | The default event handlers, the following are included: -- -- -- -- 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. defaultEventHandlers :: [EventHandler s] -- | Construct a raw message. rawMessage :: ByteString -> [ByteString] -> IrcMessage -- | Encode an IRC message into a single bytestring suitable for sending to -- the server. toByteString :: IrcMessage -> ByteString