-- 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.
--       transport &lt;- initTransport "http://example.com/soap/endpoint" id (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" active
--                      element "order" $ T.pack "age"
--                      element "limit" (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>
--   
--   Notice: to invoke HTTPS services you need to initialize a transport
--   from soap-tls or soap-openssl.
@package soap
@version 0.2.2.2


-- | Collection of helpers to use with Text.XML.Stream.Parse parsers.
--   
--   <pre>
--   let sink = flaxTag "MethodNameResponse"
--            $ flaxTag "MethodNameResult" $ do
--                info &lt;- flaxTag "Info" $ do
--                            q &lt;- readTag "quantity"
--                            b &lt;- readTag "balance"
--                            return $ Info q b
--                rc &lt;- readTag "ResponseCode"
--                return (rc, info)
--   </pre>
module Network.SOAP.Parsing.Stream

-- | Namespace- and attribute- ignorant tagNoAttr.
laxTag :: MonadThrow m => Text -> Sink Event m a -> Sink Event m (Maybe a)

-- | Non-maybe version of laxTag/tagNoAttr.
flaxTag :: MonadThrow m => Text -> Sink Event m a -> Sink Event m a
laxContent :: MonadThrow m => Text -> Sink Event m (Maybe Text)
flaxContent :: MonadThrow m => Text -> Sink Event m Text

-- | Unpack and read a current tag content.
readContent :: (Read a, MonadThrow m) => Sink Event m a

-- | Unpack and read tag content by local name.
readTag :: (Read a, MonadThrow m) => Text -> Sink Event m a

-- | Consumes a stream of input values and produces a final result, without
--   producing any output.
--   
--   <pre>
--   type Sink i m r = ConduitM i Void m r
--   </pre>
--   
--   Since 0.5.0
type Sink i = ConduitM i Void

-- | Some XML processing tools are incremental, and work in terms of events
--   rather than node trees. The <a>Event</a> type allows a document to be
--   fully specified as a sequence of events.
--   
--   Event-based XML libraries include:
--   
--   <ul>
--   <li><a>http://hackage.haskell.org/package/xml-enumerator</a></li>
--   <li><a>http://hackage.haskell.org/package/libxml-enumerator</a></li>
--   <li><a>http://hackage.haskell.org/package/expat-enumerator</a></li>
--   </ul>
data Event :: *

module Network.SOAP.Exception
data SOAPParsingError
SOAPParsingError :: String -> SOAPParsingError

-- | Exception to be thrown when transport encounters an exception that is
--   acutally a SOAP Fault.
data SOAPFault
SOAPFault :: Text -> Text -> Text -> SOAPFault
faultCode :: SOAPFault -> Text
faultString :: SOAPFault -> Text
faultDetail :: SOAPFault -> Text

-- | Try to find a SOAP Fault in a document.
extractSoapFault :: Document -> Maybe SOAPFault
instance Typeable SOAPParsingError
instance Typeable SOAPFault
instance Show SOAPParsingError
instance Eq SOAPFault
instance Show SOAPFault
instance Exception SOAPFault
instance Exception SOAPParsingError


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

module Network.SOAP.Transport.HTTP

-- | Create a http-client 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

-- | Create a http-client transport using manager settings (for plugging
--   tls etc.).
initTransportWith :: ManagerSettings -> EndpointURL -> RequestP -> BodyP -> IO Transport

-- | Load common transport parameters from a configurator file.
--   
--   <pre>
--   soap {
--     url = "https://vendor.tld/service/"
--     trace = true
--     timeout = 15
--   }
--   </pre>
--   
--   Only url field is required.
--   
--   <pre>
--   import Data.Configurator (load, Worth(Required))
--   main = do
--       transport &lt;- confTransport "soap" =&lt;&lt; load [Required "etc/example.conf"]
--   </pre>
confTransport :: Text -> Config -> IO Transport

-- | A more extensible transport parameter loader.
confTransportWith :: ManagerSettings -> Text -> Config -> RequestP -> BodyP -> 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 -> Request

-- | Show a debug dump of a request body.
traceRequest :: 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

-- | Show a debug dump of a response body.
traceBody :: 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

-- | Emulate a SOAP fault.
fault :: Text -> Text -> Text -> 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

-- | Parse raw XML document.
DocumentParser :: (Document -> 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

-- | Exception to be thrown when transport encounters an exception that is
--   acutally a SOAP Fault.
data SOAPFault
SOAPFault :: Text -> Text -> Text -> SOAPFault
faultCode :: SOAPFault -> Text
faultString :: SOAPFault -> Text
faultDetail :: SOAPFault -> Text
data SOAPParsingError
SOAPParsingError :: String -> SOAPParsingError


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

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

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

-- | Simple parser to grab a flat response by an element name.
--   
--   <pre>
--   result &lt;- invokeWS … (dictBy "BigDataResult")
--   case HM.lookup "SuccessError" result of …
--   </pre>
dictBy :: Text -> ResponseParser Dict