servant/servant-foreign/src/Servant/Foreign.hs
Philip Patsch e4865644c1 doc(servant-foreign): Document module
I spend some considerable time reverse engineering the module, so I
thought I’d write the documentation I would have liked to see.

The strategy here is that a user not necessarily has insight into how
servant works internally, or even how to write complex servant routes,
they just want to generate a list of endpoints and convert the `Req`
type into e.g. generated code in $language. Thus, they need to know
the semantics of all fields of Req, how they interact and how they
relate to a plain http route.

I made sure every `f` is replaced with `ftype`, so we have one
conventional way of referring to the foreign type argument everywhere.

Some enums are not set at all, they are marked as such.

`_reqBodyContentType` introduces a major restriction of the module, so
that is mentioned in the documentation for now, until the time it will
be fixed.

A few TODO’s describe places where types don’t make sense but would
introduce API-breaking changes, so these should probably be
simplified,
but bundled in one go.
2021-03-25 11:26:53 +01:00

61 lines
1.3 KiB
Haskell

-- | Generalizes all the data needed to make code generation work with
-- arbitrary programming languages.
--
-- See documentation of 'HasForeignType' for a simple example. 'listFromAPI' returns a list of all your endpoints and their foreign types, given a mapping from Haskell types to foreign types (conventionally called `ftypes` below).
module Servant.Foreign
(
-- * Main API
listFromAPI
, Req(..)
, defReq
, HasForeignType(..)
, GenerateList(..)
, HasForeign(..)
, NoTypes
-- * Subtypes of 'Req'
, Url(..)
, Path
, Segment(..)
, SegmentType(..)
, isCapture
, captureArg
, QueryArg(..)
, ArgType(..)
, HeaderArg(..)
, Arg(..)
, FunctionName(..)
, ReqBodyContentType(..)
, PathSegment(..)
-- * Lenses
, argName
, argType
, argPath
, reqUrl
, reqMethod
, reqHeaders
, reqBody
, reqBodyContentType
, reqReturnType
, reqFuncName
, path
, queryStr
, queryArgName
, queryArgType
, headerArg
-- * Prisms
, _PathSegment
, _HeaderArg
, _ReplaceHeaderArg
, _Static
, _Cap
, _Normal
, _Flag
, _List
-- * Re-exports
, module Servant.API
, module Servant.Foreign.Inflections
) where
import Servant.API
import Servant.Foreign.Inflections
import Servant.Foreign.Internal