Exported Servant.Links.addQueryParam

changelog.d/issue-1232

@@ -0,0 +1,9 @@
+synopsis: Exported addQueryParam
+packages: servant
+prs: #1785
+issues: #1232
+significance: minor
+description: {
+  `addQueryParams` is required to define custom `HasLink` instances which actually manipulate the
+  generated query params. This function was not exported earlier and now it is.
+}

servant/servant.cabal

@@ -1,6 +1,6 @@
 cabal-version:      3.0
 name:               servant
-version:            0.20.2
+version:            0.20.3
 synopsis:           A family of combinators for defining webservices APIs
 category:           Servant, Web
 description:

servant/src/Servant/Links.hs

@@ -115,6 +115,8 @@ module Servant.Links (
   , linkSegments
   , linkQueryParams
   , linkFragment
+  , addQueryParam
+  , addSegment
 ) where
 
 import           Data.Kind
@@ -187,6 +189,10 @@ import           Web.HttpApiData
 -- | A safe link datatype.
 -- The only way of constructing a 'Link' is using 'safeLink', which means any
 -- 'Link' is guaranteed to be part of the mentioned API.
+--
+-- NOTE: If you are writing a custom 'HasLink' instance, and need to manipulate
+-- the 'Link' (adding query params or fragments, perhaps), please use the the
+-- 'addQueryParam' and 'addSegment' functions.
 data Link = Link
   { _segments    :: [Escaped]
   , _queryParams :: [Param]
@@ -232,10 +238,18 @@ data Param
 addSegment :: Escaped -> Link -> Link
 addSegment seg l = l { _segments = _segments l <> [seg] }
 
+-- | Add a 'Param' (query param) to a 'Link'
+--
+-- Please use this judiciously from within your custom 'HasLink' instances
+-- to ensure that you don't end-up breaking the safe provided by "safe links"
 addQueryParam :: Param -> Link -> Link
 addQueryParam qp l =
     l { _queryParams = _queryParams l <> [qp] }
 
+-- | Add a 'Fragment' (query param) to a 'Link'
+--
+-- Please use this judiciously from within your custom 'HasLink' instances
+-- to ensure that you don't end-up breaking the safe provided by "safe links"
 addFragment :: Fragment' -> Link -> Link
 addFragment fr l = l { _fragment = fr }