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


-- | Fast Internet Relay Chat (IRC) library
--   
--   Fast Internet Relay Chat (IRC) library. This library implements a
--   attoparsec-based fast parser for IRC messages as well as a network
--   manager for IRC clients (user agents and bots).
@package fastirc
@version 0.2.0


-- | Utility functions for parsing IRC messages.
module Network.FastIRC.Utils

-- | Character predicate for channel names.
isChannelChar :: Char -> Bool

-- | Character predicate for channel passwords.
isChanPwdChar :: Char -> Bool

-- | Character predicate for IRC commands.
isCommandChar :: Char -> Bool

-- | Character predicate for IRC user hostnames. In the string
--   <tt>x!y@z</tt> the substring <tt>z</tt> is the user's hostname.
isHostChar :: Char -> Bool

-- | Character predicate for IRC end of line characters.
isIRCEOLChar :: Char -> Bool

-- | Character predicate for IRC tokens.
isIRCTokChar :: Char -> Bool

-- | Character predicate for IRC messages.
isMessageChar :: Char -> Bool

-- | Character predicate for IRC nicknames. This function considers high
--   bytes (0x80 to 0xFF) and most nonstandard ASCII bytes as valid,
--   because most modern IRC daemons allow nonstandard nicknames.
isNickChar :: Char -> Bool

-- | Character predicate for IRC servers.
isServerChar :: Char -> Bool

-- | Character predicate for IRC usernames. In the string <tt>x!y@z</tt>
--   the substring <tt>y</tt> is the user's username.
isUserChar :: Char -> Bool

-- | Character predicate for nicknames, usernames and hostnames.
isUserSpecChar :: Char -> Bool

-- | Run a parser completely.
parseComplete :: Parser a -> ByteString -> Maybe a


-- | A number of convenient type aliases.
module Network.FastIRC.Types
type ChannelKey = ByteString
type ChannelName = ByteString
type CommandArg = ByteString
type CommandName = ByteString
type HostName = ByteString
type MsgString = ByteString
type NickName = ByteString
type RealName = ByteString
type ServerName = ByteString
type TargetName = ByteString
type UserName = ByteString


-- | Functions for dealing with sets of IRC servers. Note that servers are
--   compared case-insensitively.
module Network.FastIRC.ServerSet

-- | A set of servers. This data type uses <a>Set</a> internally, but the
--   strings are handled case-insensitively.
data ServerSet

-- | Add a server to a <a>ServerSet</a>.
addServer :: ServerName -> ServerSet -> ServerSet

-- | Remove a server from a <a>ServerSet</a>.
delServer :: ServerName -> ServerSet -> ServerSet

-- | Empty set of servers.
emptyServers :: ServerSet

-- | Check whether specified server is in the set.
isServer :: ServerName -> ServerSet -> Bool

-- | Build from list.
serversFromList :: [ServerName] -> ServerSet

-- | Convert to list.
serversToList :: ServerSet -> [ServerName]


-- | This module includes parsers for IRC users.
module Network.FastIRC.Users

-- | IRC user or server.
data UserSpec

-- | Nickname.
Nick :: NickName -> UserSpec

-- | Nickname, username and hostname.
User :: NickName -> UserName -> HostName -> UserSpec

-- | Check whether a given nickname is a server.
userIsServer :: UserSpec -> ServerSet -> Bool

-- | Turn a <a>UserSpec</a> into a <a>ByteString</a> in a format suitable
--   to be sent to the IRC server.
showUserSpec :: UserSpec -> MsgString

-- | A <a>Parser</a> for IRC users and servers.
userParser :: Parser UserSpec
instance Eq UserSpec
instance Read UserSpec
instance Show UserSpec


-- | Parser and printer for IRC messages.
module Network.FastIRC.Messages

-- | Data type for IRC messages.
data Message
Message :: !Maybe UserSpec -> !Command -> Message

-- | Message origin (user/server).
msgOrigin :: Message -> !Maybe UserSpec

-- | Message command or numeric.
msgCommand :: Message -> !Command

-- | Parser for IRC messages.
messageParser :: Parser Message

-- | Run the <a>messageParser</a> parser.
readMessage :: MsgString -> Maybe Message

-- | Turn a <a>Message</a> into a <a>ByteString</a>.
showMessage :: Message -> MsgString

-- | Data type for IRC commands.
data Command

-- | Arbitrary string command.
StringCmd :: CommandName -> [CommandArg] -> Command

-- | Arbitrary numeric command.
NumericCmd :: Integer -> [CommandArg] -> Command
JoinCmd :: (Map ChannelName (Maybe ChannelKey)) -> Command
KickCmd :: (Set ChannelName) -> (Set NickName) -> (Maybe CommandArg) -> Command
ModeCmd :: (Maybe (TargetName, CommandArg, [CommandArg])) -> Command
NickCmd :: NickName -> (Maybe Int) -> Command
NoticeCmd :: (Set TargetName) -> CommandArg -> Command
PartCmd :: (Set ChannelName) -> (Maybe CommandArg) -> Command
PassCmd :: CommandArg -> Command
PingCmd :: ServerName -> (Maybe ServerName) -> Command
PongCmd :: ServerName -> (Maybe ServerName) -> Command
PrivMsgCmd :: (Set TargetName) -> CommandArg -> Command
QuitCmd :: (Maybe CommandArg) -> Command
TopicCmd :: ChannelName -> (Maybe CommandArg) -> Command
UserCmd :: UserName -> CommandArg -> CommandArg -> CommandArg -> Command

-- | Parser for IRC commands and their arguments.
commandParser :: Parser Command

-- | Turn a <a>Command</a> into a <a>ByteString</a>. If you need to specify
--   an origin for the command, you should use <a>Message</a> together with
--   <a>showMessage</a>.
showCommand :: Command -> MsgString
instance Eq Command
instance Read Command
instance Show Command
instance Eq Message
instance Read Message
instance Show Message


-- | This module helps you with doing input and output on IRC connections
--   or even log files.
module Network.FastIRC.IO

-- | Read an IRC message string.
hGetIRCLine :: Handle -> IO MsgString

-- | Read the next valid IRC message.
hGetMessage :: Handle -> IO Message

-- | Write an IRC command with no origin.
hPutCommand :: Handle -> Command -> IO ()

-- | Write an IRC message.
hPutMessage :: Handle -> Message -> IO ()


-- | This module implements a framework for IRC client software.
--   Essentially it consists of a dumb bot, which connects to and stays on
--   an IRC server waiting for commands.
--   
--   Using the <a>onEvent</a> function (or the convenience functions
--   <a>onConnect</a>, <a>onDisconnect</a>, etc.) you can attach event
--   handlers to certain events. These event handlers are run in the
--   <a>Bot</a> monad, which encapsulates the current state of the bot.
--   
--   Please note that even though unlikely you should expect that parts of
--   this interface will be changed in future revisions.
module Network.FastIRC.Session

-- | Bot monad.
type Bot = ContT () (StateT Config (ReaderT Params IO))

-- | Commands to be sent to the bot.
data BotCommand

-- | Add an event handler.
BotAddHandler :: (EventHandler -> IO ()) -> (Event -> Bot ()) -> BotCommand

-- | Dispatch simulated event.
BotDispatch :: Event -> BotCommand

-- | Simulate an error.
BotError :: String -> BotCommand

-- | Send a quit message.
BotQuit :: (Maybe CommandArg) -> BotCommand

-- | Simulate receiving of a message.
BotRecv :: Message -> BotCommand

-- | Send a command to the IRC server.
BotSendCmd :: Command -> BotCommand

-- | Send a message to the IRC server.
BotSendMsg :: Message -> BotCommand

-- | Send a raw string to the IRC server.
BotSendString :: MsgString -> BotCommand

-- | Immediately kill the bot.
BotTerminate :: BotCommand

-- | Runtime bot information.
data BotInfo
BotInfo :: Maybe NickName -> BotInfo
botCurrentNick :: BotInfo -> Maybe NickName

-- | Bot session descriptor.
data BotSession

-- | A bot event.
data Event

-- | Bot connected.
ConnectedEvent :: Event

-- | Bot disconnected (either error or on demand).
DisconnectedEvent :: Event

-- | Connection failed or disconnected on error.
ErrorEvent :: String -> Event

-- | Bot logged in (received numeric 001).
LoggedInEvent :: Event

-- | Received message from server.
MessageEvent :: Message -> Event

-- | Bot disconnected on demand.
QuitEvent :: Event

-- | Event handler identifier.
type EventHandler = Unique

-- | Parameters for an IRC client connection.
data Params
Params :: IO NickName -> IO UserName -> IO RealName -> Maybe CommandArg -> Address -> Params

-- | IRC nick name generator.
botGetNick :: Params -> IO NickName

-- | IRC user name generator.
botGetUser :: Params -> IO UserName

-- | IRC real name generator.
botGetRealName :: Params -> IO RealName

-- | IRC server password.
botPassword :: Params -> Maybe CommandArg

-- | IRC server address.
botServerAddr :: Params -> Address

-- | Send a command to the IRC server.
ircSendCmd :: BotSession -> Command -> IO ()

-- | Send a message (with origin) to the IRC server. Note that IRC servers
--   ignore the origin prefix, so in general you would want to use
--   <a>ircSendCmd</a> instead.
ircSendMsg :: BotSession -> Message -> IO ()

-- | Send a raw message string to the IRC server. This is what most IRC
--   clients call /quote.
ircSendString :: BotSession -> MsgString -> IO ()

-- | Add an event handler.
onEvent :: BotSession -> (Event -> Bot ()) -> IO EventHandler

-- | Send bot command to a bot.
sendBotCmd :: BotSession -> BotCommand -> IO ()

-- | Launch an IRC bot.
startBot :: Params -> IO (Either IOError BotSession)

-- | Action to run on connect.
onConnect :: BotSession -> Bot () -> IO EventHandler

-- | Action to run on disconnect.
onDisconnect :: BotSession -> Bot () -> IO EventHandler

-- | Action to run on error (connection failed/aborted).
onError :: BotSession -> (String -> Bot ()) -> IO EventHandler

-- | Action to run after login (numeric 001 received).
onLoggedIn :: BotSession -> Bot () -> IO EventHandler

-- | Action to run when a message arrives.
onMessage :: BotSession -> (Message -> Bot ()) -> IO EventHandler

-- | Action to run on quit.
onQuit :: BotSession -> Bot () -> IO EventHandler

-- | Get current bot information.
getBotInfo :: Bot BotInfo
instance Eq Event
instance Read Event
instance Show Event


-- | Fast IRC parsing and connection library.
module Network.FastIRC