@@ -13,8 +13,6 @@
13{-# LANGUAGE TypeOperators #-}
13{-# LANGUAGE TypeOperators #-}
14{-# LANGUAGE UndecidableInstances #-}
14{-# LANGUAGE UndecidableInstances #-}
16−-- | Generalizes all the data needed to make code generation work with
17−-- arbitrary programming languages.
18module Servant.Foreign.Internal where
16module Servant.Foreign.Internal where
20import Prelude ()
18import Prelude ()
@@ -40,55 +38,75 @@ import Servant.API.Modifiers
40 (RequiredArgument)
38 (RequiredArgument)
41import Servant.API.TypeLevel
39import Servant.API.TypeLevel
41+-- | Canonical name of the endpoint, can be used to generate a function name.
43+-- You can use the functions in "Servant.Foreign.Inflections", like 'Servant.Foreign.Inflections.camelCase' to transform to `Text`.
43newtype FunctionName = FunctionName { unFunctionName :: [Text] }
44newtype FunctionName = FunctionName { unFunctionName :: [Text] }
44 deriving (Data, Show, Eq, Semigroup, Monoid, Typeable)
45 deriving (Data, Show, Eq, Semigroup, Monoid, Typeable)
46makePrisms ''FunctionName
47makePrisms ''FunctionName
49+-- | See documentation of 'Arg'
48newtype PathSegment = PathSegment { unPathSegment :: Text }
50newtype PathSegment = PathSegment { unPathSegment :: Text }
49 deriving (Data, Show, Eq, IsString, Semigroup, Monoid, Typeable)
51 deriving (Data, Show, Eq, IsString, Semigroup, Monoid, Typeable)
51makePrisms ''PathSegment
53makePrisms ''PathSegment
55+-- | Maps a name to the foreign type that belongs to the annotated value.
57+-- Used for header args, query args, and capture args.
53−data Arg f = Arg
58+data Arg ftype = Arg
54 { _argName :: PathSegment
59 { _argName :: PathSegment
60+ -- ^ The name to be captured.
62+ -- Only for capture args it really denotes a path segment.
55− , _argType :: f }
63+ , _argType :: ftype
64+ -- ^ Foreign type the associated value will have
56 deriving (Data, Eq, Show, Typeable)
66 deriving (Data, Eq, Show, Typeable)
58makeLenses ''Arg
68makeLenses ''Arg
60−argPath :: Getter (Arg f) Text
70+argPath :: Getter (Arg ftype) Text
61argPath = argName . _PathSegment
71argPath = argName . _PathSegment
63−data SegmentType f
73+data SegmentType ftype
64 = Static PathSegment
74 = Static PathSegment
65− -- ^ a static path segment. like "/foo"
75+ -- ^ Static path segment.
79+ -- contains the static segments @"foo"@, @"bar"@ and @"baz"@.
66− | Cap (Arg f)
80+ | Cap (Arg ftype)
67− -- ^ a capture. like "/:userid"
81+ -- ^ A capture.
83+ -- @"user\/{userid}\/name"@
85+ -- would capture the arg @userid@ with type @ftype@.
68 deriving (Data, Eq, Show, Typeable)
86 deriving (Data, Eq, Show, Typeable)
70makePrisms ''SegmentType
88makePrisms ''SegmentType
90+-- | A part of the Url’s path.
72−newtype Segment f = Segment { unSegment :: SegmentType f }
91+newtype Segment ftype = Segment { unSegment :: SegmentType ftype }
73 deriving (Data, Eq, Show, Typeable)
92 deriving (Data, Eq, Show, Typeable)
75makePrisms ''Segment
94makePrisms ''Segment
96+-- | Whether a segment is a 'Cap'.
77−isCapture :: Segment f -> Bool
97+isCapture :: Segment ftype -> Bool
78isCapture (Segment (Cap _)) = True
98isCapture (Segment (Cap _)) = True
79isCapture _ = False
99isCapture _ = False
101+-- | Crashing Arg extraction from segment, TODO: remove
81−captureArg :: Segment f -> Arg f
102+captureArg :: Segment ftype -> Arg ftype
82captureArg (Segment (Cap s)) = s
103captureArg (Segment (Cap s)) = s
83captureArg _ = error "captureArg called on non capture"
104captureArg _ = error "captureArg called on non capture"
106+-- TODO: remove, unnecessary indirection
85−type Path f = [Segment f]
107+type Path ftype = [Segment ftype]
87−newtype Frag f = Frag { unFragment :: Arg f }
88− deriving (Data, Eq, Show, Typeable)
109+-- | Type of a 'QueryArg'.
92data ArgType
110data ArgType
@@ -97,18 +115,41 @@ data ArgType
98makePrisms ''ArgType
116makePrisms ''ArgType
118+-- | Url Query argument.
120+-- Urls can contain query arguments, which is a list of key-value pairs.
121+-- In a typical url, query arguments look like this:
123+-- @?foo=bar&alist[]=el1&alist[]=el2&aflag@
127+-- * @?foo=bar@: a plain key-val pair, either optional or required ('QueryParam')
128+-- * @?aflag@: a flag (no value, implicitly Bool with default `false` if it’s missing) ('QueryFlag')
129+-- * @?alist[]=el1&alist[]=el2@: list of values ('QueryParams')
131+-- @_queryArgType@ will be set accordingly.
133+-- For the plain key-val pairs ('QueryParam'), @_queryArgName@’s @ftype@ will be wrapped in a @Maybe@ if the argument is optional.
100−data QueryArg f = QueryArg
134+data QueryArg ftype = QueryArg
101− { _queryArgName :: Arg f
135+ { _queryArgName :: Arg ftype
136+ -- ^ Name and foreign type of the argument. Will be wrapped in `Maybe` if the query is optional and in a `[]` if the query is a list
102 , _queryArgType :: ArgType
137 , _queryArgType :: ArgType
138+ -- ^ one of normal/plain, list or flag
104 deriving (Data, Eq, Show, Typeable)
140 deriving (Data, Eq, Show, Typeable)
106makeLenses ''QueryArg
142makeLenses ''QueryArg
108−data HeaderArg f = HeaderArg
144+data HeaderArg ftype =
145+ -- | The name of the header and the foreign type of its value.
109− { _headerArg :: Arg f }
147+ { _headerArg :: Arg ftype }
148+ -- | Unused, will never be set.
110 | ReplaceHeaderArg
151 | ReplaceHeaderArg
111− { _headerArg :: Arg f
152+ { _headerArg :: Arg ftype
112 , _headerPattern :: Text
153 , _headerPattern :: Text
114 deriving (Data, Eq, Show, Typeable)
155 deriving (Data, Eq, Show, Typeable)
@@ -117,29 +158,71 @@ makeLenses ''HeaderArg
118makePrisms ''HeaderArg
159makePrisms ''HeaderArg
161+-- | Full endpoint url, with all captures and parameters
120−data Url f = Url
162+data Url ftype = Url
121− { _path :: Path f
163+ { _path :: Path ftype
164+ -- ^ Url path, list of either static segments or captures
166+ -- @"foo\/{id}\/bar"@
122− , _queryStr :: [QueryArg f]
167+ , _queryStr :: [QueryArg ftype]
168+ -- ^ List of query args
123− , _frag :: Maybe f
171+ , _frag :: Maybe ftype
174+ -- Not sent to the HTTP server, so only useful for frontend matters (e.g. inter-page linking).
125 deriving (Data, Eq, Show, Typeable)
178 deriving (Data, Eq, Show, Typeable)
127−defUrl :: Url f
180+defUrl :: Url ftype
128defUrl = Url [] [] Nothing
181defUrl = Url [] [] Nothing
130makeLenses ''Url
183makeLenses ''Url
185+-- | See documentation of '_reqBodyContentType'
132data ReqBodyContentType = ReqBodyJSON | ReqBodyMultipart
186data ReqBodyContentType = ReqBodyJSON | ReqBodyMultipart
133 deriving (Data, Eq, Show, Read)
187 deriving (Data, Eq, Show, Read)
189+-- | Full description of an endpoint in your API, generated by 'listFromAPI'. It should give you all the information needed to generate foreign language bindings.
191+-- Every field containing @ftype@ will use the foreign type mapping specified via 'HasForeignType' (see its docstring on how to set that up).
193+-- See https://docs.servant.dev/en/stable/tutorial/ApiType.html for accessible documentation of the possible content of an endpoint.
135−data Req f = Req
194+data Req ftype = Req
136− { _reqUrl :: Url f
195+ { _reqUrl :: Url ftype
196+ -- ^ Full list of URL segments, including captures
137 , _reqMethod :: HTTP.Method
197 , _reqMethod :: HTTP.Method
198+ -- ^ @\"GET\"@\/@\"POST\"@\/@\"PUT\"@\/…
138− , _reqHeaders :: [HeaderArg f]
199+ , _reqHeaders :: [HeaderArg ftype]
200+ -- ^ Headers required by this endpoint, with their type
139− , _reqBody :: Maybe f
201+ , _reqBody :: Maybe ftype
202+ -- ^ Foreign type of the expected request body ('ReqBody'), if any
140− , _reqReturnType :: Maybe f
203+ , _reqReturnType :: Maybe ftype
204+ -- ^ The foreign type of the response, if any
141 , _reqFuncName :: FunctionName
205 , _reqFuncName :: FunctionName
206+ -- ^ The URL segments rendered in a way that they can be easily concatenated into a canonical function name
142 , _reqBodyContentType :: ReqBodyContentType
207 , _reqBodyContentType :: ReqBodyContentType
208+ -- ^ The content type the request body is transferred as.
210+ -- This is a severe limitation of @servant-foreign@ currently,
211+ -- as we only allow the content type to be `JSON`
212+ -- no user-defined content types. ('ReqBodyMultipart' is not
213+ -- actually implemented.)
215+ -- Thus, any routes looking like this will work:
217+ -- @"foo" :> Get '[JSON] Foo@
219+ -- while routes like
221+ -- @"foo" :> Get '[MyFancyContentType] Foo@
223+ -- will fail with an error like
225+ -- @• JSON expected in list '[MyFancyContentType]@
144 deriving (Data, Eq, Show, Typeable)
227 deriving (Data, Eq, Show, Typeable)
@@ -183,11 +266,16 @@ defReq = Req defUrl "GET" [] Nothing Nothing (FunctionName []) ReqBodyJSON
183class HasForeignType lang ftype a where
266class HasForeignType lang ftype a where
184 typeFor :: Proxy lang -> Proxy ftype -> Proxy a -> ftype
267 typeFor :: Proxy lang -> Proxy ftype -> Proxy a -> ftype
269+-- | The language definition without any foreign types. It can be used for dynamic languages which do not /do/ type annotations.
186data NoTypes
270data NoTypes
272+-- | Use if the foreign language does not have any types.
188−instance HasForeignType NoTypes NoContent ftype where
273+instance HasForeignType NoTypes NoContent a where
189 typeFor _ _ _ = NoContent
274 typeFor _ _ _ = NoContent
276+-- | Implementation of the Servant framework types.
278+-- Relevant instances: Everything containing 'HasForeignType'.
191class HasForeign lang ftype (api :: *) where
279class HasForeign lang ftype (api :: *) where
192 type Foreign ftype api :: *
280 type Foreign ftype api :: *
193 foreignFor :: Proxy lang -> Proxy ftype -> Proxy api -> Req ftype -> Foreign ftype api
281 foreignFor :: Proxy lang -> Proxy ftype -> Proxy api -> Req ftype -> Foreign ftype api