Servant.Foreign

Generalizes all the data needed to make code generation work with arbitrary programming languages.

Documentation

data ArgType

Constructors

Normal

Flag

List

Instances

Eq ArgType

Methods

(==) :: ArgType -> ArgType -> Bool

(/=) :: ArgType -> ArgType -> Bool

Show ArgType

Methods

showsPrec :: Int -> ArgType -> ShowS

show :: ArgType -> String

showList :: [ArgType] -> ShowS

data HeaderArg f

Constructors

HeaderArg

Fields

• _headerArg :: Arg f

ReplaceHeaderArg

Fields

• _headerArg :: Arg f
• _headerPattern :: Text

Instances

Eq f => Eq (HeaderArg f)

Methods

(==) :: HeaderArg f -> HeaderArg f -> Bool

(/=) :: HeaderArg f -> HeaderArg f -> Bool

Show f => Show (HeaderArg f)

Methods

showsPrec :: Int -> HeaderArg f -> ShowS

show :: HeaderArg f -> String

showList :: [HeaderArg f] -> ShowS

data QueryArg f

Constructors

QueryArg

Fields

• _queryArgName :: Arg f
• _queryArgType :: ArgType

Instances

Eq f => Eq (QueryArg f)

Methods

(==) :: QueryArg f -> QueryArg f -> Bool

(/=) :: QueryArg f -> QueryArg f -> Bool

Show f => Show (QueryArg f)

Methods

showsPrec :: Int -> QueryArg f -> ShowS

show :: QueryArg f -> String

showList :: [QueryArg f] -> ShowS

data Req f

Constructors

Req

Fields

• _reqUrl :: Url f
• _reqMethod :: Method
• _reqHeaders :: [HeaderArg f]
• _reqBody :: Maybe f
• _reqReturnType :: Maybe f
• _reqFuncName :: FunctionName

Instances

GenerateList ftype (Req ftype)

Methods

generateList :: Req ftype -> [Req ftype]

Eq f => Eq (Req f)

Methods

(==) :: Req f -> Req f -> Bool

(/=) :: Req f -> Req f -> Bool

Show f => Show (Req f)

Methods

showsPrec :: Int -> Req f -> ShowS

show :: Req f -> String

showList :: [Req f] -> ShowS

newtype Segment f

Constructors

Segment

Fields

• unSegment :: SegmentType f

Instances

Eq f => Eq (Segment f)

Methods

(==) :: Segment f -> Segment f -> Bool

(/=) :: Segment f -> Segment f -> Bool

Show f => Show (Segment f)

Methods

showsPrec :: Int -> Segment f -> ShowS

show :: Segment f -> String

showList :: [Segment f] -> ShowS

data SegmentType f

Constructors

Static PathSegment

a static path segment. like "/foo"

Cap (Arg f)

a capture. like "/:userid"

Instances

Eq f => Eq (SegmentType f)

Methods

(==) :: SegmentType f -> SegmentType f -> Bool

(/=) :: SegmentType f -> SegmentType f -> Bool

Show f => Show (SegmentType f)

Methods

showsPrec :: Int -> SegmentType f -> ShowS

show :: SegmentType f -> String

showList :: [SegmentType f] -> ShowS

data Url f

Constructors

Url

Fields

• _path :: Path f
• _queryStr :: [QueryArg f]

Instances

Eq f => Eq (Url f)

Methods

(==) :: Url f -> Url f -> Bool

(/=) :: Url f -> Url f -> Bool

Show f => Show (Url f)

Methods

showsPrec :: Int -> Url f -> ShowS

show :: Url f -> String

showList :: [Url f] -> ShowS

type Path f = [Segment f]

data Arg f

Constructors

Arg

Fields

• _argName :: PathSegment
• _argType :: f

Instances

Eq f => Eq (Arg f)

Methods

(==) :: Arg f -> Arg f -> Bool

(/=) :: Arg f -> Arg f -> Bool

Show f => Show (Arg f)

Methods

showsPrec :: Int -> Arg f -> ShowS

show :: Arg f -> String

showList :: [Arg f] -> ShowS

newtype FunctionName

Constructors

FunctionName

Fields

• unFunctionName :: [Text]

Instances

Eq FunctionName

Methods

(==) :: FunctionName -> FunctionName -> Bool

(/=) :: FunctionName -> FunctionName -> Bool

Show FunctionName

Methods

showsPrec :: Int -> FunctionName -> ShowS

show :: FunctionName -> String

showList :: [FunctionName] -> ShowS

Monoid FunctionName

Methods

mempty :: FunctionName

mappend :: FunctionName -> FunctionName -> FunctionName

mconcat :: [FunctionName] -> FunctionName

newtype PathSegment

Constructors

PathSegment

Fields

• unPathSegment :: Text

Instances

Eq PathSegment

Methods

(==) :: PathSegment -> PathSegment -> Bool

(/=) :: PathSegment -> PathSegment -> Bool

Show PathSegment

Methods

showsPrec :: Int -> PathSegment -> ShowS

show :: PathSegment -> String

showList :: [PathSegment] -> ShowS

IsString PathSegment

Methods

fromString :: String -> PathSegment

Monoid PathSegment

Methods

mempty :: PathSegment

mappend :: PathSegment -> PathSegment -> PathSegment

mconcat :: [PathSegment] -> PathSegment

argName :: forall f. Lens' (Arg f) PathSegment

argType :: forall f f. Lens (Arg f) (Arg f) f f

argPath :: Getter (Arg f) Text

reqUrl :: forall f. Lens' (Req f) (Url f)

reqMethod :: forall f. Lens' (Req f) Method

reqHeaders :: forall f. Lens' (Req f) [HeaderArg f]

reqBody :: forall f. Lens' (Req f) (Maybe f)

reqReturnType :: forall f. Lens' (Req f) (Maybe f)

reqFuncName :: forall f. Lens' (Req f) FunctionName

path :: forall f. Lens' (Url f) (Path f)

queryStr :: forall f. Lens' (Url f) [QueryArg f]

queryArgName :: forall f f. Lens (QueryArg f) (QueryArg f) (Arg f) (Arg f)

queryArgType :: forall f. Lens' (QueryArg f) ArgType

headerArg :: forall f f. Lens (HeaderArg f) (HeaderArg f) (Arg f) (Arg f)

_PathSegment :: Iso' PathSegment Text

_HeaderArg :: forall f. Prism' (HeaderArg f) (Arg f)

_ReplaceHeaderArg :: forall f. Prism' (HeaderArg f) (Arg f, Text)

_Static :: forall f. Prism' (SegmentType f) PathSegment

_Cap :: forall f f. Prism (SegmentType f) (SegmentType f) (Arg f) (Arg f)

_Normal :: Prism' ArgType ()

_Flag :: Prism' ArgType ()

_List :: Prism' ArgType ()

class HasForeign lang ftype layout where

Minimal complete definition

foreignFor

Associated Types

type Foreign ftype layout :: *

Methods

foreignFor :: Proxy lang -> Proxy ftype -> Proxy layout -> Req ftype -> Foreign ftype layout

Instances

HasForeign k lang ftype Raw

Associated Types

type Foreign Raw layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * Raw -> Proxy * layout -> Req Raw -> Foreign Raw layout

(HasForeign k lang ftype a, HasForeign k lang ftype b) => HasForeign k lang ftype ((:<|>) a b)

Associated Types

type Foreign ((:<|>) a b) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * (a :<|> b) -> Proxy * layout -> Req (a :<|> b) -> Foreign (a :<|> b) layout

HasForeign k lang ftype sublayout => HasForeign k lang ftype (WithNamedContext name context sublayout)

Associated Types

type Foreign (WithNamedContext name context sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * (WithNamedContext name context sublayout) -> Proxy * layout -> Req (WithNamedContext name context sublayout) -> Foreign (WithNamedContext name context sublayout) layout

HasForeign k lang ftype sublayout => HasForeign k lang ftype ((:>) * * HttpVersion sublayout)

Associated Types

type Foreign ((:>) * * HttpVersion sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) HttpVersion sublayout) -> Proxy * layout -> Req ((* :> *) HttpVersion sublayout) -> Foreign ((* :> *) HttpVersion sublayout) layout

HasForeign k lang ftype sublayout => HasForeign k lang ftype ((:>) * * Vault sublayout)

Associated Types

type Foreign ((:>) * * Vault sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) Vault sublayout) -> Proxy * layout -> Req ((* :> *) Vault sublayout) -> Foreign ((* :> *) Vault sublayout) layout

HasForeign k lang ftype sublayout => HasForeign k lang ftype ((:>) * * IsSecure sublayout)

Associated Types

type Foreign ((:>) * * IsSecure sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) IsSecure sublayout) -> Proxy * layout -> Req ((* :> *) IsSecure sublayout) -> Foreign ((* :> *) IsSecure sublayout) layout

HasForeign k lang ftype sublayout => HasForeign k lang ftype ((:>) * * RemoteHost sublayout)

Associated Types

type Foreign ((:>) * * RemoteHost sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) RemoteHost sublayout) -> Proxy * layout -> Req ((* :> *) RemoteHost sublayout) -> Foreign ((* :> *) RemoteHost sublayout) layout

(KnownSymbol path, HasForeign k lang ftype sublayout) => HasForeign k lang ftype ((:>) * Symbol path sublayout)

Associated Types

type Foreign ((:>) * Symbol path sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> Symbol) path sublayout) -> Proxy * layout -> Req ((* :> Symbol) path sublayout) -> Foreign ((* :> Symbol) path sublayout) layout

(Elem JSON list, HasForeignType k k1 lang ftype a, HasForeign k1 lang ftype sublayout) => HasForeign k1 lang ftype ((:>) * * (ReqBody k list a) sublayout)

Associated Types

type Foreign ((:>) * * (ReqBody k list a) sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) (ReqBody k list a) sublayout) -> Proxy * layout -> Req ((* :> *) (ReqBody k list a) sublayout) -> Foreign ((* :> *) (ReqBody k list a) sublayout) layout

(KnownSymbol sym, HasForeignType * k lang ftype Bool, HasForeign k lang ftype sublayout) => HasForeign k lang ftype ((:>) * * (QueryFlag sym) sublayout)

Associated Types

type Foreign ((:>) * * (QueryFlag sym) sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) (QueryFlag sym) sublayout) -> Proxy * layout -> Req ((* :> *) (QueryFlag sym) sublayout) -> Foreign ((* :> *) (QueryFlag sym) sublayout) layout

(KnownSymbol sym, HasForeignType * k lang ftype [a], HasForeign k lang ftype sublayout) => HasForeign k lang ftype ((:>) * * (QueryParams * sym a) sublayout)

Associated Types

type Foreign ((:>) * * (QueryParams * sym a) sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) (QueryParams * sym a) sublayout) -> Proxy * layout -> Req ((* :> *) (QueryParams * sym a) sublayout) -> Foreign ((* :> *) (QueryParams * sym a) sublayout) layout

(KnownSymbol sym, HasForeignType k k1 lang ftype a, HasForeign k1 lang ftype sublayout) => HasForeign k1 lang ftype ((:>) * * (QueryParam k sym a) sublayout)

Associated Types

type Foreign ((:>) * * (QueryParam k sym a) sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) (QueryParam k sym a) sublayout) -> Proxy * layout -> Req ((* :> *) (QueryParam k sym a) sublayout) -> Foreign ((* :> *) (QueryParam k sym a) sublayout) layout

(KnownSymbol sym, HasForeignType * k lang ftype a, HasForeign k lang ftype sublayout) => HasForeign k lang ftype ((:>) * * (Header sym a) sublayout)

Associated Types

type Foreign ((:>) * * (Header sym a) sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) (Header sym a) sublayout) -> Proxy * layout -> Req ((* :> *) (Header sym a) sublayout) -> Foreign ((* :> *) (Header sym a) sublayout) layout

(KnownSymbol sym, HasForeignType k k1 lang ftype t, HasForeign k1 lang ftype sublayout) => HasForeign k1 lang ftype ((:>) * * (Capture k sym t) sublayout)

Associated Types

type Foreign ((:>) * * (Capture k sym t) sublayout) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * ((* :> *) (Capture k sym t) sublayout) -> Proxy * layout -> Req ((* :> *) (Capture k sym t) sublayout) -> Foreign ((* :> *) (Capture k sym t) sublayout) layout

(Elem JSON list, HasForeignType k k2 lang ftype a, ReflectMethod k1 method) => HasForeign k2 lang ftype (Verb k k1 method status list a)

Associated Types

type Foreign (Verb k k1 method status list a) layout :: *

Methods

foreignFor :: Proxy lang ftype -> Proxy * (Verb k k1 method status list a) -> Proxy * layout -> Req (Verb k k1 method status list a) -> Foreign (Verb k k1 method status list a) layout

class HasForeignType lang ftype a where

HasForeignType maps Haskell types with types in the target language of your backend. For example, let's say you're implementing a backend to some language X, and you want a Text representation of each input/output type mentioned in the API:

-- First you need to create a dummy type to parametrize your
-- instances.
data LangX

-- Otherwise you define instances for the types you need
instance HasForeignType LangX Text Int where
   typeFor _ _ _ = "intX"

-- Or for example in case of lists
instance HasForeignType LangX Text a => HasForeignType LangX Text [a] where
   typeFor lang type _ = "listX of " <> typeFor lang ftype (Proxy :: Proxy a)

Finally to generate list of information about all the endpoints for an API you create a function of a form:

getEndpoints :: (HasForeign LangX Text api, GenerateList Text (Foreign Text api))
             => Proxy api -> [Req Text]
getEndpoints api = listFromAPI (Proxy :: Proxy LangX) (Proxy :: Proxy Text) api

-- If language __X__ is dynamically typed then you can use
-- a predefined NoTypes parameter with the () output type:

getEndpoints :: (HasForeign NoTypes () api, GenerateList Text (Foreign () api))
             => Proxy api -> [Req ()]
getEndpoints api = listFromAPI (Proxy :: Proxy NoTypes) (Proxy :: Proxy ()) api

Minimal complete definition

typeFor

Methods

typeFor :: Proxy lang -> Proxy ftype -> Proxy a -> ftype

Instances

HasForeignType k * NoTypes () ftype

Methods

typeFor :: Proxy () ftype -> Proxy * ftype -> Proxy NoTypes a -> ftype

class GenerateList ftype reqs where

Utility class used by listFromAPI which computes the data needed to generate a function for each endpoint and hands it all back in a list.

Minimal complete definition

generateList

Methods

generateList :: reqs -> [Req ftype]

Instances

GenerateList ftype (Req ftype)

Methods

generateList :: Req ftype -> [Req ftype]

(GenerateList ftype start, GenerateList ftype rest) => GenerateList ftype ((:<|>) start rest)

Methods

generateList :: (start :<|> rest) -> [Req ftype]

data NoTypes

Instances

HasForeignType k * NoTypes () ftype

Methods

typeFor :: Proxy () ftype -> Proxy * ftype -> Proxy NoTypes a -> ftype

captureArg :: Segment f -> Arg f

isCapture :: Segment f -> Bool

defReq :: Req ftype

listFromAPI :: (HasForeign lang ftype api, GenerateList ftype (Foreign ftype api)) => Proxy lang -> Proxy ftype -> Proxy api -> [Req ftype]

Generate the necessary data for codegen as a list, each Req describing one endpoint from your API type.

module Servant.API

module Servant.Foreign.Inflections