-- 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:
--   
--   
--   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 <- initTransport "http://example.com/soap/endpoint" id (iconv "cp-1251")
--   
--       -- Making queries
--       activeStaff <- listStaff transport True
--       print activeStaff
--   
--   data Person = Person Text Int deriving Show
--   
--   listStaff :: Transport -> Bool -> 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 -> do
--                             name <- Parse.content
--                             return $ Person name (read . T.unpack $ age)
--   
--   
--   Notice: to invoke HTTPS services you need to initialize a transport
--   from soap-tls or soap-openssl.
--   
--   Full examples available at source repo:
--   https://bitbucket.org/dpwiz/haskell-soap/src/HEAD/soap/examples/
@package soap
@version 0.2.3.6

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

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

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

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

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

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

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

-- | Same as ConduitT, for backwards compat
type ConduitM = ConduitT

-- | Uninhabited data type
data Void

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

-- | 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 heart of the package, invokeWS 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
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 = ConduitM Event Void 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.
--   
--   
--   pair cur = (readT "fst" cur, readT "snd" cur)
--   
readT :: Text -> Cursor -> Text

-- | Extract a read-able type from a content of a node with given name.
--   
--   
--   age = readC "age" :: Cursor -> Integer
--   
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.
--   
--   
--   invokeWS … (CursorParser . readDict $ laxElement "WebScaleResponse" &/ laxElement "BigDataResult")
--   
readDict :: Axis -> Cursor -> Dict

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

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

-- | Deprecated: Processors were lifted to IO.
initTransportWith :: ManagerSettings -> EndpointURL -> RequestP -> BodyP -> IO Transport

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

-- | A more extensible transport parameter loader.
confTransportWith :: ManagerSettings -> Text -> Config -> RequestP -> BodyP -> IO Transport

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

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

-- | Deprecated: Processors were lifted to IO.
traceRequest :: RequestP

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

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

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

-- | Deprecated: Processors were lifted to IO.
traceBody :: BodyP

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