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


-- | Stomp Parser and Utilities
--   
--   The Stomp Protocol specifies message-oriented interoperability.
--   Applications connect to a message broker to send (publish) or receive
--   (subscribe) messages through queues. Interoperating applications do
--   not know the location or internal structure of each other. They see
--   only each other's interfaces, <i>i.e.</i> the messages published and
--   subscribed through the broker. Broker and application use a protocol
--   based on the exchange of commands and other data packets, called
--   <i>frames</i>. The Stompl library provides abstractions over Stomp
--   frames and a Stomp frame parser. It does not implement a client or
--   broker itself, but provides abstractions to libraries and programs
--   doing so. It is used by the Stompl Queue library (stomp-queues). More
--   documentation and a test suite can be found on
--   <a>https://github.com/toschoo/mom/</a>. The Stomp specification can be
--   found at <a>http://stomp.github.com</a>.
@package stompl
@version 0.5.0


-- | Stomp Frames and some useful operations on them
module Network.Mom.Stompl.Frame

-- | This is a frame
data Frame

-- | The frame type identifies, what the Stomp protocol calls
--   <i>command</i>;
--   
--   <ul>
--   <li>commands sent from application to broker are: Connect, Disconnect,
--   Subscribe, Unsubscribe, Send, Begin, Commit, Abort, Ack, Nack,
--   HeartBeat</li>
--   <li>commands sent from broker to application are: Connected, Message,
--   Error, HeartBeat</li>
--   </ul>
data FrameType

-- | Sent by the application to initiate a connection
Connect :: FrameType

-- | Same as Connect, but with <a>STOMP</a> instead of <a>CONNECT</a>
Stomp :: FrameType

-- | Sent by the broker to confirm the connection
Connected :: FrameType

-- | Sent by the application to end the connection
Disconnect :: FrameType

-- | Sent by the application to publish a message in a queue
Send :: FrameType

-- | Sent by the broker to forward a message published in a queue to which
--   the application has subscribed
Message :: FrameType

-- | Sent by the application to subscribe to a queue
Subscribe :: FrameType

-- | Sent by the application to unsubscribe from a queue
Unsubscribe :: FrameType

-- | Sent by the application to start a transaction
Begin :: FrameType

-- | Sent by the application to commit a transaction
Commit :: FrameType

-- | Sent by the application to abort a transaction
Abort :: FrameType

-- | Sent by the application to acknowledge a message
Ack :: FrameType

-- | Sent by the application to negatively acknowledge a message
Nack :: FrameType

-- | Keep-alive message sent by both, application and broker
HeartBeat :: FrameType

-- | Sent by the broker to report an error
Error :: FrameType

-- | Sent by the broker to confirm the receipt of a frame
Receipt :: FrameType

-- | Tuple of (key, value)
type Header = (String, String)

-- | The Frame body is represented as <i>strict</i> <tt>ByteString</tt>.
type Body = ByteString

-- | Heart-beat configuration; the first <a>Int</a> of the pair represents
--   the frequency in which the sender wants to send heart-beats; the
--   second represents the highest frequency in which the sender can accept
--   heart-beats. The frequency is expressed as the period in milliseconds
--   between two heart-beats. For details on negotiating heart-beats,
--   please refer to the Stomp specification.
type Heart = (Int, Int)

-- | The Stomp version used or accepted by the sender; the first <a>Int</a>
--   is the major version number, the second is the minor. For details on
--   version negotiation, please refer to the Stomp specification.
type Version = (Int, Int)
data AckMode

-- | A successfully sent message is automatically considered ack'd
Auto :: AckMode

-- | The client is expected to explicitly confirm the receipt of a message
--   by sending an <a>Ack</a> frame; all message older than the ack'd
--   message since the last <a>Ack</a> (or the beginning of the session)
--   are implicitly ack'd as well. This is called <i>cumulative</i> ack.
Client :: AckMode

-- | Non-cumulative ack: The client is expected to explicitly confirm the
--   receipt of a message by sending an <a>Ack</a> frame; only the message
--   with the msg-id in the <a>Ack</a> frame is actually ack'd
ClientIndi :: AckMode

-- | check if <a>String</a> represents a valid <a>AckMode</a>
isValidAck :: String -> Bool

-- | Description of a server consisting of name, version and comments
type SrvDesc = (String, String, String)

-- | get name from <a>SrvDesc</a>
getSrvName :: SrvDesc -> String

-- | get version from <a>SrvDesc</a>
getSrvVer :: SrvDesc -> String

-- | get comments from <a>SrvDesc</a>
getSrvCmts :: SrvDesc -> String

-- | make a <a>Connect</a> frame (Application -&gt; Broker). The parameters
--   are:
--   
--   <ul>
--   <li>User: user to authenticate at the broker.</li>
--   <li>Passcode: password to authenticate at the broker.</li>
--   <li>Host: broker's virtual hoast (<i>e.g.</i>
--   stomp.broker.github.org).</li>
--   <li><a>HeartBeat</a>: the clients bid in negotiating the
--   heart-beat.</li>
--   <li><a>Version</a>: the versions supported by the client.</li>
--   <li>ClientId: Client identification for persistent connections. Note
--   that the client id is not a standard Stomp feature, but specific to
--   ActiveMQ and other brokers.</li>
--   <li><a>Header</a>: List of additional, broker-specific headers</li>
--   </ul>
mkConnect :: String -> String -> String -> Heart -> [Version] -> String -> [Header] -> Frame

-- | Same as <a>mkConnect</a>, but the result is a "STOMP" frame rather
--   than a "CONNECT" frame
mkStomp :: String -> String -> String -> Heart -> [Version] -> String -> [Header] -> Frame

-- | make a <a>Connect</a> frame (Broker -&gt; Application). The parameters
--   are:
--   
--   <ul>
--   <li>Session: A unique identifier created by the broker and identifying
--   the session</li>
--   <li><a>HeartBeat</a>: The heart-beat agreed by the broker</li>
--   <li><a>Version</a>: The version accepted by the broker</li>
--   <li><a>SrvDesc</a>: The server description</li>
--   <li><a>Header</a>: List of additional, broker-specific headers.</li>
--   </ul>
mkConnected :: String -> Heart -> Version -> SrvDesc -> [Header] -> Frame

-- | make a <a>Subscribe</a> frame (Application -&gt; Broker). The
--   parameters are:
--   
--   <ul>
--   <li>Destination: The name of the queue as it is known by the broker
--   and other applications using the queue</li>
--   <li><a>AckMode</a>: The Acknowledge Mode for this subscription</li>
--   <li>Selector: An expression defining those messages that are of actual
--   for client. The Stomp protocol does not define a language for
--   selectors; it is even not entirely clear, where messages are selected:
--   already at the broker, or only by the client. Some brokers provide
--   pre-selection of messages, others do not.</li>
--   <li>Subscription Id: A unique identifier distinguishing this
--   subscription from others to the same queue. The identifier is defined
--   by the application.</li>
--   <li>Receipt: A unique identifier defined by the application to request
--   confirmation of receipt of this frame. If no receipt is wanted, the
--   string shall be empty.</li>
--   <li><a>Header</a>: List of additional, broker-specific headers.</li>
--   </ul>
mkSubscribe :: String -> AckMode -> String -> String -> String -> [Header] -> Frame

-- | make an <a>Unsubscribe</a> frame (Application -&gt; Broker). The
--   parameters are:
--   
--   <ul>
--   <li>Destination: The queue name; either a destination or a
--   subscription id must be given. (According to protocol version 1.1, the
--   subscription id is mandatory on both, <a>Subscribe</a> and
--   <a>Unsubscribe</a>.)</li>
--   <li>Subscription Id: The subscription identifier (see
--   <a>mkSubscribe</a>)</li>
--   <li>Receipt: The receipt (see <a>mkSubscribe</a>)</li>
--   <li><a>Header</a>: Additional, broker-specific headers</li>
--   </ul>
mkUnsubscribe :: String -> String -> String -> [Header] -> Frame

-- | make a <a>Send</a> frame (Application -&gt; Broker). The parameters
--   are:
--   
--   <ul>
--   <li>Destination: The name of the queue where the message should be
--   published</li>
--   <li>Transaction: A unique identifier indicating a running transaction;
--   if sent with a transaction, the message will not be delivered to
--   subscribing applications, before the transaction is committed. If the
--   <a>Send</a> is not part of a transaction, the string shall be
--   empty.</li>
--   <li>Receipt: A receipt (see <a>mkSubscribe</a> for details)</li>
--   <li><a>Type</a>: The content type of the payload message as MIME
--   Type</li>
--   <li>Length: The length of the type in bytes</li>
--   <li><a>Header</a>: List of additional headers; Stomp protocol requires
--   that user-specified headers are passed through to subscribing
--   applications. These headers may, for instance, be use by selectors to
--   select messages.</li>
--   <li><a>Body</a>: The payload message</li>
--   </ul>
mkSend :: String -> String -> String -> Type -> Int -> [Header] -> Body -> Frame

-- | make a <a>Message</a> frame (Broker -&gt; Application). The parameters
--   are:
--   
--   <ul>
--   <li>Subscription Id: The message was sent because the application
--   subscribed to the queue with this subscription id (see
--   <a>mkSubscribe</a>).</li>
--   <li>Destination: The name of the queue, in wich the message was
--   published.</li>
--   <li>Message Id: A unique message identifier, defined by the
--   broker</li>
--   <li><a>Type</a>: The type of the playload as MIME Type</li>
--   <li>Length: The length of the payload in bytes</li>
--   <li><a>Header</a>: A list of user-defined headers (see <a>mkSend</a>
--   for details)</li>
--   <li><a>Body</a>: The payload</li>
--   </ul>
mkMessage :: String -> String -> String -> String -> Type -> Int -> [Header] -> Body -> Frame

-- | make a <a>Receipt</a> frame (Broker -&gt; Application). The parameters
--   are:
--   
--   <ul>
--   <li>Error Message Id: A short error description</li>
--   <li>Receipt Id: The receipt of frame sent by the application to which
--   this error relates</li>
--   <li><a>Type</a>: The format of the error message as MIME Type</li>
--   <li>Length: The length of the error message</li>
--   <li><a>Header</a>: List of additional, broker-specific headers</li>
--   <li><a>Body</a>: The error message</li>
--   </ul>
mkErr :: String -> String -> Type -> Int -> [Header] -> Body -> Frame

-- | make a <a>Begin</a> frame (Application -&gt; Broker). The parameters
--   are:
--   
--   <ul>
--   <li>Transaction: A unique transaction identifier defined by the
--   application.</li>
--   <li>Receipt: A receipt (see <a>mkSubscribe</a> for details)</li>
--   <li><a>Header</a>: Additional, broker-specific headers</li>
--   </ul>
mkBegin :: String -> String -> [Header] -> Frame

-- | make a <a>Commit</a> frame (Application -&gt; Broker). The parameters
--   are:
--   
--   <ul>
--   <li><tt>Transaction</tt>: A unique transaction identifier defined by
--   the application.</li>
--   <li><a>Receipt</a>: A receipt (see <a>mkSubscribe</a> for
--   details)</li>
--   <li><a>Header</a>: Additional, broker-specific headers</li>
--   </ul>
mkCommit :: String -> String -> [Header] -> Frame

-- | make an <a>Abort</a> frame (Application -&gt; Broker). The parameters
--   are:
--   
--   <ul>
--   <li>Transaction: A unique transaction identifier defined by the
--   application.</li>
--   <li>Receipt: A receipt (see <a>mkSubscribe</a> for details)</li>
--   <li><a>Header</a>: Additional, broker-specific headers</li>
--   </ul>
mkAbort :: String -> String -> [Header] -> Frame

-- | make an <a>Ack</a> frame (Application -&gt; Broker). The parameters
--   are:
--   
--   <ul>
--   <li>Message Id: The identifier of the message to be ack'd</li>
--   <li>Subscription Id: The subscription, through which the message was
--   received</li>
--   <li>Transaction: Acks may be part of a transaction (see <a>mkSend</a>
--   for details).</li>
--   <li>Receipt: see <a>mkSubscribe</a> for details</li>
--   </ul>
mkAck :: String -> String -> String -> String -> [Header] -> Frame

-- | make a <a>Nack</a> frame (Application -&gt; Broker). The parameters
--   are:
--   
--   <ul>
--   <li>Message Id: The identifier of the message to be nack'd</li>
--   <li>Subscription Id: The subscription, through which the message was
--   received</li>
--   <li>Transaction: Nacks may be part of a transaction (see <a>mkSend</a>
--   for details).</li>
--   <li>Receipt: see <a>mkSubscribe</a> for details</li>
--   </ul>
mkNack :: String -> String -> String -> String -> [Header] -> Frame

-- | make a <a>Disconnect</a> frame (Application -&gt; Broker). The
--   parameter is:
--   
--   <ul>
--   <li>Receipt: see <a>mkSubscribe</a> for details</li>
--   </ul>
mkDisconnect :: String -> [Header] -> Frame

-- | make a <tt>HeatBeat</tt> frame (Application -&gt; Broker and Broker
--   -&gt; Application)
mkBeat :: Frame

-- | make a <a>Receipt</a> frame (Broker -&gt; Application). The parameter
--   is:
--   
--   <ul>
--   <li>Receipt: The receipt identifier received from the application</li>
--   <li><a>Header</a>: List of additional, broker-specific headers</li>
--   </ul>
mkReceipt :: String -> [Header] -> Frame

-- | make <a>Connect</a> frame
mkConFrame :: [Header] -> Either String Frame

-- | make <a>Stomp</a> frame
mkStmpFrame :: [Header] -> Either String Frame

-- | make <a>Connected</a> frame
mkCondFrame :: [Header] -> Either String Frame

-- | make <a>Disconnect</a> frame
mkDisFrame :: [Header] -> Either String Frame

-- | make <a>Subscribe</a> frame
mkSubFrame :: [Header] -> Either String Frame

-- | make <a>Unsubscribe</a> frame
mkUSubFrame :: [Header] -> Either String Frame

-- | make <a>Send</a> frame
mkSndFrame :: [Header] -> Int -> Body -> Either String Frame

-- | make <a>Message</a> frame
mkMsgFrame :: [Header] -> Int -> Body -> Either String Frame

-- | make <a>Error</a> frame
mkErrFrame :: [Header] -> Int -> Body -> Either String Frame

-- | make <a>Begin</a> frame
mkBgnFrame :: [Header] -> Either String Frame

-- | make <a>Commit</a> frame
mkCmtFrame :: [Header] -> Either String Frame

-- | make <a>Abort</a> frame
mkAbrtFrame :: [Header] -> Either String Frame

-- | make <a>Ack</a> frame
mkAckFrame :: [Header] -> Either String Frame

-- | make <a>Nack</a> frame
mkNackFrame :: [Header] -> Either String Frame

-- | make <a>Receipt</a> frame
mkRecFrame :: [Header] -> Either String Frame

-- | make <i>login</i> header
mkLogHdr :: String -> Header

-- | make <i>passcode</i> header
mkPassHdr :: String -> Header

-- | make <i>destination</i> header
mkDestHdr :: String -> Header

-- | make <i>content-length</i> header
mkLenHdr :: String -> Header

-- | make <i>transaction</i> header
mkTrnHdr :: String -> Header

-- | make <i>receipt</i> header
mkRecHdr :: String -> Header

-- | make <i>selector</i> header
mkSelHdr :: String -> Header

-- | make <i>id</i> header (subscribe frame)
mkIdHdr :: String -> Header

-- | make <i>ack</i> header (subscribe frame)
mkAckHdr :: String -> Header

-- | make <i>session</i> header (connected frame)
mkSesHdr :: String -> Header

-- | make <i>message</i> header (error frame)
mkMsgHdr :: String -> Header

-- | make <i>message-id</i> header
mkMIdHdr :: String -> Header

-- | make <i>accept-version</i> header (connect frame)
mkAcVerHdr :: String -> Header

-- | make <i>version</i> header (connected frame)
mkVerHdr :: String -> Header

-- | make <i>host</i> header (connect frame)
mkHostHdr :: String -> Header

-- | make <i>heart-beat</i> header
mkBeatHdr :: String -> Header

-- | make <i>content-type</i> header
mkMimeHdr :: String -> Header

-- | make <i>server</i> header (connected frame)
mkSrvHdr :: String -> Header

-- | make <i>subscription</i> header
mkSubHdr :: String -> Header

-- | make <i>client-id</i> header
mkCliIdHdr :: String -> Header

-- | convert <a>String</a> to <a>Version</a>
valToVer :: String -> Maybe Version

-- | convert <a>String</a> to list of <a>Version</a>
valToVers :: String -> Maybe [Version]

-- | convert <a>Version</a> to <a>String</a>
verToVal :: Version -> String

-- | convert list of <a>Version</a> to <a>String</a>
versToVal :: [Version] -> String

-- | convert <a>HeartBeat</a> to <a>String</a>
beatToVal :: Heart -> String

-- | convert <a>String</a> to <a>HeartBeat</a>
valToBeat :: String -> Maybe Heart

-- | convert <a>AckMode</a> to <a>String</a>
ackToVal :: AckMode -> String

-- | convert <a>String</a> to <a>AckMode</a>
valToAck :: String -> Maybe AckMode

-- | convert <a>String</a> to <a>SrvDesc</a>
strToSrv :: String -> SrvDesc

-- | convert <a>SrvDesc</a> to <a>String</a>
srvToStr :: SrvDesc -> String

-- | negotiates version - if no common version is found, the function
--   results in version 1.0!
negoVersion :: [Version] -> [Version] -> Version

-- | negotiates heart-beat
negoBeat :: Heart -> Heart -> Heart

-- | remove header (<a>String</a>) from list of <a>Header</a>
rmHdr :: [Header] -> String -> [Header]

-- | remove headers (list of <a>String</a>) from list of <a>Header</a>
rmHdrs :: [Header] -> [String] -> [Header]
getAck :: [Header] -> Either String AckMode
getLen :: [Header] -> Either String Int

-- | gets the <a>FrameType</a> of a <a>Frame</a>
typeOf :: Frame -> FrameType

-- | converts a <a>Frame</a> into a <a>ByteString</a>
putFrame :: Frame -> ByteString

-- | converts a <a>Frame</a> into a <a>String</a>
toString :: Frame -> String

-- | converts the <a>FrameType</a> into a <a>ByteString</a>
putCommand :: Frame -> ByteString

-- | converts a <a>Send</a> frame into a <a>Message</a> frame; parameters:
--   
--   <ul>
--   <li>message id</li>
--   <li>subscription id</li>
--   <li>The original <a>Send</a> frame</li>
--   </ul>
sndToMsg :: String -> String -> String -> Frame -> Maybe Frame

-- | converts a <a>Connect</a> frame into a <a>Connected</a> frame,
--   negotiating heart-beats and version; parameters:
--   
--   <ul>
--   <li>server desc</li>
--   <li>session id</li>
--   <li>caller's bid for heart-beat</li>
--   <li>caller's supported versions</li>
--   <li>the original <a>Connect</a> frame</li>
--   </ul>
conToCond :: String -> String -> Heart -> [Version] -> Frame -> Maybe Frame

-- | sets the transaction header to an empty string; this is a useful
--   function for brokers: when a transaction has been committed, the
--   <a>Send</a> messages can be handled by the same function without,
--   accidentally, iterating into a new transaction.
resetTrans :: Frame -> Frame

-- | Compliance with protocol version
complies :: Version -> Frame -> Bool

-- | get <i>destination</i> from <a>Subscribe</a>, <a>Unsubscribe</a>,
--   <a>Send</a> or <a>Message</a>
getDest :: Frame -> String

-- | get <i>transaction</i> from <a>Send</a>, <a>Ack</a>, <a>Nack</a>,
--   <a>Begin</a>, <a>Commit</a> or <a>Abort</a>
getTrans :: Frame -> String

-- | get <i>receipt</i> or <i>receipt-id</i> from any frame, but
--   <a>Connect</a>, <a>Connected</a>, <a>Message</a>, <a>Error</a>
getReceipt :: Frame -> String

-- | get <i>login</i> from <a>Connect</a>
getLogin :: Frame -> String

-- | get <i>passcode</i> from <a>Connect</a>
getPasscode :: Frame -> String

-- | get <i>client-id</i> from <a>Connect</a>
getCliId :: Frame -> String

-- | get <i>host</i> from <a>Connect</a>
getHost :: Frame -> String

-- | get <i>accept-version</i> from <a>Connect</a>
getVersions :: Frame -> [Version]

-- | get <i>version</i> from <a>Connected</a>
getVersion :: Frame -> Version

-- | get <i>heart-beat</i> from <a>Connect</a> or <a>Connected</a>
getBeat :: Frame -> Heart

-- | get <i>session</i> from <a>Connected</a>
getSession :: Frame -> String

-- | get <i>server</i> from <a>Connected</a>
getServer :: Frame -> SrvDesc

-- | get <i>subscription</i> from <a>Ack</a>, <a>Nack</a> or <a>Message</a>
getSub :: Frame -> String

-- | get <i>selector</i> from <a>Subscribe</a>
getSelector :: Frame -> String

-- | get <i>id</i> from <a>Subscribe</a> or <a>Unsubscribe</a>
getId :: Frame -> String

-- | get <i>ack</i> from <a>Subscribe</a>
getAcknow :: Frame -> AckMode

-- | get <i>ack</i> or <i>message-id</i> from <a>Message</a>
getMsgAck :: Frame -> String

-- | get <i>body</i> from <a>Send</a>, <a>Message</a>, <a>Error</a>
getBody :: Frame -> ByteString

-- | get <i>content-type</i> from <a>Send</a>, <a>Message</a>, <a>Error</a>
getMime :: Frame -> Type

-- | get <i>content-length</i> from <a>Send</a>, <a>Message</a>,
--   <a>Error</a>
getLength :: Frame -> Int

-- | get <i>message</i> from <a>Error</a>
getMsg :: Frame -> String

-- | get all additional headers from <a>Send</a> or <a>Message</a>
getHeaders :: Frame -> [Header]

-- | snoc
(|>) :: ByteString -> Word8 -> ByteString
infixr 9 |>

-- | cons
(<|) :: Word8 -> ByteString -> ByteString
infixr 9 <|

-- | append
(>|<) :: ByteString -> ByteString -> ByteString
infixr 9 >|<
upString :: String -> String
numeric :: String -> Bool
instance GHC.Classes.Eq Network.Mom.Stompl.Frame.Frame
instance GHC.Show.Show Network.Mom.Stompl.Frame.Frame
instance GHC.Classes.Eq Network.Mom.Stompl.Frame.AckMode
instance GHC.Classes.Eq Network.Mom.Stompl.Frame.FrameType
instance GHC.Read.Read Network.Mom.Stompl.Frame.FrameType
instance GHC.Show.Show Network.Mom.Stompl.Frame.FrameType
instance GHC.Show.Show Network.Mom.Stompl.Frame.AckMode
instance GHC.Read.Read Network.Mom.Stompl.Frame.AckMode


-- | Stomp Parser based on Attoparsec
module Network.Mom.Stompl.Parser

-- | The Stomp Parser
stompParser :: Parser Frame

-- | Parses a ByteString at once with Attoparsec <a>parseOnly</a>. May fail
--   or conclude.
stompAtOnce :: ByteString -> Either String Frame