From cbe0f0c0d0a288fd5a9aa4143e29e4e32135ee67 Mon Sep 17 00:00:00 2001 From: Nicolas BACQUEY Date: Wed, 7 Dec 2022 18:00:08 +0100 Subject: [PATCH] Add missing documentation and changelog line --- servant-server/CHANGELOG.md | 1 + .../src/Servant/Server/Internal/Router.hs | 20 ++++++++++++++++++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/servant-server/CHANGELOG.md b/servant-server/CHANGELOG.md index 09f4a73f..a3d11aa8 100644 --- a/servant-server/CHANGELOG.md +++ b/servant-server/CHANGELOG.md @@ -13,6 +13,7 @@ Compatibility with GHC 9.4, see [PR #1592](https://github.com/haskell-servant/se - Add `MonadFail` instance for `Handler` wrt [#1545](https://github.com/haskell-servant/servant/issues/1545) - Support GHC 9.2 [#1525](https://github.com/haskell-servant/servant/issues/1525) +- Add capture hints in `Router` type for debug and display purposes [PR #1556] (https://github.com/haskell-servant/servant/pull/1556) 0.19 ---- diff --git a/servant-server/src/Servant/Server/Internal/Router.hs b/servant-server/src/Servant/Server/Internal/Router.hs index 0a3391ce..5fdfa6e7 100644 --- a/servant-server/src/Servant/Server/Internal/Router.hs +++ b/servant-server/src/Servant/Server/Internal/Router.hs @@ -28,9 +28,12 @@ import Servant.Server.Internal.ServerError type Router env = Router' env RoutingApplication +-- | Holds information about pieces of url that are captured as variables. data CaptureHint = CaptureHint { captureName :: Text + -- ^ Holds the name of the captured variable , captureType :: TypeRep + -- ^ Holds the type of the captured variable } deriving (Show, Eq) @@ -54,10 +57,21 @@ data Router' env a = -- for the empty path, to be tried in order | CaptureRouter [CaptureHint] (Router' (Text, env) a) -- ^ first path component is passed to the child router in its - -- environment and removed afterwards + -- environment and removed afterwards. + -- The first argument is a list of hints for all variables that can be + -- captured by the router. The fact that it is a list is counter-intuitive, + -- because the 'Capture' combinator only allows to capture a single varible, + -- with a single name and a single type. However, the 'choice' smart + -- constructor may merge two 'Capture' combinators with different hints, thus + -- forcing the type to be '[CaptureHint]'. + -- Because 'CaptureRouter' is built from a 'Capture' combinator, the list of + -- hints should always be non-empty. | CaptureAllRouter [CaptureHint] (Router' ([Text], env) a) -- ^ all path components are passed to the child router in its -- environment and are removed afterwards + -- The first argument is a hint for the list of variables that can be + -- captured by the router. Note that the 'captureType' field of the hint + -- should always be '[a]' for some 'a'. | RawRouter (env -> a) -- ^ to be used for routes we do not know anything about | Choice (Router' env a) (Router' env a) @@ -101,6 +115,10 @@ choice router1 router2 = Choice router1 router2 data RouterStructure = StaticRouterStructure (Map Text RouterStructure) Int | CaptureRouterStructure [CaptureHint] RouterStructure + -- ^ The first argument holds information about variables + -- that are captured by the router. There may be several hints + -- if several routers have been aggregated by the 'choice' + -- smart constructor. | RawRouterStructure | ChoiceStructure RouterStructure RouterStructure deriving (Eq, Show)