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


-- | SOAP client tools
--   
--   Tools to build SOAP clients using xml-conduit.
--   
--   A mildly-complicated example:
--   
--   <pre>
--   main = do
--       -- Initial one-time preparations.
--       certP &lt;- clientCert "priv/client.crt" "priv/client.key"
--       transport &lt;- initTransport "https://example.com/soap/endpoint" certP (iconv "cp-1251")
--   
--       -- Making queries
--       activeStaff &lt;- listStaff transport True
--       print activeStaff
--   
--   data Person = Person Text Int deriving Show
--   
--   listStaff :: Transport -&gt; Bool -&gt; IO [Person]
--   listStaff t active = invokeWS t "urn:dummy:listStaff" () body parser
--       where
--           body = element "request" $ element "listStaff" $ do
--                      element "active" $ toXML active
--                      element "order" "age"
--                      element "limit" $ toXML (10 :: Int)
--   
--           parser = StreamParser $ force "no people" $ tagNoAttr "people" $ Parse.many parsePerson
--   
--           parsePerson = tagName "person" (requireAttr "age") $ \age -&gt; do
--                             name &lt;- Parse.content
--                             return $ Person name (read . unpack $ age)
--   </pre>
--   
--   Changelog
--   
--   <ul>
--   <li>0.2: Switch to xml-conduit-writer for more clean serializers.
--   Pluggable transports. Raw and streaming parsers.</li>
--   <li>0.1: Initial implementation, somewhat inflexible and warty, but
--   working with diverse services.</li>
--   </ul>
@package soap
@version 0.2.0.0


-- | Some helpers to parse documents with Text.XML.Cursor.
module Network.SOAP.Parsing.Cursor

-- | Grab node content by element name.
--   
--   <pre>
--   pair cur = (readT "fst" cur, readT "snd" cur)
--   </pre>
readT :: Text -> Cursor -> Text

-- | Extract a read-able type from a content of a node with given name.
--   
--   <pre>
--   age = readC "age" :: Cursor -&gt; Integer
--   </pre>
readC :: Read a => Text -> Cursor -> a

-- | Apply an axis and extract a key-value from child elements.
--   
--   <pre>
--   invokeWS … (CursorParser . readDict $ laxElement "WebScaleResponse" &amp;/ laxElement "BigDataResult")
--   </pre>
readDict :: Axis -> Cursor -> Dict

-- | Very generic type to catch server reply when you don't care about
--   types.
type Dict = HashMap Text Text


-- | This package comes with a single transport, but the your vendor's SOAP
--   implementation can behave very differently, so invokeWS can be rigged
--   to use anything that follows a simple interface.
module Network.SOAP.Transport

-- | Common transport type. Get a request and deliver it to an endpoint
--   specified during initialization.
type Transport = String -> Document -> IO ByteString


-- | A feature-rich http-conduit based transport allowing to deal with
--   HTTPS, authentication and other stuff using request and body
--   processors.
module Network.SOAP.Transport.HTTP.Conduit

-- | Create a http-conduit transport. Use identity transformers if you
--   don't need any special treatment.
initTransport :: EndpointURL -> RequestP -> BodyP -> IO Transport

-- | Create a transport without any request and body processing.
initTransport_ :: EndpointURL -> IO Transport

-- | Web service URL. Configured at initialization, but you can tweak it
--   dynamically with a request processor.
type EndpointURL = String

-- | Update request record after defaults and method-specific fields are
--   set.
type RequestP = Request (ResourceT IO) -> Request (ResourceT IO)

-- | Load certificate, key and make a request processor setting them.
clientCert :: FilePath -> FilePath -> IO RequestP

-- | Process response body to make it a nice UTF8-encoded XML document.
type BodyP = ByteString -> ByteString

-- | Create an IConv-based processor.
iconv :: EncodingName -> BodyP

-- | Render document, submit it as a POST request and retrieve a body.
runQuery :: Manager -> EndpointURL -> RequestP -> BodyP -> Transport


-- | Debug transport to train your parsers without bugging real services.
module Network.SOAP.Transport.Mock

-- | Wrap a collection of handlers into a transport.
initTransport :: Handlers -> IO Transport
type Handler = Document -> IO ByteString
type Handlers = [(String, Handler)]

-- | Process a Document and wrap result in a SOAP Envelope.
handler :: ToXML a => (Document -> IO a) -> Handler

-- | Choose and apply a handler.
runQuery :: [(String, Handler)] -> Transport


-- | A heart of the package, <a>invokeWS</a> assembles and executes
--   requests.
module Network.SOAP

-- | Prepare data, assemble request and apply a parser to a response.
invokeWS :: (ToXML h, ToXML b) => Transport -> String -> h -> b -> ResponseParser a -> IO a

-- | Common transport type. Get a request and deliver it to an endpoint
--   specified during initialization.
type Transport = String -> Document -> IO ByteString

-- | Different parsing modes available to extract reply contents.
data ResponseParser a

-- | Streaming parser from Text.XML.Stream.Parse
StreamParser :: (Parser a) -> ResponseParser a

-- | XPath-like parser from Text.XML.Cursor
CursorParser :: (Cursor -> a) -> ResponseParser a

-- | Work with a raw bytestring.
RawParser :: (ByteString -> a) -> ResponseParser a

-- | Stream parser from Text.XML.Stream.Parse.
type Parser a = Sink Event (ResourceT IO) a