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


-- | Streaming IRC message library using conduits.
--   
--   IRC messages consist of an optional identifying prefix, a command
--   name, and a list of arguments. The <a>irc</a> package provides a
--   low-level decoding and encoding scheme for messages in terms of
--   ByteStrings, but using this relies on matching names of commands as
--   strings, and unpacking this decoded structure yourself. This package
--   takes it a little further, providing an ADT for IRC messages and
--   sources, and conduits which attempt to decode and encode messages
--   appropriately.
--   
--   In addition to providing conduits for automatically handling streaming
--   messages, there are also helper functions for connecting to an IRC
--   server and hooking up conduits to the socket.
@package irc-conduit
@version 0.3.0.1


-- | Internal IRC conduit types and utilities. This module is NOT
--   considered to form part of the public interface of this library.
module Network.IRC.Conduit.Internal

-- | See <tt><a>Control.Lens.Lens.Lens</a></tt>.
type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t

-- | A <tt><a>Simple</a></tt> <a>Lens</a>.
type Lens' s a = Lens s s a a

-- | See <tt><a>Control.Lens.Prism.Prism</a></tt>.
type Prism s t a b = forall p f. (Choice p, Applicative f) => p a (f b) -> p s (f t)

-- | A <tt><a>Simple</a></tt> <a>Prism</a>.
type Prism' s a = Prism s s a a

-- | Split up incoming bytestrings into new lines.
chunked :: Monad m => ConduitM ByteString ByteString m ()
type ChannelName a = a
type NickName a = a
type ServerName a = a
type Reason a = Maybe a
type IsModeSet = Bool
type ModeFlag a = a
type ModeArg a = a
type NumericArg a = a

-- | The target of a message. Will be a nick or channel name.
type Target a = a
type IrcEvent = Event ByteString
type IrcSource = Source ByteString
type IrcMessage = Message ByteString

-- | 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 <a>RawMsg</a>.
[_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
fromByteString :: ByteString -> Either ByteString IrcEvent

-- | Attempt to decode a ByteString into a message, returning a Nothing if
--   either the source or the message can't be determined.
attemptDecode :: ByteString -> Maybe (IrcSource, IrcMessage)

-- | Encode an IRC message into a single bytestring suitable for sending to
--   the server.
toByteString :: IrcMessage -> ByteString
mkMessage :: ByteString -> [ByteString] -> ByteString

-- | Construct a raw message.
rawMessage :: ByteString -> [ByteString] -> IrcMessage
instance GHC.Show.Show (Network.IRC.Conduit.Internal.NickName a) => GHC.Show.Show (Network.IRC.Conduit.Internal.Event a)
instance GHC.Base.Functor Network.IRC.Conduit.Internal.Event
instance GHC.Classes.Eq (Network.IRC.Conduit.Internal.NickName a) => GHC.Classes.Eq (Network.IRC.Conduit.Internal.Event a)
instance GHC.Show.Show (Network.IRC.Conduit.Internal.Target a) => GHC.Show.Show (Network.IRC.Conduit.Internal.Message a)
instance GHC.Base.Functor Network.IRC.Conduit.Internal.Message
instance GHC.Classes.Eq (Network.IRC.Conduit.Internal.Target a) => GHC.Classes.Eq (Network.IRC.Conduit.Internal.Message a)
instance GHC.Show.Show (Network.IRC.Conduit.Internal.NickName a) => GHC.Show.Show (Network.IRC.Conduit.Internal.Source a)
instance GHC.Base.Functor Network.IRC.Conduit.Internal.Source
instance GHC.Classes.Eq (Network.IRC.Conduit.Internal.NickName a) => GHC.Classes.Eq (Network.IRC.Conduit.Internal.Source a)


-- | <a>Lens</a>es and <a>Prism</a>s.
module Network.IRC.Conduit.Lens

-- | <a>Lens</a> for <a>_raw</a>.
raw :: Lens' (Event a) ByteString

-- | <a>Lens</a> for <a>_source</a>.
source :: Lens' (Event a) (Source a)

-- | <a>Lens</a> for <a>_message</a>.
message :: Lens' (Event a) (Message a)

-- | <a>Prism</a> for <a>User</a>
_User :: Prism' (Source a) (NickName a)

-- | <a>Prism</a> for <a>Channel</a>
_Channel :: Prism' (Source a) (ChannelName a, NickName a)

-- | <a>Prism</a> for <a>Server</a>
_Server :: Prism' (Source a) (ServerName a)

-- | <a>Prism</a> for <a>Privmsg</a>
_Privmsg :: Prism' (Message a) (Target a, Either CTCPByteString a)

-- | <a>Prism</a> for <a>Notice</a>
_Notice :: Prism' (Message a) (Target a, Either CTCPByteString a)

-- | <a>Prism</a> for <a>Nick</a>
_Nick :: Prism' (Message a) (NickName a)

-- | <a>Prism</a> for <a>Join</a>
_Join :: Prism' (Message a) (ChannelName a)

-- | <a>Prism</a> for <a>Part</a>
_Part :: Prism' (Message a) (ChannelName a, Reason a)

-- | <a>Prism</a> for <a>Quit</a>
_Quit :: Prism' (Message a) (Reason a)

-- | <a>Prism</a> for <a>Mode</a>
_Mode :: Prism' (Message a) (Target a, IsModeSet, [ModeFlag a], [ModeArg a])

-- | <a>Prism</a> for <a>Topic</a>
_Topic :: Prism' (Message a) (ChannelName a, a)

-- | <a>Prism</a> for <a>Invite</a>
_Invite :: Prism' (Message a) (ChannelName a, NickName a)

-- | <a>Prism</a> for <a>Kick</a>
_Kick :: Prism' (Message a) (ChannelName a, NickName a, Reason a)

-- | <a>Prism</a> for <a>Ping</a>
_Ping :: Prism' (Message a) (ServerName a, Maybe (ServerName a))

-- | <a>Prism</a> for <a>Pong</a>
_Pong :: Prism' (Message a) (ServerName a)

-- | <a>Prism</a> for <a>Numeric</a>
_Numeric :: Prism' (Message a) (Int, [NumericArg a])

-- | <a>Prism</a> for <a>RawMsg</a>
_RawMsg :: Prism' (Message a) a


-- | Conduits for serialising and deserialising IRC messages.
--   
--   The <a>Event</a>, <a>Message</a>, and <a>Source</a> types are
--   parameterised on the underlying representation, and are functors.
--   Decoding and encoding only work in terms of <a>ByteString</a>s, but
--   the generality is provided so that programs using this library can
--   operate in terms of <tt>Text</tt>, or some other more useful
--   representation, with great ease.
module Network.IRC.Conduit
type ChannelName a = a
type NickName a = a
type ServerName a = a
type Reason a = Maybe a
type IsModeSet = Bool
type ModeFlag a = a
type ModeArg a = a
type NumericArg a = a

-- | The target of a message. Will be a nick or channel name.
type Target a = a
type IrcEvent = Event ByteString
type IrcSource = Source ByteString
type IrcMessage = Message ByteString

-- | 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 <a>RawMsg</a>.
[_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

-- | A conduit which takes as input bytestrings representing encoded IRC
--   messages, and decodes them to events. If decoding fails, the original
--   bytestring is just passed through.
ircDecoder :: Monad m => ConduitM ByteString (Either ByteString IrcEvent) m ()

-- | Like <a>ircDecoder</a>, but discards messages which could not be
--   decoded.
ircLossyDecoder :: Monad m => ConduitM ByteString IrcEvent m ()

-- | A conduit which takes as input irc messages, and produces as output
--   the encoded bytestring representation.
ircEncoder :: Monad m => ConduitM IrcMessage ByteString m ()

-- | A conduit which rate limits output sent downstream. Awaiting on this
--   conduit will block, even if there is output ready, until the time
--   limit has passed.
floodProtector :: MonadIO m => NominalDiffTime -> IO (ConduitM a a m ())

-- | Connect to a network server, without TLS, and concurrently run the
--   producer and consumer.
ircClient :: Int -> ByteString -> IO () -> ConduitM (Either ByteString IrcEvent) Void IO () -> ConduitM () IrcMessage IO () -> IO ()

-- | Run the IRC conduits using a provided connection.
--   
--   Starts the connection and concurrently run the initialiser, event
--   consumer, and message sources. Terminates as soon as one throws an
--   exception.
ircWithConn :: ((AppData -> IO ()) -> IO ()) -> IO () -> ConduitM (Either ByteString IrcEvent) Void IO () -> ConduitM () IrcMessage IO () -> IO ()

-- | Like <a>ircClient</a>, but with TLS. The TLS configuration used is
--   <a>defaultTLSConfig</a>.
ircTLSClient :: Int -> ByteString -> IO () -> ConduitM (Either ByteString IrcEvent) Void IO () -> ConduitM () IrcMessage IO () -> IO ()

-- | Like <a>ircTLSClient</a>, but takes the configuration to use, which
--   includes the host and port.
ircTLSClient' :: TLSClientConfig -> IO () -> ConduitM (Either ByteString IrcEvent) Void IO () -> ConduitM () IrcMessage IO () -> IO ()

-- | The default TLS settings for <a>ircTLSClient</a>.
defaultTLSConfig :: Int -> ByteString -> TLSClientConfig

-- | 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
