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


-- | Use records for query parameters in servant APIs.
--   
--   Having positional parameters in <tt>servant</tt> can be error-prone,
--   especially when there are a lot of them and they have similar types.
--   This package solves that problem by letting one use records to specify
--   query parameters in <tt>servant</tt> APIs. Use
--   <a>servant-queryparam-server</a> for servers,
--   <a>servant-queryparam-client</a> for clients,
--   [servant-queryparam-openapi3](https:/<i>hackage.haskell.org</i>package<i>servant-queryparam-openapi3)
--   for [openapi3](https:</i><i>hackage.haskell.org</i>package/openapi3).
--   See the <a>README</a> for more information.
@package servant-queryparam-core
@version 2.0.0


-- | This module provides functions to modify <a>Symbol</a>s and type-level
--   lists.
--   
--   The workflow to define a modification function can be as follows.
--   
--   <ol>
--   <li>Use <a>ToList</a> to convert a <a>Symbol</a> to a type-level list
--   of <a>Char</a>s.</li>
--   <li>Use functions from here and from the package
--   <a>first-class-families</a> for type-level lists
--   (<tt>Fcf.Data.List</tt>).</li>
--   <li>Use <a>FromList</a> to convert a type-level list of <a>Char</a>s
--   back to a <a>Symbol</a>.</li>
--   </ol>
--   
--   Example (see <a>DropPrefix</a>):
--   
--   <pre>
--   &gt;&gt;&gt; :kind! DropPrefix "_userParams_category"
--   DropPrefix "_userParams_category" :: Symbol
--   = "category"
--   </pre>
--   
--   Modules that use the <a>Eval</a> type family (e.g.,
--   <a>Servant.Record</a>) must be imported together with modules that
--   export instances of <a>Eval</a> (see the <tt>GHC</tt> documentation on
--   Type families).
module Servant.QueryParam.TypeLevel

-- | Expression evaluator.
type family Eval (e :: Exp a) :: a

-- | Kind of type-level expressions indexed by their result type.
type Exp a = a -> Type

-- | Convert a list of <a>Char</a>s to a <a>Symbol</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! FromList ['a', '+', 'c']
--   FromList ['a', '+', 'c'] :: Symbol
--   = "a+c"
--   </pre>
type family FromList (cs :: [Char]) :: Symbol

-- | Convert a list of <a>Char</a>s to a <a>Symbol</a>.
--   
--   In this list, <tt>Chars</tt> go in a reverse order.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! FromList1 ['a', 'b', 'c'] ""
--   FromList1 ['a', 'b', 'c'] "" :: Symbol
--   = "cba"
--   </pre>
type family FromList1 (syms :: [Char]) (sym :: Symbol) :: Symbol

-- | Convert a <a>Symbol</a> to a list of <a>Char</a>s.
type family ToList (sym :: Symbol) :: [Char]

-- | Convert a possibly unconsed <a>Symbol</a> to a list of <a>Char</a>s.
type family ToList1 (sym :: Maybe (Char, Symbol)) :: [Char]

-- | Type equality.
--   
--   <h3><b>Details</b></h3>
--   
--   The base library also defines a similar <tt>(<a>==</a>)</tt>; it
--   differs from <a>TyEq</a> in the following ways:
--   
--   <ul>
--   <li><a>TyEq</a> is heterogeneous: its arguments may have different
--   kinds;</li>
--   <li><a>TyEq</a> is reflexive: <tt>TyEq a a</tt> always reduces to
--   <a>True</a> even if <tt>a</tt> is a variable.</li>
--   </ul>
data TyEq (c :: a) (d :: b) (e :: Bool)

-- | Type inequality
data NotTyEq :: a -> b -> Exp Bool

-- | Drop leading underscores.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! Eval (DropUnderscores ['_', '_', 'a'])
--   Eval (DropUnderscores ['_', '_', 'a']) :: [Char]
--   = '['a']
--   </pre>
type DropUnderscores = DropWhile (TyEq '_')

-- | Drop leading non-underscores.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! Eval (DropNonUnderscores ['a', 'a', '_'])
--   Eval (DropNonUnderscores ['a', 'a', '_']) :: [Char]
--   = '['_']
--   </pre>
type DropNonUnderscores = DropWhile (NotTyEq '_')

-- | Drop the prefix of a <a>Symbol</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! DropPrefix "_userParams_category"
--   DropPrefix "_userParams_category" :: Symbol
--   = "category"
--   </pre>
type family DropPrefix (sym :: Symbol) :: Symbol


-- | This module provides functions and instances for working with query
--   parameter records.
module Servant.QueryParam.Record

-- | <a>RecordParam</a> uses fields in a record to represent query
--   parameters.
--   
--   For each record field:
--   
--   <ul>
--   <li>The modified record field name becomes a query parameter
--   name.</li>
--   <li>The record field type becomes the query parameter type.</li>
--   </ul>
--   
--   For example, this API:
--   
--   <pre>
--   type API = "users" :&gt; (QueryParam "category" Category :&gt;
--                          QueryParam' '[Required, Strict] "sort_by" SortBy :&gt;
--                          QueryFlag "with_schema" :&gt;
--                          QueryParams "filters" Filter :&gt;
--                          Get '[JSON] User)
--   </pre>
--   
--   can be written using records:
--   
--   <pre>
--   data DropPrefixExp :: sym -&gt; <a>Exp</a> sym
--   
--   type instance <a>Eval</a> (DropPrefixExp sym) = <a>DropPrefix</a> sym
--   
--   data UserParams = UserParams
--     { _userParams_category :: Maybe Category
--     , _userParams_sort_by :: SortBy
--     , _userParams_with_schema :: Bool
--     , _userParams_filters :: [Filter]
--     }
--   
--   type API = "users" :&gt; <a>RecordParam</a> DropPrefixExp UserParams :&gt; Get '[JSON] User
--   </pre>
--   
--   Here, <tt>DropPrefixExp</tt> wraps a <tt>sym</tt> into <tt>Exp</tt>.
--   
--   The instance of <a>Eval</a> for <tt>DropPrefixExp sym</tt> drops the
--   prefix of that <tt>sym</tt> via <a>DropPrefix</a>.
--   
--   <a>DropPrefix</a> is applied to the fields of <tt>UserParams</tt>.
--   
--   The <tt>"_userParams_category"</tt> record field corresponds to the
--   query parameter <tt>"category"</tt>.
data RecordParam (mod :: Symbol -> Exp Symbol) (a :: Type)

-- | Type family for rewriting a <a>RecordParam</a> API to a regular
--   <tt>servant</tt> API. This family is useful for defining instances of
--   classes that extract information from the API type, such as classes
--   from <tt>servant-swagger</tt> or <tt>servant-foreign</tt>.
--   
--   Typical use:
--   
--   <pre>
--   instance SomeClass (UnRecordParam (RecordParam mod a :&gt; api))) =&gt;
--            SomeClass (RecordParam mod a :&gt; api) where
--      someMethod _ = someMethod (Proxy :: Proxy (UnRecordParam (RecordParam mod a :&gt; api))
--   </pre>
type family UnRecordParam (mod :: Symbol -> Exp Symbol) (x :: Type) :: Type
instance (GHC.Generics.Generic a, Servant.QueryParam.Record.GHasLink mod (GHC.Generics.Rep a) sub) => Servant.Links.HasLink (Servant.QueryParam.Record.RecordParam mod a Servant.API.Sub.:> sub)
instance Servant.QueryParam.Record.GHasLink mod a sub => Servant.Links.HasLink (Servant.QueryParam.Record.GParam mod (a ()) Servant.API.Sub.:> sub)
instance forall k (mod :: GHC.Types.Symbol -> Fcf.Core.Exp GHC.Types.Symbol) (c :: * -> *) (sub :: k) (m :: GHC.Generics.Meta). Servant.QueryParam.Record.GHasLink mod c sub => Servant.QueryParam.Record.GHasLink mod (GHC.Generics.D1 m c) sub
instance (Servant.Links.HasLink sub, Servant.QueryParam.Record.GHasLink mod a (Servant.QueryParam.Record.GParam mod (b ()) Servant.API.Sub.:> sub)) => Servant.QueryParam.Record.GHasLink mod (a GHC.Generics.:*: b) sub
instance forall k (mod :: GHC.Types.Symbol -> Fcf.Core.Exp GHC.Types.Symbol) (a :: * -> *) (sub :: k) (m :: GHC.Generics.Meta). (Servant.QueryParam.Record.GHasLink mod a sub, Servant.Links.HasLink sub) => Servant.QueryParam.Record.GHasLink mod (GHC.Generics.C1 m a) sub
instance (GHC.TypeLits.KnownSymbol sym, GHC.TypeLits.KnownSymbol (Fcf.Core.Eval (mod sym)), Servant.Links.HasLink sub) => Servant.QueryParam.Record.GHasLink mod (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just sym) d1 d2 d3) (GHC.Generics.Rec0 GHC.Types.Bool)) sub
instance (GHC.TypeLits.KnownSymbol sym, GHC.TypeLits.KnownSymbol (Fcf.Core.Eval (mod sym)), Web.Internal.HttpApiData.ToHttpApiData a, Servant.Links.HasLink (a Servant.API.Sub.:> sub), Servant.Links.HasLink sub) => Servant.QueryParam.Record.GHasLink mod (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just sym) d1 d2 d3) (GHC.Generics.Rec0 [a])) sub
instance (GHC.TypeLits.KnownSymbol sym, GHC.TypeLits.KnownSymbol (Fcf.Core.Eval (mod sym)), Web.Internal.HttpApiData.ToHttpApiData a, Servant.Links.HasLink (a Servant.API.Sub.:> sub), Servant.Links.HasLink sub) => Servant.QueryParam.Record.GHasLink mod (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just sym) d1 d2 d3) (GHC.Generics.Rec0 (GHC.Maybe.Maybe a))) sub
instance (GHC.TypeLits.KnownSymbol sym, GHC.TypeLits.KnownSymbol (Fcf.Core.Eval (mod sym)), Web.Internal.HttpApiData.ToHttpApiData a, Servant.Links.HasLink (a Servant.API.Sub.:> sub), Servant.Links.HasLink sub) => Servant.QueryParam.Record.GHasLink mod (GHC.Generics.S1 ('GHC.Generics.MetaSel ('GHC.Maybe.Just sym) d1 d2 d3) (GHC.Generics.Rec0 a)) sub