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


-- | JSON-RPC 2.0 on the client side.
--   
--   Functions for creating a JSON-RPC 2.0 client. See
--   <a>http://www.jsonrpc.org/specification</a>. This library supports
--   batch requests and notifications, as well as single method calls. It
--   also provides a function for creating corresponding server-side
--   methods with the package <a>json-rpc-server</a>. This library does not
--   handle transport, so a function for communicating with the server must
--   be provided. The demo folder contains an example client and server
--   that can be compiled with the demo flag. See
--   <a>Network.JsonRpc.Client</a> for details.
@package json-rpc-client
@version 0.2.5.0


-- | Functions for implementing the client side of JSON-RPC 2.0. See
--   <a>http://www.jsonrpc.org/specification</a>.
module Network.JsonRpc.Client

-- | Function used to send requests to the server. <a>Nothing</a>
--   represents no response, as when a JSON-RPC server receives only
--   notifications.
type Connection m = ByteString -> m (Maybe ByteString)

-- | Return type of a method. A method call can either fail with an
--   <a>RpcError</a> or succeed with a result of type <tt>r</tt>.
type RpcResult (m :: * -> *) r = ExceptT RpcError m r

-- | Signature specifying the name, parameter names and types
--   (<tt>ps</tt>), and return type (<tt>r</tt>) of a method.
data Signature ps r
Signature :: Text -> ps -> Signature ps r

-- | A node in a linked list specifying parameter names and types. It is
--   right associative.
data p (:::) ps
(:::) :: Text -> ps -> (:::) p ps

-- | Creates a function for calling a JSON-RPC method on the server.
toFunction :: (Monad m, ClientFunction ps r f, ComposeMultiParam (Batch r -> RpcResult m r) f g) => Connection m -> Signature ps r -> g

-- | Creates a function for calling a JSON-RPC method on the server as a
--   notification.
toFunction_ :: (Monad m, ClientFunction ps r f, ComposeMultiParam (Batch r -> RpcResult m ()) f g) => Connection m -> Signature ps r -> g

-- | A batch call. Batch multiple requests by combining values of this type
--   using its <a>Applicative</a> and <a>Alternative</a> instances before
--   running them with <a>runBatch</a>.
data Batch r

-- | Creates a function for calling a JSON-RPC method as part of a batch
--   request.
toBatchFunction :: ClientFunction ps r f => Signature ps r -> f

-- | Creates a function for calling a JSON-RPC method as a notification and
--   as part of a batch request.
toBatchFunction_ :: (ClientFunction ps r f, ComposeMultiParam (Batch r -> Batch ()) f g) => Signature ps r -> g

-- | Converts all requests in a batch to notifications.
voidBatch :: Batch r -> Batch ()

-- | Evaluates a batch. The process depends on its size:
--   
--   <ol>
--   <li>If the batch is empty, the server function is not called.</li>
--   <li>If the batch has exactly one request, it is sent as a request
--   object.</li>
--   <li>If the batch has multiple requests, they are sent as an array of
--   request objects.</li>
--   </ol>
runBatch :: Monad m => Connection m -> Batch r -> RpcResult m r

-- | JSON-RPC error.
data RpcError
RpcError :: Int -> Text -> Maybe Value -> RpcError
[errCode] :: RpcError -> Int
[errMsg] :: RpcError -> Text
[errData] :: RpcError -> Maybe Value

-- | Code used for all client-side errors. It is -31999.
clientCode :: Int

-- | Relationship between the parameters (<tt>ps</tt>), return type
--   (<tt>r</tt>), and client-side batch function (<tt>f</tt>) of a
--   JSON-RPC method.
class ClientFunction ps r f | ps r -> f, f -> ps r

-- | Relationship between a function (<tt>g</tt>) taking any number of
--   arguments and yielding a <tt><a>Batch</a> a</tt>, a function
--   (<tt>f</tt>) taking a <tt><a>Batch</a> a</tt>, and the function
--   (<tt>h</tt>) that applies g to all of its arguments and then applies f
--   to the result.
class ComposeMultiParam f g h | f g -> h, g h -> f
instance GHC.Show.Show ps => GHC.Show.Show (p Network.JsonRpc.Client.::: ps)
instance GHC.Show.Show ps => GHC.Show.Show (Network.JsonRpc.Client.Signature ps r)
instance Data.Aeson.Types.FromJSON.FromJSON Network.JsonRpc.Client.Response
instance Data.Aeson.Types.ToJSON.ToJSON Network.JsonRpc.Client.IdRequest
instance GHC.Base.Functor Network.JsonRpc.Client.Batch
instance GHC.Base.Applicative Network.JsonRpc.Client.Batch
instance GHC.Base.Alternative Network.JsonRpc.Client.Batch
instance Data.Aeson.Types.FromJSON.FromJSON r => Network.JsonRpc.Client.ClientFunction () r (Network.JsonRpc.Client.Batch r)
instance Network.JsonRpc.Client.ComposeMultiParam (Network.JsonRpc.Client.Batch a -> b) (Network.JsonRpc.Client.Batch a) b
instance Network.JsonRpc.Client.ComposeMultiParam f g h => Network.JsonRpc.Client.ComposeMultiParam f (a -> g) (a -> h)
instance (Network.JsonRpc.Client.ClientFunction ps r f, Data.Aeson.Types.ToJSON.ToJSON a) => Network.JsonRpc.Client.ClientFunction (a Network.JsonRpc.Client.::: ps) r (a -> f)


-- | Convenience function for creating server-side methods from
--   <a>Signature</a>s with the package <a>json-rpc-server</a>.
module Network.JsonRpc.ServerAdapter

-- | Creates a method from the given signature and function. The parameters
--   of the resulting method match the order and types of the parameters in
--   the signature and are all <a>Required</a>.
toServerMethod :: (ConvertParams ps1 ps2, MethodParams f ps2 m r) => Signature ps1 r -> f -> Method m

-- | Relationship between the parameters in a <a>Signature</a>
--   (<tt>ps1</tt>) and the parameters expected by <a>toMethod</a>
--   (<tt>ps2</tt>) for a given RPC method.
class ConvertParams ps1 ps2 | ps1 -> ps2, ps2 -> ps1
instance Network.JsonRpc.ServerAdapter.ConvertParams () ()
instance Network.JsonRpc.ServerAdapter.ConvertParams ps1 ps2 => Network.JsonRpc.ServerAdapter.ConvertParams (p Network.JsonRpc.Client.::: ps1) (p Network.JsonRpc.Types.:+: ps2)
