-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | An IRC client library. -- @package irc-client @version 0.2.4.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 = ReaderT IRCState IO a data IRCState IRCState :: ConnectionConfig -> TVar InstanceConfig -> IRCState -- | Read-only connection configuration _connectionConfig :: IRCState -> ConnectionConfig -- | Mutable instance configuration in STM _instanceConfig :: IRCState -> TVar InstanceConfig -- | Construct a new IRC state newIRCState :: MonadIO m => ConnectionConfig -> InstanceConfig -> m IRCState -- | Access the entire state. ircState :: IRC IRCState -- | Extract the connection configuration from an IRC state getConnectionConfig :: IRCState -> ConnectionConfig -- | Extract the instance configuration from an IRC state getInstanceConfig :: IRCState -> TVar InstanceConfig -- | Extract the current snapshot of the instance configuration from an IRC -- state getInstanceConfig' :: MonadIO m => IRCState -> m InstanceConfig -- | Access the connection config connectionConfig :: IRC ConnectionConfig -- | Access the instance config TVar instanceConfigTVar :: IRC (TVar InstanceConfig) -- | Access the instance config as it is right now. instanceConfig :: IRC InstanceConfig -- | Overwrite the instance config, even if it has changed since we looked -- at it. putInstanceConfig :: InstanceConfig -> IRC () -- | The origin of a message. data Origin FromServer :: Origin FromClient :: Origin -- | The static state of an IRC server connection. data ConnectionConfig ConnectionConfig :: (Int -> ByteString -> IO () -> Consumer (Either ByteString IrcEvent) IO () -> Producer IO IrcMessage -> IO ()) -> TBMChan IrcMessage -> ByteString -> Int -> NominalDiffTime -> IRC () -> (Origin -> ByteString -> IO ()) -> ConnectionConfig -- | Function to connect and start the conduits. _func :: ConnectionConfig -> Int -> ByteString -> IO () -> Consumer (Either ByteString IrcEvent) IO () -> Producer IO IrcMessage -> IO () -- | Message send queue. _sendqueue :: ConnectionConfig -> TBMChan IrcMessage -- | The server host. _server :: ConnectionConfig -> ByteString -- | The server port. _port :: ConnectionConfig -> Int -- | The minimum time between two adjacent messages. _flood :: ConnectionConfig -> NominalDiffTime -- | Action to run if the remote server closes the connection. _disconnect :: ConnectionConfig -> IRC () -- | Function to log messages sent to and received from the server. _logfunc :: ConnectionConfig -> Origin -> ByteString -> IO () -- | The updateable state of an IRC connection. data InstanceConfig InstanceConfig :: Text -> Text -> Text -> [Text] -> Text -> [EventHandler] -> [(Text, Maybe Text)] -> InstanceConfig -- | Client nick _nick :: InstanceConfig -> Text -- | Client username _username :: InstanceConfig -> Text -- | Client realname _realname :: InstanceConfig -> Text -- | Current channels _channels :: InstanceConfig -> [Text] -- | Response to CTCP VERSION _ctcpVer :: InstanceConfig -> Text -- | The registered event handlers _eventHandlers :: InstanceConfig -> [EventHandler] -- | List of nicks (optionally restricted to channels) to ignore messages -- from. No channel = global. _ignore :: InstanceConfig -> [(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 EventHandler :: Text -> EventType -> (UnicodeEvent -> IRC ()) -> EventHandler -- | A description of the event handler. _description :: EventHandler -> Text -- | Which type to be triggered by _matchType :: EventHandler -> EventType -- | The function to call. _eventFunc :: EventHandler -> UnicodeEvent -> IRC () -- | 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 Eq Origin instance Read Origin instance Show Origin instance Eq EventType instance Show EventType -- | 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 -> IRC () -- | Update the channel list in the instance configuration and also part -- the channel. leaveChannel :: Text -> Maybe Text -> IRC () -- | 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 -> Text -> STM () -- | Send a message to the source of an event. reply :: UnicodeEvent -> Text -> IRC () -- | 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] -- | Respond to server PING messages with a PONG. pingHandler :: UnicodeEvent -> IRC () -- | Respond to CTCP PING requests with a CTCP PONG. ctcpPingHandler :: UnicodeEvent -> IRC () -- | Respond to CTCP VERSION requests with the version string. ctcpVersionHandler :: UnicodeEvent -> IRC () -- | Respond to CTCP TIME requests with the system time. ctcpTimeHandler :: UnicodeEvent -> IRC () -- | 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 -> IRC () -- | Mangle the nick if there's a collision (numeric replies 432, 433, and -- 436) when we set it nickMangler :: UnicodeEvent -> IRC () -- | The default disconnect handler: do nothing. You might want to override -- this with one which reconnects. defaultDisconnectHandler :: IRC () -- | 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 { _handlers = yourCustomEventHandlers : _handlers 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 -- | Connect to a server with TLS. connectWithTLS :: MonadIO m => ByteString -> Int -> NominalDiffTime -> m ConnectionConfig -- | 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 -> 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 -- | Connect to a server with TLS, with the provided logging function. connectWithTLS' :: MonadIO m => (Origin -> ByteString -> IO ()) -> ByteString -> Int -> NominalDiffTime -> m ConnectionConfig -- | 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 -> IRC () -- | Send a message, using TLS if enabled. This blocks if messages are sent -- too rapidly. sendBS :: IrcMessage -> IRC () -- | Disconnect from the server, properly tearing down the TLS session (if -- there is one). disconnect :: IRC () -- | Construct a default IRC configuration from a nick defaultIRCConf :: Text -> InstanceConfig -- | The default disconnect handler: do nothing. You might want to override -- this with one which reconnects. defaultDisconnectHandler :: IRC () -- | 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] -- | 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