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


-- | A CTCP encoding and decoding library for IRC clients.
--   
--   CTCP (Client To Client Protocol) is a way of sending arbitrary data
--   over an IRC network, which may include bytes not allowed in standard
--   IRC messages. CTCPs are sent as a PRIVMSG or NOTICE, where the first
--   and last characters as <tt>\001</tt> (SOH), and special bytes are
--   escaped by encoding them into a two-byte sequence beginning with
--   <tt>\020</tt> (DLE). CTCPs consist of command name (typically in
--   upper-case) followed by list of space-separated arguments, which may
--   be empty.
--   
--   One use of CTCPs supported by the vast majority of IRC clients today
--   is the ACTION command, typically invoked with /me. For example, if the
--   user <tt>foo</tt> in the channel <tt>#bar</tt> were to issue
--   
--   <pre>
--   /me dances
--   </pre>
--   
--   everyone in the channel would receive the message
--   
--   <pre>
--   :foo PRIVMSG #bar :\001ACTION dances\001
--   </pre>
--   
--   Other common uses of CTCP include requesting the name and version of a
--   user's IRC client, their local time, determining ping times, and
--   initiating file transfers (DCC).
--   
--   Characters are escaped as follows:
--   
--   <ul>
--   <li><i><tt>\000</tt> (NUL)</i> <tt>\020 \060</tt> ("0")</li>
--   <li><i><tt>\012</tt> (NL)</i> <tt>\020 \156</tt> ("n")</li>
--   <li><i><tt>\015</tt> (CR)</i> <tt>\020 \162</tt> ("r")</li>
--   <li><i><tt>\020</tt> (DLE)</i> <tt>\020 \020</tt></li>
--   </ul>
--   
--   All other appearences of the escape character are errors, and are
--   dropped.
--   
--   See <a>http://www.irchelp.org/irchelp/rfc/ctcpspec.html</a> for more
--   details.
@package irc-ctcp
@version 0.1.3.0


-- | Functions for encoding and decoding CTCPs.
module Network.IRC.CTCP

-- | Type representing a CTCP-encoded bytestring.
data CTCPByteString

-- | Get the underlying (encoded) bytestring from a CTCP bytestring.
getUnderlyingByteString :: CTCPByteString -> ByteString

-- | Turn a command name and arguments into a CTCP-encoded bytestring.
--   
--   This encodes the text with UTF-8. If another encoding is desired,
--   <a>encodeCTCP</a> should be used directly.
toCTCP :: Text -> [Text] -> CTCPByteString

-- | Decode a CTCP-encoded bytestring and turn it into a command name and
--   arguments.
--   
--   This decodes the text with UTF-8. If another encoding is desired,
--   <a>decodeCTCP</a> should be used directly.
fromCTCP :: CTCPByteString -> (Text, [Text])

-- | Encode a bytestring according to the CTCP spec.
encodeCTCP :: ByteString -> CTCPByteString

-- | Decode a CTCP bytestring. Extraeneous escapes are dropped.
decodeCTCP :: CTCPByteString -> ByteString

-- | Check if a bytestring represents a CTCP.
--   
--   This is intentionally very lenient, in particular it doesn't check
--   that there are no extra escape characters. This is because the spec
--   states that misplaced escape characters should be discarded by the
--   decoding process.
isCTCP :: ByteString -> Bool

-- | Check if a bytestring looks like a CTCP, and if so, wrap it up in the
--   <a>CTCPByteString</a> type.
--   
--   This uses <a>isCTCP</a>, and so is lenient with escapes.
asCTCP :: ByteString -> Maybe CTCPByteString

-- | Apply one of two functions depending on whether the bytestring looks
--   like a CTCP or not.
--   
--   This uses <a>asCTCP</a>, and so is lenient with escapes.
orCTCP :: (ByteString -> a) -> (CTCPByteString -> a) -> ByteString -> a
instance GHC.Show.Show Network.IRC.CTCP.CTCPByteString
instance GHC.Classes.Eq Network.IRC.CTCP.CTCPByteString
