-- 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>
--   import Network.SOAP
--   import Network.SOAP.Transport.HTTP
--   
--   import Text.XML.Writer
--   import Text.XML.Stream.Parse as Parse
--   import           Data.Text (Text)
--   import qualified Data.Text as T
--   
--   main :: IO ()
--   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 . T.unpack $ age)
--   </pre>
--   
--   Notice: to invoke HTTPS services you need to initialize a transport
--   from soap-tls or soap-openssl.
--   
--   Full examples available at source repo:
--   <a>https://bitbucket.org/dpwiz/haskell-soap/src/HEAD/soap/examples/</a>
@package soap
@version 0.2.3.2


-- | 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  SOAPAction header -> Document  XML document with a SOAP request -> IO ByteString

module Network.SOAP.Transport.HTTP

-- | Create a http-client transport using manager settings (for plugging
--   tls etc.).
initTransportWithM :: ManagerSettings -> EndpointURL -> RequestProc -> BodyProc -> 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 RequestProc = Request -> IO Request
printRequest :: RequestProc

-- | Process response body to make it a nice UTF8-encoded XML document.
type BodyProc = ByteString -> IO ByteString
printBody :: BodyProc

-- | Render document, submit it as a POST request and retrieve a body.
runQueryM :: Manager -> EndpointURL -> RequestProc -> BodyProc -> Transport

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

-- | <i>Deprecated: Processors were lifted to IO.</i>
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

-- | <i>Deprecated: Processors were lifted to IO.</i>
type RequestP = Request -> Request

-- | Show a debug dump of a request body.

-- | <i>Deprecated: Processors were lifted to IO.</i>
traceRequest :: RequestP

-- | <i>Deprecated: Processors were lifted to IO.</i>
type BodyP = ByteString -> ByteString

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

-- | Show a debug dump of a response body.

-- | <i>Deprecated: Processors were lifted to IO.</i>
traceBody :: BodyP

-- | <i>Deprecated: Processors were lifted to IO.</i>
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


-- | 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 GHC.Show.Show Network.SOAP.Exception.SOAPFault
instance GHC.Classes.Eq Network.SOAP.Exception.SOAPFault
instance GHC.Show.Show Network.SOAP.Exception.SOAPParsingError
instance GHC.Exception.Exception Network.SOAP.Exception.SOAPParsingError
instance GHC.Exception.Exception Network.SOAP.Exception.SOAPFault


-- | 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  SOAPAction header -> Document  XML document with a SOAP request -> IO ByteString
runResponseParser :: ResponseParser a -> ByteString -> IO a

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