From 839f5a79a9a538c516e03896656ebb16dea28e95 Mon Sep 17 00:00:00 2001
From: Daniel Larsson <daniel.j.larsson@gmail.com>
Date: Sun, 28 Dec 2014 22:56:58 +0100
Subject: [PATCH] Added support for matrix parameters

---
 servant.cabal                  |  1 +
 src/Servant/API.hs             |  3 +++
 src/Servant/API/MatrixParam.hs | 35 ++++++++++++++++++++++++++++++++++
 3 files changed, 39 insertions(+)
 create mode 100644 src/Servant/API/MatrixParam.hs

diff --git a/servant.cabal b/servant.cabal
index dce0d075..66d3c288 100644
--- a/servant.cabal
+++ b/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
diff --git a/src/Servant/API.hs b/src/Servant/API.hs
index 78b327a2..e30e3642 100644
--- a/src/Servant/API.hs
+++ b/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 ( (:>)(..) )
diff --git a/src/Servant/API/MatrixParam.hs b/src/Servant/API/MatrixParam.hs
new file mode 100644
index 00000000..5e826571
--- /dev/null
+++ b/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