Added support for matrix parameters

servant.cabal

@@ -34,6 +34,7 @@ library
     Servant.API.Post
     Servant.API.Put
     Servant.API.QueryParam
+    Servant.API.MatrixParam
     Servant.API.Raw
     Servant.API.ReqBody
     Servant.API.Sub

src/Servant/API.hs

@@ -15,6 +15,8 @@ module Servant.API (
   module Servant.API.QueryParam,
   -- | Accessing the request body as a JSON-encoded type: @'ReqBody'@
   module Servant.API.ReqBody,
+  -- | Retrieving matrix parameters from the 'URI' segment: @'MatrixParam'@
+  module Servant.API.MatrixParam,
 
   -- * Actual endpoints, distinguished by HTTP method
   -- | GET requests
@@ -45,6 +47,7 @@ import Servant.API.Header ( Header )
 import Servant.API.Post ( Post )
 import Servant.API.Put ( Put )
 import Servant.API.QueryParam ( QueryFlag, QueryParams, QueryParam )
+import Servant.API.MatrixParam ( MatrixFlag, MatrixParams, MatrixParam )
 import Servant.API.Raw ( Raw )
 import Servant.API.ReqBody ( ReqBody )
 import Servant.API.Sub ( (:>)(..) )

src/Servant/API/MatrixParam.hs

@@ -0,0 +1,35 @@
+{-# LANGUAGE PolyKinds #-}
+module Servant.API.MatrixParam where
+
+-- | Lookup the value associated to the @sym@ matrix string parameter
+-- and try to extract it as a value of type @a@.
+--
+-- Example:
+--
+-- > -- /books;author=<author name>
+-- > type MyApi = "books" :> MatrixParam "author" Text :> Get [Book]
+data MatrixParam sym a
+
+-- | Lookup the values associated to the @sym@ matrix string parameter
+-- and try to extract it as a value of type @[a]@. This is typically
+-- meant to support matrix string parameters of the form
+-- @param[]=val1;param[]=val2@ and so on. Note that servant doesn't actually
+-- require the @[]@s and will fetch the values just fine with
+-- @param=val1;param=val2@, too.
+--
+-- Example:
+--
+-- > -- /books;authors[]=<author1>;authors[]=<author2>;...
+-- > type MyApi = "books" :> MatrixParams "authors" Text :> Get [Book]
+data MatrixParams sym a
+
+-- | Lookup a potentially value-less matrix string parameter
+-- with boolean semantics. If the param @sym@ is there without any value,
+-- or if it's there with value "true" or "1", it's interpreted as 'True'.
+-- Otherwise, it's interpreted as 'False'.
+--
+-- Example:
+--
+-- > -- /books;published
+-- > type MyApi = "books" :> MatrixFlag "published" :> Get [Book]
+data MatrixFlag sym