-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Another library for writing IRC clients.
--   
@package irc-fun-client
@version 0.2.0.0


-- | Get the current UTC time and formatted time strings, using auto-update
--   to run the actual action periodically and by demand. In other words,
--   these functions can safely be used at high frequency.
--   
--   Intended use: Create a single getter in the main thread and pass as
--   needed to other threads for their own use.
module Network.IRC.Fun.Client.Time

-- | Make a getter which returns the current time, and a formatted time
--   string for use in IRC logs.
currentTimeGetter :: IO (IO (UTCTime, String))

module Network.IRC.Fun.Client.Util

-- | Check if a message mentions a given nickname.
--   
--   This isn't the same as substring search, since the nickname could
--   appear inside a longer word. For example, "ron" isn't really mentioned
--   in "asynchronic". Therefore, this function is a bit smarter about
--   this, trying to capturing real mentions, and works quite well in
--   practice.
mentions :: String -> String -> Bool


-- | Using the tools provided here, you can track which users are members
--   of which channels. This functionality has a variety of uses, e.g.
--   displaying user lists in client UI and logging/displaying quit
--   messages in the correct channel logs/buffers.
module Network.IRC.Fun.Client.NickTracker
newtype ChannelTracker
ChannelTracker :: (HashSet NickName) -> ChannelTracker
newtype NetworkTracker
NetworkTracker :: (HashMap ChannelName ChannelTracker) -> NetworkTracker

-- | Check whether a nickname is present in a channel.
isMemberOf :: NickName -> ChannelTracker -> Bool

-- | Check whether a nickname is present in a channel.
isInChannel :: NickName -> ChannelName -> NetworkTracker -> Bool

-- | Check in which channels a nickname is present.
presence :: NickName -> NetworkTracker -> [ChannelName]

-- | Record a channel with the given present nicknames.
newChannel :: [NickName] -> ChannelTracker

-- | Create new tracker.
newNetwork :: NetworkTracker

-- | Record a nickname being present in a channel.
addMember :: NickName -> ChannelTracker -> ChannelTracker

-- | Record a nickname being present in a channel.
addToChannel :: ChannelName -> NickName -> NetworkTracker -> NetworkTracker

-- | Record a nickname change. Remove old nickname from the channels in
--   which it's present, and add the new nickname to them.
changeNick :: NickName -> NickName -> NetworkTracker -> NetworkTracker

-- | Record a channel with the given present nicknames.
addChannel :: ChannelName -> [NickName] -> NetworkTracker -> NetworkTracker

-- | Record a channel not having a given nickname anymore.
removeMember :: NickName -> ChannelTracker -> ChannelTracker

-- | Record a channel not having a given nickname anymore.
removeFromChannel :: ChannelName -> NickName -> NetworkTracker -> NetworkTracker

-- | Record a nickname not being present in any channel anymore.
removeFromNetwork :: NickName -> NetworkTracker -> NetworkTracker

-- | Remove a channel from the tracker.
removeChannel :: ChannelName -> NetworkTracker -> NetworkTracker

-- | Remove channels from the tracker.
removeChannels :: [ChannelName] -> NetworkTracker -> NetworkTracker

module Network.IRC.Fun.Client.IO

-- | Details of the connection to IRC.
data Connection
Connection :: String -> Int -> Bool -> String -> Maybe String -> Connection

-- | IRC Server address, e.g. <tt>"irc.freenode.net"</tt>
server :: Connection -> String

-- | IRC server port, <tt>6667</tt> should be a safe default
port :: Connection -> Int

-- | Whether to make an encrypted connection via TLS (not implemented)
tls :: Connection -> Bool

-- | IRC nickname for the bot, e.g. <tt>"funbot"</tt>
nick :: Connection -> String

-- | Connection password, use if the nickname is registered
password :: Connection -> Maybe String

-- | Haskell defines operations to read and write characters from and to
--   files, represented by values of type <tt>Handle</tt>. Each value of
--   this type is a <i>handle</i>: a record used by the Haskell run-time
--   system to <i>manage</i> I/O with file system objects. A handle has at
--   least the following properties:
--   
--   <ul>
--   <li>whether it manages input or output or both;</li>
--   <li>whether it is <i>open</i>, <i>closed</i> or
--   <i>semi-closed</i>;</li>
--   <li>whether the object is seekable;</li>
--   <li>whether buffering is disabled, or enabled on a line or block
--   basis;</li>
--   <li>a buffer (whose length may be zero).</li>
--   </ul>
--   
--   Most handles will also have a current I/O position indicating where
--   the next input or output operation will occur. A handle is
--   <i>readable</i> if it manages only input or both input and output;
--   likewise, it is <i>writable</i> if it manages only output or both
--   input and output. A handle is <i>open</i> when first allocated. Once
--   it is closed it can no longer be used for either input or output,
--   though an implementation cannot re-use its storage while references
--   remain to it. Handles are in the <a>Show</a> and <a>Eq</a> classes.
--   The string produced by showing a handle is system dependent; it should
--   include enough information to identify the handle for debugging. A
--   handle is equal according to <a>==</a> only to itself; no attempt is
--   made to compare the internal state of different handles for equality.
data Handle :: *

-- | Connect to an IRC server using the given connection parameters, and
--   return a handle to the open socket. This just opens a TCP connection,
--   without sending any IRC commands.
ircConnect :: Connection -> IO Handle

-- | Disconnect from IRC by closing the client's side of the connection.
--   This function is mainly provided for completeness. You should probably
--   use the QUIT command of IRC to quit the network in a manner
--   coordinated with the server.
ircDisconnect :: Handle -> IO ()

-- | Send an IRC command, given in string form, to the server. The given
--   command string shouldn't contain any newlines.
hPutIrcRaw :: Handle -> String -> IO ()

-- | Send an IRC message represented in generic form to the server.
hPutIrcGeneric :: Handle -> GenericMessage -> IO ()

-- | Send an IRC message to the server.
hPutIrc :: Handle -> Message -> IO ()

-- | Receive an IRC message, given in string form, from the server. The
--   resulting string won't contain newlines.
hGetIrcRaw :: Handle -> IO String

-- | Receive an IRC message in generic form from the server. If parsing the
--   message read from the server fails, <a>Nothing</a> is returned.
hGetIrcGenericOnce :: Handle -> IO (Maybe GenericMessage)

-- | Receive the next valid (successfully parsed) IRC message in generic
--   form from the server.
hGetIrcGeneric :: Handle -> IO GenericMessage

-- | Receive an IRC message from the server. If parsing the message read
--   from the server fails, <a>Nothing</a> is returned.
hGetIrcOnce :: Handle -> IO (Maybe (Either SpecificReply SpecificMessage))

-- | Receive the next valid (successfully parsed) IRC message from the
--   server.
hGetIrc :: Handle -> IO (Either SpecificReply SpecificMessage)
instance Eq Connection
instance Show Connection


-- | This module allows you to identify IRC events. Events are a wrapper
--   around IRC messages, which provide a logical layer convenient to work
--   with (while IRC messages have their lower level aspects, being plain
--   protocol messages).
module Network.IRC.Fun.Client.Events

-- | An event triggered by an IRC message sent from the server.
data Event

-- | A ping was sent to the bot. The parameters are the server name and
--   optionally a server to forward the response to. They can be passed
--   as-is directly to the PONG response.
Ping :: String -> (Maybe String) -> Event

-- | One or more users have been kicked from a channel for an optionally
--   given reason. Parameters: Channel, nicknames, reason.
Kick :: String -> [String] -> (Maybe String) -> Event

-- | A user joined a channel. Parameters: Channel, nickname.
Join :: String -> String -> Event

-- | A user left a channel, optionally with a given reason. Parameters:
--   Channel, nickname, reason.
Part :: String -> String -> (Maybe String) -> Event

-- | A user left the network, optonally for the given reason. Parameters:
--   Nickname, reason.
Quit :: String -> (Maybe String) -> Event

-- | TODO
Mode :: Event

-- | Message sent in a channel by a user. The last parameter indicates
--   whether the message is actually a notice. If yes, the client shouldn't
--   automatically send a response. Parameters: Channel, nickname, message,
--   whether notice.
ChannelMessage :: String -> String -> String -> Bool -> Event

-- | A private message sent specifically to the client from a user. The
--   last parameter indicates whether the message is actually a notice. If
--   yes, the client shouldn't send any automatic response. Parameters:
--   Nickname, message, whether notice.
PrivateMessage :: String -> String -> Bool -> Event

-- | A user's nickname has changed. Parameters: Old nick, new nick.
NickChange :: String -> String -> Event

-- | Channel topic change. Parameterss: Channel, nickname of user who
--   changed the topic, new topic content.
Topic :: String -> String -> String -> Event

-- | The client has been invited to a channel by another user. Parameters:
--   Channel, nickname of inviting user.
Invite :: String -> String -> Event

-- | The server sent a list of nicknames present in a channel. Parameters:
--   Channel privacy mode, channel name, list of users. Each list item is a
--   pair of a user privilege level in the channel, and the user's
--   nickname.
Names :: ChannelPrivacy -> String -> [(Privilege, String)] -> Event
OtherEvent :: String -> Event
data ChannelPrivacy :: *
Secret :: ChannelPrivacy
Private :: ChannelPrivacy
Public :: ChannelPrivacy
data Privilege :: *
Regular :: Privilege
Voice :: Privilege
Operator :: Privilege

-- | Try to generate events from an IRC message. If it fails, <a>Left</a>
--   an error message is returned. Otherwise, <a>Right</a> a list of
--   generated events is returned.
detectEvents :: Either SpecificReply SpecificMessage -> Either String [Event]

-- | Receive IRC events. If parsing and detecting the events fails,
--   <a>Nothing</a> is returned.
hGetIrcEventsOnce :: Handle -> IO (Maybe [Event])

-- | Receive the next valid (successfully parsed and detected) series of
--   IRC events.
hGetIrcEvents :: Handle -> IO [Event]
instance Show Event


-- | This module provides convenient functions for performing common IRC
--   client actions. Some of them simply send a single IRC message, while
--   othere send a sequence of several messages.
module Network.IRC.Fun.Client.Commands

-- | Log in as an IRC user with nickname and optional password, using the
--   given connection parameters.
ircLogin :: Handle -> Connection -> Bool -> Bool -> IO ()

-- | IRC servers send PING messages at regular intervals to test the
--   presence of an active client, at least if no other activity is
--   detected on the connection. The server closes the connection
--   automatically if a PONG response isn't sent from the client within a
--   certain amount of time.
--   
--   Therefore, an IRC client usually listens to these PINGs and sends back
--   PONG messages. This function sends a PONG. The parameters should
--   simply be the ones received in the PING message.
ircPong :: Handle -> String -> Maybe String -> IO ()

-- | Join an IRC channel.
ircJoin :: Handle -> String -> Maybe String -> IO ()

-- | Join one or more IRC channels.
ircJoinMulti :: Handle -> [(String, Maybe String)] -> IO ()

-- | Leave an IRC channel.
ircPart :: Handle -> String -> Maybe String -> IO ()

-- | Leave one or more IRC channels.
ircPartMulti :: Handle -> [String] -> Maybe String -> IO ()

-- | Leave all IRC channels you joined.
ircPartAll :: Handle -> IO ()

-- | Send a private message to an IRC user.
ircSendToUser :: Handle -> String -> String -> IO ()

-- | Send a message to an IRC channel.
ircSendToChannel :: Handle -> String -> String -> IO ()

-- | Finish the IRC session, asking the server to close the connection.
ircQuit :: Handle -> Maybe String -> IO ()

module Network.IRC.Fun.Client.ChannelLogger
data Logger
data ChanLogEvent
EnterChan :: NickName -> ChanLogEvent
LeaveChan :: NickName -> ChanLogEvent
MessageChan :: NickName -> String -> ChanLogEvent
RenameInChan :: NickName -> NickName -> ChanLogEvent
data LogEvent
Enter :: NickName -> ChannelName -> LogEvent
Leave :: NickName -> ChannelName -> LogEvent
LeaveAll :: NickName -> LogEvent
Message :: NickName -> ChannelName -> String -> LogEvent
Rename :: NickName -> NickName -> LogEvent

-- | Utility for constructing a log file path.
logFilePath :: FilePath -> String -> ChannelName -> FilePath

-- | Create a logger for a given IRC channel.
newLogger :: IO String -> FilePath -> IO Logger

-- | Flush buffers and release resources.
--   
--   When the logger is paused for a long period of time (i.e. not
--   momentarily - e.g. by a user disabling channel logging via UI), you
--   can use this to release resources. Later, when logging is needed
--   again, create a fresh new logger.
--   
--   If your client joins many channels but log few of them, you can save
--   resources by keeping open loggers only for the few logged channels.
removeLogger :: Logger -> IO ()

-- | Write a log message corresponding to a given event.
logEvent :: Logger -> ChanLogEvent -> IO ()

-- | If an IRC client event can be logged, return a matching log event and
--   the channel in which the event has occured.
fromClientEvent :: Event -> Maybe LogEvent
instance Show ChanLogEvent
instance Show LogEvent


-- | Here is an overview of the library, by module:
--   
--   <ul>
--   <li><a>IO</a>: Provides functions for connecting to an IRC server, and
--   for sending and receiving IRC messages.</li>
--   <li><a>Commands</a>: Provides functions for sending IRC commands to
--   the server.</li>
--   <li><a>Events</a>: Provides an Event type and functions for receiving
--   IRC events. These events are an abstraction on top of IRC
--   messages.</li>
--   <li><a>ChannelLogger</a>: Provides a system for logging IRC channel
--   activity into a file.</li>
--   <li><a>Time</a>: Provides an efficient scalable way to get the current
--   time, and a formatted time string for use in the logger.</li>
--   <li><a>NickTracker</a>: Provides functions for tracking channels and
--   their members</li>
--   <li><a>Util</a>: Miscellaneous helper functions which could be useful
--   to clients</li>
--   </ul>
--   
--   If you're writing an IRC client, here is a suggestion for how to
--   begin:
--   
--   <ol>
--   <li>Use functions from <a>IO</a> module to connect to an IRC
--   server</li>
--   <li>Use functions from <a>Commands</a> module to send common IRC
--   commands</li>
--   <li>Write an events loop which listens to the IRC server input and
--   responds, and a UI component which reacts to user-initiated commands.
--   Use the <a>Events</a> module to receive high-level events. If you have
--   a specific need to receive IRC messages directly, use functions from
--   the <a>IO</a> module.</li>
--   </ol>
module Network.IRC.Fun.Client