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


-- | Dependently typed API framework
--   
--   Types and kinds for describing APIs.
--   
--   This package defines the kind <a>Serv.Api.Api</a> which classifies
--   types which statically describe an API. Define your
--   <a>Serv.Api.Api</a>-kinded types and then write/derive compliant
--   servers, clients, and documentation all statically guaranteed to
--   match.
--   
--   Import <a>Serv.Api.Prelude</a> for the smoothest experience defining
--   these types.
--   
--   See the README for more details.
@package serv
@version 0.2.0.0


-- | Types, but really kinds, which represent the structure of an API.
module Serv.Api

-- | <a>Api</a>s describe collections of HTTP endpoints accessible at
--   various segmented <a>Path</a>s.
data Api star

-- | An <a>Endpoint</a> describes a root API which responds only to
--   requests with empty paths. It matches on HTTP <a>Method</a>s which
--   demand <a>Verb</a>s, <a>HeaderName</a>s, and <a>Body</a>s.
--   
--   <a>Endpoint</a> differs from <a>OneOf</a> in that it can only choose
--   between possible methods and automatically provides an <a>OPTIONS</a>
--   response.
Endpoint :: star -> [Handler star] -> Api star

-- | <a>Api</a>s consist of many sub-<a>Api</a>s which are attempted
--   sequentially. <tt><a>OneOf</a> choices</tt> expresses this sequential
--   search along a set of sub-<a>Api</a> <tt>choices</tt>.
OneOf :: [Api star] -> Api star

-- | <a>Abstract</a> enables the use of standard <a>Application</a>s within
--   an <a>Api</a>. These cannot be examined further through type analysis,
--   but they are a common use case.
Abstract :: Api star

-- | Qualify an API using a series of <a>Path</a> "segments"
(:>) :: Path star -> Api star -> Api star

-- | <a>Generalized</a> path segments match against data in the request.
data Path star

-- | Matches if the request has a non-empty remaining path and the next
--   segment matches exactly
Const :: Symbol -> Path star

-- | Matches if the request has a given header and its value matches
--   exactly (!)
HeaderAs :: HeaderName -> Symbol -> Path star

-- | Matches if the request has a non-empty remaining path. The next
--   segment is "captured", provided to the server implementation.
Seg :: Symbol -> star -> Path star

-- | Always matches, "capturing" the value of a header, or <a>Nothing</a>
--   if the header fails to exist.
Header :: HeaderName -> star -> Path star

-- | Always matches, "captures" the remaining path segments as a list of
--   text values. May just capture the empty list.
Wildcard :: Path star

-- | A <a>Handler</a> is a single HTTP verb response handled at a given
--   <a>Endpoint</a>. In order to complete a <tt>Handler'</tt>s operation
--   it may demand data from the request such as headers or the request
--   body.
data Handler star

-- | A "core" <a>Handler</a> definition which describes the <a>Verb</a> it
--   responds to along with a set of response headers and a chance to
--   attach a response <a>Body</a>.
Method :: Verb -> [(Status, Output star)] -> Handler star

-- | Augment a <a>Handler</a> to include requirements of a request body.
CaptureBody :: [star] -> star -> (Handler star) -> Handler star

-- | Augment a <a>Handler</a> to include requirements of request header
--   values.
CaptureHeaders :: [(HeaderName, star)] -> (Handler star) -> Handler star

-- | Augment a <a>Handler</a> to include requirements of the request query
--   string
CaptureQuery :: [(Symbol, star)] -> (Handler star) -> Handler star

-- | Describes an output from an API under a given status.
data Output star
Respond :: [(HeaderName, star)] -> (Body star) -> Output star

-- | <a>Handler</a> responses may opt to include a response body or not.
data Body star

-- | Return a response body by specifying a set of content-types and a
--   value to derive the body from.
HasBody :: [star] -> star -> Body star

-- | A response with an empty body
Empty :: Body star

-- | Extra syntax-sugar for representing type-level pairs.
type (:::) a b = '(a, b)

-- | The singleton kind-indexed data family.
type Endpoint ann ms = Endpoint ann ms
type OneOf apis = OneOf apis
type Abstract = Abstract
type (:>) a b = a :> b
type Const sym = Const sym
type HeaderAs ty sym = HeaderAs ty sym
type Seg sym ty = Seg sym ty
type Header name ty = Header name ty
type Wildcard = Wildcard
type Method verb responses = Method verb responses
type CaptureBody cTypes ty method = CaptureBody cTypes ty method
type CaptureHeaders hdrs method = CaptureHeaders hdrs method
type CaptureQuery query method = CaptureQuery query method
type Respond hdrs body = Respond hdrs body
type HasBody ctypes ty = HasBody ctypes ty
type Empty = Empty
instance (Data.Singletons.SingI ts, Data.Singletons.SingI a) => Data.Singletons.SingI ('Serv.Api.HasBody ts a)
instance Data.Singletons.SingI 'Serv.Api.Empty
instance (Data.Singletons.SingI ts, Data.Singletons.SingI b) => Data.Singletons.SingI ('Serv.Api.Respond ts b)
instance (Data.Singletons.SingI v, Data.Singletons.SingI ts) => Data.Singletons.SingI ('Serv.Api.Method v ts)
instance (Data.Singletons.SingI ts, Data.Singletons.SingI a, Data.Singletons.SingI k) => Data.Singletons.SingI ('Serv.Api.CaptureBody ts a k)
instance (Data.Singletons.SingI ts, Data.Singletons.SingI k) => Data.Singletons.SingI ('Serv.Api.CaptureHeaders ts k)
instance (Data.Singletons.SingI ts, Data.Singletons.SingI k) => Data.Singletons.SingI ('Serv.Api.CaptureQuery ts k)
instance Data.Singletons.SingI s => Data.Singletons.SingI (Serv.Api.Const s)
instance (Data.Singletons.SingI n, Data.Singletons.SingI v) => Data.Singletons.SingI (Serv.Api.HeaderAs n v)
instance (Data.Singletons.SingI n, Data.Singletons.SingI t) => Data.Singletons.SingI (Serv.Api.Seg n t)
instance (Data.Singletons.SingI n, Data.Singletons.SingI t) => Data.Singletons.SingI (Serv.Api.Header n t)
instance Data.Singletons.SingI Serv.Api.Wildcard
instance (Data.Singletons.SingI t, Data.Singletons.SingI ts) => Data.Singletons.SingI ('Serv.Api.Endpoint t ts)
instance Data.Singletons.SingI ts => Data.Singletons.SingI ('Serv.Api.OneOf ts)
instance Data.Singletons.SingI Serv.Api.Abstract
instance (Data.Singletons.SingI p, Data.Singletons.SingI k) => Data.Singletons.SingI (p Serv.Api.:> k)


-- | Typeclasses constructing functions which reflect and analyze API
--   types.
--   
--   (<i>A little rough right now, sorry</i>)
module Serv.Api.Analysis
data EndpointAnalysis
EndpointAnalysis :: Set Verb -> Set SomeHeaderName -> Set SomeHeaderName -> EndpointAnalysis
[verbsHandled] :: EndpointAnalysis -> Set Verb
[headersExpected] :: EndpointAnalysis -> Set SomeHeaderName
[headersEmitted] :: EndpointAnalysis -> Set SomeHeaderName
inspectEndpoint :: Sing hs -> EndpointAnalysis
inspectHandler :: Sing h -> EndpointAnalysis
headerNames :: Sing hts -> Set SomeHeaderName
inspectVerbs :: Sing hs -> Set Verb
headersExpectedOf :: Sing hs -> Set SomeHeaderName
instance GHC.Base.Monoid Serv.Api.Analysis.EndpointAnalysis


-- | Module containing everything you need to define an <a>Api</a> type.
--   Import this unqualified for easy <a>Api</a> definitions.
--   
--   Exports the instance of <a>SingI</a> for all <tt>Typeable</tt> types.
--   This will cause issues for <tt>CustomStar</tt>-style <a>SingI</a>
--   instances, but is nearly required for Serv.
module Serv.Api.Prelude

-- | A <a>SingI</a> constraint is essentially an implicitly-passed
--   singleton. If you need to satisfy this constraint with an explicit
--   singleton, please see <a>withSingI</a>.
class SingI (a :: k)

-- | Produce the singleton explicitly. You will likely need the
--   <tt>ScopedTypeVariables</tt> extension to use this method the way you
--   want.
sing :: SingI a => Sing k a