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


-- | Rest API library.
--   
--   Rest API library.
@package rest-core
@version 0.39

module Rest.ShowUrl


-- | Module facilitating informative inspection of datatypes.
module Rest.Info


-- | Error types that can be returned by handlers, as well as some
--   utilities for manipulating these errors.
module Rest.Error
mapE :: (Applicative m, Monad m) => (e -> e') -> ExceptT e m a -> ExceptT e' m a
infixl 8 `mapE`
orThrow :: MonadError e m => m (Maybe b) -> e -> m b
orThrowWith :: MonadError a m => m (Either e b) -> (e -> a) -> m b
eitherToStatus :: Either a b -> Status a b

-- | Wrap your custom error type in a <a>Reason</a>.
domainReason :: a -> Reason a

-- | Try two ExceptT computations left to right yielding the last error if
--   both fail. This prevents the need for a Semigroup or Monoid instance
--   for the error type, which is necessary if using (<a>!</a>) or
--   (<a>|</a>) respectively.
(>|<) :: (Monad m) => ExceptT f m a -> ExceptT e m a -> ExceptT e m a
infixl 3 >|<

module Rest.Dictionary.Types

-- | The <a>Format</a> datatype enumerates all input and output formats we
--   might recognize.
data Format
XmlFormat :: Format
JsonFormat :: Format
StringFormat :: Format
FileFormat :: Format
MultipartFormat :: Format
NoFormat :: Format

-- | The <a>Dict</a> datatype containing sub-dictionaries for translation
--   of identifiers (i), headers (h), parameters (p), inputs (i), outputs
--   (o), and errors (e). Inputs, outputs and errors can have multiple
--   associated dictionaries.
data Dict h_aiXx p_aiXy i_aiXz o_aiXA e_aiXB
headers :: forall cat h p i o e a. ArrowApply cat => Lens cat (Dict h p i o e -> Dict a p i o e) (Header h -> Header a)
params :: forall cat h p i o e a. ArrowApply cat => Lens cat (Dict h p i o e -> Dict h a i o e) (Param p -> Param a)
inputs :: forall cat h p i o e a. ArrowApply cat => Lens cat (Dict h p i o e -> Dict h p a o e) (Inputs i -> Inputs a)
outputs :: forall cat h p i o e a. ArrowApply cat => Lens cat (Dict h p i o e -> Dict h p i a e) (Outputs o -> Outputs a)
errors :: forall cat h p i o e a. ArrowApply cat => Lens cat (Dict h p i o e -> Dict h p i o a) (Errors e -> Errors a)

-- | The empty dictionary, recognizing no types.
empty :: Dict () () Nothing Nothing Nothing

-- | Type synonym for dictionary modification.
type Modifier h p i o e = Dict () () Nothing Nothing Nothing -> Dict h p i o e

-- | The explicit dictionary <a>Ident</a> describes how to translate a
--   resource identifier (originating from a request URI) to a Haskell
--   value. We allow plain <a>String</a> identifiers or all Haskell types
--   that have a <a>Read</a> instance.
data Ident id
[ReadId] :: (Info id, Read id) => Ident id
[StringId] :: Ident String

-- | The explicit dictionary <a>Header</a> describes how to translate HTTP
--   request headers to some Haskell value. The first field in the
--   <a>Header</a> constructor is a white list of headers we can recognize,
--   used in generic validation and for generating documentation. The
--   second field is a custom parser that can fail with a <a>DataError</a>
--   or can produce a some value. When explicitly not interested in the
--   headers we can use <a>NoHeader</a>.
data Header h
[NoHeader] :: Header ()
[Header] :: [String] -> ([Maybe String] -> Either DataError h) -> Header h
[TwoHeaders] :: Header h -> Header k -> Header (h, k)

-- | The explicit dictionary <a>Param</a> describes how to translate the
--   request parameters to some Haskell value. The first field in the
--   <a>Param</a> constructor is a white list of paramters we can
--   recognize, used in generic validation and for generating
--   documentation. The second field is a custom parser that can fail with
--   a <a>DataError</a> or can produce a some value. When explicitly not
--   interested in the parameters we can use <a>NoParam</a>.
data Param p
[NoParam] :: Param ()
[Param] :: [String] -> ([Maybe String] -> Either DataError p) -> Param p
[TwoParams] :: Param p -> Param q -> Param (p, q)

-- | The explicit dictionary <a>Input</a> describes how to translate the
--   request body into some Haskell value. We currently use a constructor
--   for every combination of input type to output type. For example, we
--   can use XML input in multiple ways, parsed, as plain/text or as raw
--   bytes, depending on the needs of the backend resource.
data Input i
[JsonI] :: (Typeable i, FromJSON i, JSONSchema i) => Input i
[ReadI] :: (Info i, Read i, Show i) => Input i
[StringI] :: Input String
[FileI] :: Input ByteString
[XmlI] :: (Typeable i, XmlPickler i) => Input i
[XmlTextI] :: Input Text
[RawJsonI] :: Input ByteString
[RawXmlI] :: Input ByteString
[RawJsonAndXmlI] :: Input (Either Json Xml)

-- | The explicit dictionary <a>Output</a> describes how to translate some
--   Haskell value to a response body. We currently use a constructor for
--   every combination of input type to output type.
data Output o
[FileO] :: Output (ByteString, String, Bool)
[RawJsonO] :: Output ByteString
[RawXmlO] :: Output ByteString
[JsonO] :: (Typeable o, ToJSON o, JSONSchema o) => Output o
[XmlO] :: (Typeable o, XmlPickler o) => Output o
[StringO] :: Output String
[RawJsonAndXmlO] :: Output ByteString
[MultipartO] :: Output [BodyPart]

-- | The explicit dictionary <a>Error</a> describes how to translate some
--   Haskell error value to a response body.
data Error e
[JsonE] :: (ToResponseCode e, Typeable e, ToJSON e, JSONSchema e) => Error e
[XmlE] :: (ToResponseCode e, Typeable e, XmlPickler e) => Error e

-- | Newtype around ByteStrings used in <a>RawJsonAndXmlI</a> to add some
--   protection from parsing the input incorrectly.
newtype Xml
Xml :: ByteString -> Xml
[unXml] :: Xml -> ByteString

-- | Newtype around ByteStrings used in <a>RawJsonAndXmlI</a> to add some
--   protection from parsing the input incorrectly.
newtype Json
Json :: ByteString -> Json
[unJson] :: Json -> ByteString
data Dicts f a
[None] :: Dicts f Nothing
[Dicts] :: [f a] -> Dicts f (Just a)

-- | <i>Deprecated: The modifier for this lens doesn't do anything when
--   Dicts is None. Use getDicts and modDicts instead.</i>
dicts :: forall a o f. o ~ FromMaybe o a => Dicts f a :-> [f o]

-- | Get the list of dictionaries. If there are none, you get a [o]. If
--   this is too polymorphic, try <a>getDicts_</a>.
getDicts :: o ~ FromMaybe o a => Dicts f a -> [f o]

-- | Get the list of dictionaries. If there are none, you get a [()].
--   Sometimes useful to constraint the types if the element type of the
--   list isn't clear from the context.
getDicts_ :: o ~ FromMaybe () a => Dicts f a -> [f o]
modDicts :: (FromMaybe o i ~ o) => ([f o] -> [f o]) -> Dicts f i -> Dicts f (Just o)
type Inputs i = Dicts Input i
type Outputs o = Dicts Output o
type Errors e = Dicts Error e

-- | Custom existential packing an error together with a Reason.
data SomeError
[SomeError] :: Errors e -> Reason (FromMaybe Void e) -> SomeError
instance GHC.Show.Show (Rest.Dictionary.Types.Dict h0 p0 i0 o0 e0)
instance GHC.Show.Show Rest.Dictionary.Types.Json
instance GHC.Classes.Eq Rest.Dictionary.Types.Json
instance GHC.Show.Show Rest.Dictionary.Types.Xml
instance GHC.Classes.Eq Rest.Dictionary.Types.Xml
instance GHC.Show.Show Rest.Dictionary.Types.Format
instance GHC.Enum.Bounded Rest.Dictionary.Types.Format
instance GHC.Enum.Enum Rest.Dictionary.Types.Format
instance GHC.Classes.Ord Rest.Dictionary.Types.Format
instance GHC.Classes.Eq Rest.Dictionary.Types.Format
instance GHC.Show.Show (Rest.Dictionary.Types.Ident id)
instance GHC.Show.Show (Rest.Dictionary.Types.Input i)
instance GHC.Classes.Eq (Rest.Dictionary.Types.Input i)
instance GHC.Classes.Ord (Rest.Dictionary.Types.Input i)
instance GHC.Show.Show (Rest.Dictionary.Types.Output o)
instance GHC.Classes.Eq (Rest.Dictionary.Types.Output o)
instance GHC.Classes.Ord (Rest.Dictionary.Types.Output o)
instance GHC.Show.Show (Rest.Dictionary.Types.Error e)
instance GHC.Classes.Eq (Rest.Dictionary.Types.Error e)
instance GHC.Classes.Ord (Rest.Dictionary.Types.Error e)
instance GHC.Show.Show (f (Rest.Dictionary.Types.FromMaybe Rest.Types.Void.Void a)) => GHC.Show.Show (Rest.Dictionary.Types.Dicts f a)
instance GHC.Show.Show (Rest.Dictionary.Types.Header h)
instance GHC.Show.Show (Rest.Dictionary.Types.Param p)


-- | Combinators for specifying the input/output dictionaries of a
--   <tt>Handler</tt>. The combinators can be combined using
--   <tt>(</tt><a>.</a><tt>)</tt>.
module Rest.Dictionary.Combinators

-- | Allow direct usage of as input as <a>String</a>.
stringI :: Dict h p Nothing o e -> Dict h p (Just String) o e

-- | Allow direct usage of as input as raw Xml <a>Text</a>.
xmlTextI :: Dict h p Nothing o e -> Dict h p (Just Text) o e

-- | Allow usage of input as file contents, represented as a
--   <a>ByteString</a>.
fileI :: Dict h p Nothing o e -> Dict h p (Just ByteString) o e

-- | The input can be read into some instance of <a>Read</a>. For
--   inspection reasons the type must also be an instance of both
--   <a>Info</a> and <a>Show</a>.
readI :: (Info i, Read i, Show i, FromMaybe i i' ~ i) => Dict h p i' o e -> Dict h p (Just i) o e

-- | The input can be read into some instance of <a>XmlPickler</a>.
xmlI :: (Typeable i, XmlPickler i, FromMaybe i i' ~ i) => Dict h p i' o e -> Dict h p (Just i) o e

-- | The input can be used as an XML <a>ByteString</a>.
rawXmlI :: Dict h p Nothing o e -> Dict h p (Just ByteString) o e

-- | The input can be read into some instance of <a>Json</a>.
jsonI :: (Typeable i, FromJSON i, JSONSchema i, FromMaybe i i' ~ i) => Dict h p i' o e -> Dict h p (Just i) o e

-- | The input can be used as a JSON <a>ByteString</a>.
rawJsonI :: Dict h p Nothing o e -> Dict h p (Just ByteString) o e

-- | The input can be used as a JSON or XML <a>ByteString</a>.
--   
--   An API client can send either format so the handler needs to handle
--   both.
rawJsonAndXmlI :: Dict h p Nothing o e -> Dict h p (Just (Either Json Xml)) o e

-- | Allow output as plain String.
stringO :: Dict h p i Nothing e -> Dict h p i (Just String) e

-- | Allow file output using a combination of the raw data, the file name,
--   and an attachment flag (causing the file to be downloaded by browsers
--   instead of shown). The mime type will be determined from the file
--   extension by your web server library, or "application/octet-stream"
--   with an unknown extension.
fileO :: Dict h p i Nothing e -> Dict h p i (Just (ByteString, String, Bool)) e

-- | Allow output as XML using the <a>XmlPickler</a> type class.
xmlO :: (Typeable o, XmlPickler o, FromMaybe o o' ~ o) => Dict h p i o' e -> Dict h p i (Just o) e

-- | Allow output as raw XML represented as a <a>ByteString</a>.
rawXmlO :: Dict h p i Nothing e -> Dict h p i (Just ByteString) e

-- | Allow output as JSON using the <a>Json</a> type class.
jsonO :: (Typeable o, ToJSON o, JSONSchema o, FromMaybe o o' ~ o) => Dict h p i o' e -> Dict h p i (Just o) e

-- | Allow output as raw JSON represented as a <a>ByteString</a>.
rawJsonO :: Dict h p i Nothing e -> Dict h p i (Just ByteString) e

-- | Allow output as raw JSON and XML represented as <a>ByteString</a>s.
--   Both values are needed since the accept header determines which one to
--   send.
rawJsonAndXmlO :: Dict h p i Nothing e -> Dict h p i (Just ByteString) e

-- | Allow output as multipart. Writes out the ByteStrings separated by
--   boundaries, with content type 'multipart/mixed'.
multipartO :: Dict h p i Nothing e -> Dict h p i (Just [BodyPart]) e

-- | Allow error output as JSON using the <a>Json</a> type class.
jsonE :: (ToResponseCode e, Typeable e, ToJSON e, JSONSchema e, FromMaybe e e' ~ e) => Dict h p i o e' -> Dict h p i o (Just e)

-- | Allow error output as XML using the <a>XmlPickler</a> type class.
xmlE :: (ToResponseCode e, Typeable e, XmlPickler e, FromMaybe e e' ~ e) => Dict h p i o e' -> Dict h p i o (Just e)

-- | The input can be read into some instance of both <a>Json</a> and
--   <a>XmlPickler</a>.
xmlJsonI :: (Typeable i, FromJSON i, JSONSchema i, XmlPickler i, FromMaybe i i' ~ i) => Dict h p i' o e -> Dict h p (Just i) o e

-- | Allow output as JSON using the <a>Json</a> type class and allow output
--   as XML using the <a>XmlPickler</a> type class.
xmlJsonO :: (Typeable o, ToJSON o, JSONSchema o, XmlPickler o, FromMaybe o o' ~ o) => Dict h p i o' e -> Dict h p i (Just o) e

-- | Allow error output as JSON using the <a>Json</a> type class and allow
--   output as XML using the <a>XmlPickler</a> type class.
xmlJsonE :: (ToResponseCode e, Typeable e, ToJSON e, JSONSchema e, XmlPickler e, FromMaybe e e' ~ e) => Dict h p i o e' -> Dict h p i o (Just e)

-- | The input can be read into some instance of both <a>Json</a> and
--   <a>XmlPickler</a> and allow output as JSON using the <a>Json</a> type
--   class and allow output as XML using the <a>XmlPickler</a> type class.
xmlJson :: (Typeable i, FromJSON i, JSONSchema i, XmlPickler i, Typeable o, ToJSON o, JSONSchema o, XmlPickler o, FromMaybe i i' ~ i, FromMaybe o o' ~ o) => Dict h p i' o' e -> Dict h p (Just i) (Just o) e

-- | Set custom sub-dictionary for recognizing headers.
mkHeader :: Header h -> Dict x p i o e -> Dict h p i o e

-- | Add custom sub-dictionary for recognizing headers.
addHeader :: Header h -> Dict h' p i o e -> Dict (h, h') p i o e

-- | Set custom sub-dictionary for recognizing parameters.
mkPar :: Param p -> Dict h x i o e -> Dict h p i o e

-- | Add custom sub-dictionary for recognizing parameters.
addPar :: Param p -> Dict h p' i o e -> Dict h (p, p') i o e

-- | Open up input type for extension with custom dictionaries.

-- | <i>Deprecated: This can be safely removed, it is now just the
--   identity.</i>
someI :: Dict h p i o e -> Dict h p i o e

-- | Open up output type for extension with custom dictionaries.

-- | <i>Deprecated: This can be safely removed, it is now just the
--   identity.</i>
someO :: Dict h p i o e -> Dict h p i o e

-- | Open up error type for extension with custom dictionaries.

-- | <i>Deprecated: This can be safely removed, it is now just the
--   identity.</i>
someE :: Dict h p i o e -> Dict h p i o e


-- | A dictionary (<a>Dict</a>) describes how to convert Haskell values to
--   and from a web representation. Rest resources internally use plain
--   Haskell datatypes, while communication to the outside world mostly
--   happens using XML, JSON, plain text, query parameters, etc. The
--   <a>Dict</a> datatype describes how to convert resource
--   <i>indentifiers, input, request parameters, request headers, output,
--   and errors</i> to and from a Haskell representation.
--   
--   The <a>Dict</a> datatype and most functions working on it take a type
--   parameters for every aspect of its communication, which can grow
--   quickly. This module and most code that depend on it uses the implicit
--   convention of using the type variable <a>id</a> for the resource
--   identifier, the <tt>h</tt> for the request headers, the <tt>p</tt> for
--   the request parameters, the <tt>i</tt> for the request body, the
--   <tt>o</tt> for the response body, and the <tt>e</tt> for a possible
--   error.
module Rest.Dictionary


-- | Handlers for endpoints in a <tt>Resource</tt>.
module Rest.Handler

-- | Create a handler for a single resource. Takes the entire environmend
--   as input.
mkHandler :: (Monad m, i ~ FromMaybe () i', o ~ FromMaybe () o', e ~ FromMaybe Void e') => Modifier h p i' o' e' -> (Env h p i -> ExceptT (Reason e) m o) -> Handler m

-- | Create a handler for a single resource. Takes only the body
--   information as input.
mkInputHandler :: (Monad m, i ~ FromMaybe () i', o ~ FromMaybe () o', e ~ FromMaybe Void e') => Modifier () () i' o' e' -> (i -> ExceptT (Reason e) m o) -> Handler m

-- | Create a handler for a single resource. Doesn't take any input.
mkConstHandler :: (Monad m, o ~ FromMaybe () o', e ~ FromMaybe Void e') => Modifier () () Nothing o' e' -> ExceptT (Reason e) m o -> Handler m

-- | Create a handler for a single resource. Take body information and the
--   resource identifier as input. The monad <tt>m</tt> must be a
--   <a>Reader</a>-like type containing the idenfier.
mkIdHandler :: (MonadReader id m, i ~ FromMaybe () i', o ~ FromMaybe () o', e ~ FromMaybe Void e') => Modifier h p i' o' e' -> (i -> id -> ExceptT (Reason e) m o) -> Handler m

-- | Smart constructor for creating a list handler. Restricts the type of
--   the <a>Input</a> dictionary to <a>None</a>
mkListing :: (Monad m, o ~ FromMaybe () o', e ~ FromMaybe Void e') => Modifier h p Nothing o' e' -> (Range -> ExceptT (Reason e) m [o]) -> ListHandler m

-- | Create a list handler that accepts ordering information. Restricts the
--   type of the <a>Input</a> dictionary to <a>None</a>
mkOrderedListing :: (Monad m, o ~ FromMaybe () o', e ~ FromMaybe Void e') => Modifier h p Nothing o' e' -> ((Range, Maybe String, Maybe String) -> ExceptT (Reason e) m [o]) -> ListHandler m

-- | Data type for representing the requested range in list handlers.
data Range :: *
Range :: Int -> Int -> Range
[offset] :: Range -> Int
[count] :: Range -> Int

-- | Dictionary for taking <a>Range</a> parameters. Allows two query
--   parameters, <tt>offset</tt> and <tt>count</tt>. If not passed, the
--   defaults are 0 and 100. The maximum range that can be passed is 1000.
range :: Param Range

-- | Dictionary for taking ordering information. In addition to the
--   parameters accepted by <a>range</a>, this accepts <tt>order</tt> and
--   <tt>direction</tt>.
orderedRange :: Param (Range, Maybe String, Maybe String)

-- | An environment of inputs passed to a handler. Contains information
--   from the <a>header</a>s, the <a>param</a>eters and the body
--   <a>input</a>.
data Env h p i
Env :: h -> p -> i -> Env h p i
[header] :: Env h p i -> h
[param] :: Env h p i -> p
[input] :: Env h p i -> i

-- | A handler for some endpoint. The input and output types are specified
--   by the <a>dictionary</a>, which can be created using the combinators
--   from <a>Rest.Dictionary.Combinators</a>. The inputs (headers,
--   parameters and body) are passed as an <a>Env</a> to the
--   <a>handler</a>. This handler runs in monad <tt>m</tt>, combined with
--   the ability to throw errors. The result is either the output value, or
--   a list of them for list handlers. If the <a>secure</a> flag is set,
--   this suggests to clients that the resource should only be served over
--   https. It has no effect when running the API.
data GenHandler m f
[GenHandler] :: (i ~ FromMaybe () i', o ~ FromMaybe () o', e ~ FromMaybe Void e') => {dictionary :: Dict h p i' o' e', handler :: Env h p i -> ExceptT (Reason e) m (Apply f o), secure :: Bool} -> GenHandler m f

-- | Construct a <a>GenHandler</a> using a <a>Modifier</a> instead of a
--   <a>Dict</a>. The <a>secure</a> flag will be <a>False</a>.
mkGenHandler :: (Monad m, i ~ FromMaybe () i', o ~ FromMaybe () o', e ~ FromMaybe Void e') => Modifier h p i' o' e' -> (Env h p i -> ExceptT (Reason e) m (Apply f o)) -> GenHandler m f

-- | Apply a Functor <tt>f</tt> to a type <tt>a</tt>. In general will
--   result in <tt>f a</tt>, except if <tt>f</tt> is <a>Identity</a>, in
--   which case it will result in <tt>a</tt>. This prevents a lot of
--   <a>Identity</a> wrapping/unwrapping.

-- | A <a>Handler</a> returning a single item.
type Handler m = GenHandler m Identity

-- | A <a>Handler</a> returning a list of items.
type ListHandler m = GenHandler m []

-- | Set <a>secure</a> to <a>True</a>.
secureHandler :: Handler m -> Handler m


-- | This module contains data types and combinators for defining a
--   <a>Schema</a> for your <tt>Resource</tt>. A <a>Schema</a> has three
--   type parameters, specifying the identifiers for a single resource, a
--   listing, and a top-level (static) action. After routing, these
--   identifiers will be passed to the <tt>Handler</tt>.
module Rest.Schema

-- | A schema with a top level listing.
withListing :: mid -> Step sid mid aid -> Schema sid mid aid

-- | A schema with no top level listing.
noListing :: Step sid mid aid -> Schema sid mid aid

-- | A schema with a singleton at the top level.
singleton :: sid -> Step sid mid aid -> Schema sid mid aid

-- | A list of named endpoints.
named :: [(String, Endpoint sid mid aid)] -> Step sid mid aid

-- | A top level action endpoint for this resource.
static :: aid -> Endpoint sid mid aid

-- | A singleton resource endpoint.
single :: sid -> Endpoint sid mid aid

-- | A single resource endpoint with a string identifier.
singleBy :: (String -> sid) -> Endpoint sid mid aid

-- | A single resource endpoint with an identifier that can be read.
singleRead :: (Show a, Read a, Info a) => (a -> sid) -> Endpoint sid mid aid

-- | A listing endpoint.
listing :: mid -> Endpoint sid mid aid

-- | A listing endpoint with a string identifier.
listingBy :: (String -> mid) -> Endpoint sid mid aid

-- | A listing with an identifier that can be read.
listingRead :: (Show a, Read a, Info a) => (a -> mid) -> Endpoint sid mid aid

-- | An unnamed single resource with a string identifier.
unnamedSingle :: (String -> sid) -> Step sid mid aid

-- | An unnamed single resource with an identifier that can be read.
unnamedSingleRead :: (Show a, Read a, Info a) => (a -> sid) -> Step sid mid aid

-- | An unnamed listing with a string identifier.
unnamedListing :: (String -> mid) -> Step sid mid aid

-- | An unnamed listing with an identifier that can be read.
unnamedListingRead :: (Show a, Read a, Info a) => (a -> mid) -> Step sid mid aid

-- | A <a>Schema</a> describes how (part of the) route to a resource looks,
--   and returns an identifier for a single resource (<tt>sid</tt>), many
--   resources (<tt>mid</tt>) or a static action (<tt>aid</tt>). The first
--   argument specifies the top level resource (no path segments). The
--   second specifies a what happens at the first step in the path.
data Schema sid mid aid
Schema :: (Maybe (Cardinality sid mid)) -> (Step sid mid aid) -> Schema sid mid aid

-- | A step in the routing of a resource. A part of the uri either
--   identifies a <a>Named</a> resource, or an <a>Unnamed</a> resource.
--   Named resources can be static actions (<a>Left</a>) or one or many
--   singletons or by's.
data Step sid mid aid
Named :: [(String, Endpoint sid mid aid)] -> Step sid mid aid
Unnamed :: (Cardinality (Id sid) (Id mid)) -> Step sid mid aid

-- | Specifies if we're identifying a single resource, or many (a listing).
data Cardinality s m
Single :: s -> Cardinality s m
Many :: m -> Cardinality s m

-- | A <a>Getter</a> can either be a <a>Singleton</a> (there is only one)
--   or it can be identified <a>By</a> an <a>Id</a>entifier.
data Getter id
Singleton :: id -> Getter id
By :: (Id id) -> Getter id

-- | An identification of an item in a resource. It contains a dictionary
--   describing how to identify the resource, and a function for this
--   identification type to an <tt>id</tt>.
data Id id
Id :: (Ident a) -> (a -> id) -> Id id

-- | A named endpoint: an static action, a single item of many items.
type Endpoint sid mid aid = Either aid (Cardinality (Getter sid) (Getter mid))


-- | A <a>Resource</a> type for representing a REST resource, as well as
--   smart constructors for empty resources which can then be filled in
--   using record updates.
module Rest.Resource

-- | The <a>Resource</a> data type represents a single resource in a REST
--   API. Handlers run in a monad <tt>m</tt>, while things below this
--   resource run in <tt>s</tt>. The identifiers <tt>sid</tt>, <tt>mid</tt>
--   and <tt>aid</tt> identify a single item, a listing and an action.
data Resource m s sid mid aid
[Resource] :: (Applicative m, Monad m, Applicative s, Monad s) => {name :: String  The name for this resource, used as a path segment in routing., description :: String  A description of the resource, used for documentation., schema :: Schema sid mid aid  The schema for routing and identification., private :: Bool  Private resources are not documented, but they are exposed., enter :: forall b. sid -> s b -> m b  How to run a subresource given an id., list :: mid -> ListHandler m  List handler, both toplevel and deeper (search)., statics :: aid -> Handler m  Static actions, e.g. signin., get :: Maybe (Handler s)  Get a single resource identified by id., update :: Maybe (Handler s)  Update a single resource identified by id., remove :: Maybe (Handler s)  Delete a single resource identified by id., create :: Maybe (Handler m)  Create a single resource, generating a new id., actions :: [(String, Handler s)]  Actions performed on a single resource., selects :: [(String, Handler s)]  Properties of a single resource.} -> Resource m s sid mid aid

-- | Create an empty resource given an <a>enter</a> function. It has no
--   name, so if you wish to route to this resource, you should set one.
mkResource :: (Applicative m, Monad m, Applicative s, Monad s) => (forall b. sid -> s b -> m b) -> Resource m s sid Void Void

-- | Make a resource that doesn't add any information for subresources
--   (i.e. <a>enter</a> is set to <a>id</a>).
mkResourceId :: (Applicative m, Monad m) => Resource m m sid Void Void

-- | Make a resource that provides the single resource identifier to its
--   subresources.
mkResourceReader :: (Applicative m, Monad m) => Resource m (ReaderT sid m) sid Void Void

-- | Make a resource that provides the single resource identifier to its
--   subresources, by giving a conversion function to a <a>ReaderT</a>. If
--   <tt>s</tt> is a newtype around <a>ReaderT</a>, for example, the
--   function should unwrap the newtype.
mkResourceReaderWith :: (Applicative m, Monad m, Applicative s, Monad s) => (forall b. s b -> ReaderT sid m b) -> Resource m s sid Void Void

module Rest.Container
listI :: Inputs i -> Maybe (Inputs (Just (List (FromMaybe () i))))
listO :: Outputs o -> Maybe (Outputs (Just (List (FromMaybe () o))))
mappingI :: forall i i'. i ~ FromMaybe () i' => Inputs i' -> Maybe (Inputs (Just (StringHashMap String i)))
mappingO :: forall o o'. o ~ FromMaybe () o' => Outputs o' -> Maybe (Outputs (Just (StringHashMap String o)))
statusO :: (e ~ FromMaybe Void e', o ~ FromMaybe () o') => Errors e' -> Outputs o' -> Maybe (Outputs (Just (Status e o)))
reasonE :: e ~ FromMaybe Void e' => Errors e' -> Errors (Just (Reason e))
defaultE :: Errors (Just Reason_)


-- | This module allows you to combine <a>Resource</a>s into an <a>Api</a>.
--   This can then be served using 'rest-happstack' or 'rest-snap', or used
--   to generate clients or documentation using 'rest-gen'.
module Rest.Api

-- | An API can be versioned or unversioned. A versioned API is a set of
--   versioned routers. An unversioned API is just a single router.
data Api m
[Unversioned] :: Some1 (Router m) -> Api m
[Versioned] :: VersionSet m -> Api m

-- | A version set is a list of versioned routers.
type VersionSet m = [(Version, Some1 (Router m))]

-- | A <a>Router</a> is a <a>Resource</a> and a list of subresources.
data Router m s
[Embed] :: Resource m s sid mid aid -> [Some1 (Router s)] -> Router m s

-- | An existential where the second argument has kind <tt>(* -&gt;
--   *)</tt>.
data Some1 f
[Some1] :: f (a :: * -> *) -> Some1 f

-- | Convenience constructor constructing a route without any subresource.
route :: Monad s => Resource m s sid mid aid -> Router m s

-- | Add the second router as a subresource to the first.
compose :: Router m s -> Router s t -> Router m s

-- | Operators with the right fixities to allow you to define routes
--   without using parentheses. Start with the shortest near the root.
(-/) :: Router m s -> Router s t -> Router m s
infixl 4 -/

-- | Operators with the right fixities to allow you to define routes
--   without using parentheses. Start with the shortest near the root.
(--/) :: Router m s -> Router s t -> Router m s
infixl 5 --/

-- | Operators with the right fixities to allow you to define routes
--   without using parentheses. Start with the shortest near the root.
(---/) :: Router m s -> Router s t -> Router m s
infixl 6 ---/

-- | Operators with the right fixities to allow you to define routes
--   without using parentheses. Start with the shortest near the root.
(----/) :: Router m s -> Router s t -> Router m s
infixl 7 ----/

-- | Operators with the right fixities to allow you to define routes
--   without using parentheses. Start with the shortest near the root.
(-----/) :: Router m s -> Router s t -> Router m s
infixl 8 -----/

-- | Operators with the right fixities to allow you to define routes
--   without using parentheses. Start with the shortest near the root.
(------/) :: Router m s -> Router s t -> Router m s
infixl 9 ------/

-- | An empty router to use as the root for your API.
root :: (Applicative m, Monad m) => Router m m

-- | An API version has three parts. The first is two are used for API
--   breaking changes, the last for non-API breaking changes.
data Version
Version :: Int -> Int -> Maybe Int -> Version
[full] :: Version -> Int
[major] :: Version -> Int
[minor] :: Version -> Maybe Int

-- | Smart constructor for <a>Version</a>.
mkVersion :: Int -> Int -> Int -> Version

-- | Get the latest version of an API.
latest :: VersionSet m -> Maybe (Version, Some1 (Router m))

-- | Parse a <a>String</a> as a <a>Version</a>. The string should contain
--   two or three numbers separated by dots, e.g. <tt>1.12.3</tt>.
parseVersion :: String -> Maybe Version

-- | Look up a version in an API. The string can either be a valid version
--   according to <a>parseVersion</a>, or "latest".
lookupVersion :: String -> VersionSet m -> Maybe (Some1 (Router m))

-- | Look up a version in the API.
lookupVersion' :: Version -> VersionSet m -> Maybe (Some1 (Router m))

-- | Given a version string, an API and a fallback, do the following:
--   
--   <ul>
--   <li>Parse the version number or "latest".</li>
--   <li>Look up this version.</li>
--   <li>If ok, run the given function on it.</li>
--   <li>If not parsed or found, return the fallback.</li>
--   </ul>
withVersion :: String -> Api m -> r -> (Version -> Some1 (Router m) -> r) -> r
instance GHC.Classes.Ord Rest.Api.Version
instance GHC.Classes.Eq Rest.Api.Version
instance GHC.Show.Show Rest.Api.Version

module Rest.Driver.Types
type Run m n = forall a. m a -> n a
data RunnableHandler n
RunnableHandler :: (Run m n) -> (Handler m) -> RunnableHandler n
data Config m
Config :: (forall s. Config m -> Router m s -> [Resource] -> ExceptT Reason_ m [BodyPart]) -> Config m
[runMultiResources] :: Config m -> forall s. Config m -> Router m s -> [Resource] -> ExceptT Reason_ m [BodyPart]
mapHandler :: Run m n -> RunnableHandler m -> RunnableHandler n

module Rest.Driver.Perform
class (Applicative m, Monad m) => Rest m
getHeader :: Rest m => String -> m (Maybe String)
getParameter :: Rest m => String -> m (Maybe String)
getBody :: Rest m => m ByteString
getMethod :: Rest m => m (Maybe Method)
getPaths :: Rest m => m [String]
lookupMimeType :: Rest m => String -> m (Maybe String)
setHeader :: Rest m => String -> String -> m ()
setResponseCode :: Rest m => Int -> m ()
failureWriter :: Rest m => Errors e -> Reason (FromMaybe Void e) -> m ByteString
writeResponse :: Rest m => RunnableHandler m -> m ByteString
accept :: Maybe String -> Maybe String -> Maybe String -> [Format]
instance Rest.Driver.Perform.Rest m => Rest.Driver.Perform.Rest (Control.Monad.Trans.Cont.ContT r m)
instance Rest.Driver.Perform.Rest m => Rest.Driver.Perform.Rest (Control.Monad.Trans.Except.ExceptT e m)
instance (GHC.Base.Monoid w, Rest.Driver.Perform.Rest m) => Rest.Driver.Perform.Rest (Control.Monad.Trans.RWS.Lazy.RWST r w s m)
instance Rest.Driver.Perform.Rest m => Rest.Driver.Perform.Rest (Control.Monad.Trans.Reader.ReaderT r m)
instance Rest.Driver.Perform.Rest m => Rest.Driver.Perform.Rest (Control.Monad.Trans.State.Lazy.StateT s m)
instance (GHC.Base.Monoid w, Rest.Driver.Perform.Rest m) => Rest.Driver.Perform.Rest (Control.Monad.Trans.Writer.Lazy.WriterT w m)
instance Rest.Driver.Perform.Rest m => Rest.Driver.Perform.Rest (Control.Monad.Trans.Identity.IdentityT m)
instance Rest.Driver.Perform.Rest m => Rest.Driver.Perform.Rest (Control.Monad.Trans.Maybe.MaybeT m)

module Rest.Driver.RestM
data RestM m a
runRestM :: RestInput -> RestM m a -> m (a, RestOutput)
runRestM_ :: Functor m => RestInput -> RestM m a -> m a
data RestInput
RestInput :: HashMap (CI String) String -> HashMap String String -> ByteString -> Maybe Method -> [String] -> HashMap String String -> RestInput
[headers] :: RestInput -> HashMap (CI String) String
[parameters] :: RestInput -> HashMap String String
[body] :: RestInput -> ByteString
[method] :: RestInput -> Maybe Method
[paths] :: RestInput -> [String]
[mimeTypes] :: RestInput -> HashMap String String
emptyInput :: RestInput
data RestOutput
RestOutput :: HashMap String String -> Maybe Int -> RestOutput
[headersSet] :: RestOutput -> HashMap String String
[responseCode] :: RestOutput -> Maybe Int
instance GHC.Base.Monad m => GHC.Base.Monad (Rest.Driver.RestM.RestM m)
instance GHC.Base.Applicative m => GHC.Base.Applicative (Rest.Driver.RestM.RestM m)
instance GHC.Base.Functor m => GHC.Base.Functor (Rest.Driver.RestM.RestM m)
instance GHC.Show.Show Rest.Driver.RestM.RestOutput
instance GHC.Base.Monoid Rest.Driver.RestM.RestOutput
instance Control.Monad.Trans.Class.MonadTrans Rest.Driver.RestM.RestM
instance (GHC.Base.Functor m, GHC.Base.Applicative m, GHC.Base.Monad m) => Rest.Driver.Perform.Rest (Rest.Driver.RestM.RestM m)

module Rest.Driver.Routing.Internal
type UriParts = [String]
apiError :: (MonadError (Reason e) m) => Reason e -> m a
data RouterData m
RouterData :: Method -> Config m -> RouterData m
[method] :: RouterData m -> Method
[config] :: RouterData m -> Config m
newtype Router m a
Router :: ReaderT (RouterData m) (StateT UriParts (ExceptT Reason_ Identity)) a -> Router m a
[unRouter] :: Router m a -> ReaderT (RouterData m) (StateT UriParts (ExceptT Reason_ Identity)) a
runRouter :: Config m -> Method -> UriParts -> Router m (RunnableHandler m) -> Either Reason_ (RunnableHandler m)
route :: (Applicative m, Monad m) => Maybe Method -> UriParts -> Api m -> Either Reason_ (RunnableHandler m)
routeWith :: Config m -> Maybe Method -> UriParts -> Api m -> Either Reason_ (RunnableHandler m)
routeRoot :: Router m s -> Router m (RunnableHandler m)
routeMultiGet :: Router m s -> MaybeT (Router m) (RunnableHandler m)
routeRouter :: Router m s -> Router n (RunnableHandler m)
routeToplevel :: Resource m s sid mid aid -> [Some1 (Router s)] -> Maybe (Cardinality sid mid) -> MaybeT (Router n) (RunnableHandler m)
routeCreate :: Resource m s sid mid aid -> MaybeT (Router n) (RunnableHandler m)
routeStep :: Resource m s sid mid aid -> [Some1 (Router s)] -> Step sid mid aid -> Router n (RunnableHandler m)
routeNamed :: Resource m s sid mid aid -> [Some1 (Router s)] -> Endpoint sid mid aid -> Router n (RunnableHandler m)
routeUnnamed :: Resource m s sid mid aid -> [Some1 (Router s)] -> Cardinality (Id sid) (Id mid) -> Router n (RunnableHandler m)
routeGetter :: Getter sid -> Resource m s sid mid aid -> [Some1 (Router s)] -> Router n (RunnableHandler m)
multi :: Resource m s sid mid aid -> Id sid -> Router n (RunnableHandler m)
routeListGetter :: Monad m => Getter mid -> (mid -> ListHandler m) -> Router n (RunnableHandler m)
withSubresource :: sid -> Resource m s sid mid aid -> [Some1 (Router s)] -> Router n (RunnableHandler m)
routeSingle :: sid -> Resource m s sid mid aid -> Router n (RunnableHandler m)
routeName :: String -> Router n ()
routeListHandler :: Monad m => ListHandler m -> Router n (RunnableHandler m)
lookupRouter :: String -> [Some1 (Router s)] -> Maybe (Some1 (Router s))
parseIdent :: MonadError (Reason e) m => Id id -> String -> m id
splitUriString :: String -> UriParts
popSegment :: Router n String
withSegment :: Router n a -> (String -> Router n a) -> Router n a
noRestPath :: Router n ()
guardNullPath :: (MonadPlus m, MonadState UriParts m) => m ()
hasMethod :: Method -> Router n ()
guardMethod :: (MonadPlus m, MonadReader (RouterData c) m) => Method -> m ()
mkListHandler :: Monad m => ListHandler m -> Maybe (Handler m)
mkListAction :: Monad m => (Env h p i -> ExceptT (Reason e) m [a]) -> Env h (Range, p) i -> ExceptT (Reason e) m (List a)
mkMultiHandler :: Monad m => Id id -> (id -> Run s m) -> Handler s -> Maybe (Handler m)
mkMultiGetHandler :: forall m s. (Applicative m, Monad m) => Config m -> Router m s -> Handler m
defaultRunMultiResources :: (Applicative m, Monad m) => Config m -> Router m s -> [Resource] -> ExceptT Reason_ m [BodyPart]
defaultConfig :: (Applicative m, Monad m) => Config m
runResource :: (Applicative m, Monad m) => Config m -> Router m s -> Resource -> m BodyPart
routeResource :: Config m -> Router m s -> Resource -> Either Reason_ (RunnableHandler m)
toRestInput :: Resource -> RestInput
mkHeaders :: HashMap String d -> [(HeaderName, d)]
mkBodyPart :: ByteString -> RestOutput -> BodyPart
fromMaybeT :: Monad m => m a -> MaybeT m a -> m a
instance Control.Monad.Error.Class.MonadError Rest.Types.Error.Reason_ (Rest.Driver.Routing.Internal.Router m)
instance Control.Monad.State.Class.MonadState Rest.Driver.Routing.Internal.UriParts (Rest.Driver.Routing.Internal.Router m)
instance Control.Monad.Reader.Class.MonadReader (Rest.Driver.Routing.Internal.RouterData m) (Rest.Driver.Routing.Internal.Router m)
instance GHC.Base.Monad (Rest.Driver.Routing.Internal.Router m)
instance GHC.Base.Applicative (Rest.Driver.Routing.Internal.Router m)
instance GHC.Base.Functor (Rest.Driver.Routing.Internal.Router m)

module Rest.Driver.Routing
route :: (Applicative m, Monad m) => Maybe Method -> UriParts -> Api m -> Either Reason_ (RunnableHandler m)
mkListHandler :: Monad m => ListHandler m -> Maybe (Handler m)
mkMultiHandler :: Monad m => Id id -> (id -> Run s m) -> Handler s -> Maybe (Handler m)
type UriParts = [String]
splitUriString :: String -> UriParts

module Rest.Run
apiToHandler :: (Applicative m, Monad m) => Rest m => Api m -> m ByteString
apiToHandler' :: (Applicative m, Monad m) => Rest n => Run m n -> Api m -> n ByteString
apiToHandlerWith :: Config m -> Rest n => Run m n -> Api m -> n ByteString
data Config m
Config :: (forall s. Config m -> Router m s -> [Resource] -> ExceptT Reason_ m [BodyPart]) -> Config m
[runMultiResources] :: Config m -> forall s. Config m -> Router m s -> [Resource] -> ExceptT Reason_ m [BodyPart]


-- | These modules allow you to define a single REST resource. Then, you
--   can combine multiple resources into an API using <a>Rest.Api</a>, and
--   run them using 'rest-happstack' or 'rest-snap', or generate client
--   code or documentation using 'rest-gen'.
module Rest