@@ -23,7 +23,9 @@
2323-- example above).
2424module Servant.API.ResponseHeaders
2525 ( Headers(..)
26− , AddHeader(addHeader)
26+ , AddHeader
27+ , addHeader
28+ , noHeader
2729 , BuildHeadersTo(buildHeadersTo)
2830 , GetHeaders(getHeaders)
2931 , HeaderValMap
@@ -43,7 +45,7 @@ import Prelude ()
4345import Prelude.Compat
4446
4547-- | Response Header objects. You should never need to construct one directly.
46−-- Instead, use 'addHeader'.
48+-- Instead, use 'addOptionalHeader.
4749data Headers ls a = Headers { getResponse :: a
4850 -- ^ The underlying value of a 'Headers'
4951 , getHeadersHList :: HList ls
@@ -108,17 +110,48 @@ instance OVERLAPPABLE_ ( KnownSymbol h, GetHeaders (HList rest), ToHttpApiData v
108110-- We need all these fundeps to save type inference
109111class AddHeader h v orig new
110112 | h v orig -> new, new -> h, new -> v, new -> orig where
111− addHeader :: v -> orig -> new -- ^ N.B.: The same header can't be added multiple times
113+ addOptionalHeader :: Header h v -> orig -> new -- ^ N.B.: The same header can't be added multiple times
112114
113115
114116instance OVERLAPPING_ ( KnownSymbol h, ToHttpApiData v )
115117 => AddHeader h v (Headers (fst ': rest) a) (Headers (Header h v ': fst ': rest) a) where
116− addHeader a (Headers resp heads) = Headers resp (HCons (Header a) heads)
118+ addOptionalHeader hdr (Headers resp heads) = Headers resp (HCons hdr heads)
117119
118120instance OVERLAPPABLE_ ( KnownSymbol h, ToHttpApiData v
119121 , new ~ (Headers '[Header h v] a) )
120122 => AddHeader h v a new where
121− addHeader a resp = Headers resp (HCons (Header a) HNil)
123+ addOptionalHeader hdr resp = Headers resp (HCons hdr HNil)
124+
125+-- | @addHeader@ adds a header to a response. Note that it changes the type of
126+-- the value in the following ways:
127+--
128+-- 1. A simple value is wrapped in "Headers [<hdr>]":
129+--
130+-- >>> let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;
131+-- >>> getHeaders example1
132+-- [("someheader","5")]
133+--
134+-- 2. A value that already has a header has its new header *prepended* to the
135+-- existing list:
136+--
137+-- >>> let example1 = addHeader 5 "hi" :: Headers '[Header "someheader" Int] String;
138+-- >>> let example2 = addHeader True example1 :: Headers '[Header "1st" Bool, Header "someheader" Int] String
139+-- >>> getHeaders example2
140+-- [("1st","true"),("someheader","5")]
141+--
142+-- Note that while in your handlers type annotations are not required, since
143+-- the type can be inferred from the API type, in other cases you may find
144+-- yourself needing to add annotations.
145+addHeader :: AddHeader h v orig new => v -> orig -> new
146+addHeader = addOptionalHeader . Header
147+
148+-- | Deliberately do not add a header to a value.
149+--
150+-- >>> let example1 = noHeader "hi" :: Headers '[Header "someheader" Int] String
151+-- >>> getHeaders example1
152+-- []
153+noHeader :: AddHeader h v orig new => orig -> new
154+noHeader = addOptionalHeader MissingHeader
122155
123156-- $setup
124157-- >>> import Servant.API