diff --git a/README.md b/README.md
index ebe05357..c6785aea 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ import Web.Scotty
main = scotty 3000 $
get "/:word" $ do
- beam <- captureParam "word"
+ beam <- pathParam "word"
html $ mconcat ["
Scotty, ", beam, " me up!
"]
```
diff --git a/Web/Scotty.hs b/Web/Scotty.hs
index 9c273380..479bb229 100644
--- a/Web/Scotty.hs
+++ b/Web/Scotty.hs
@@ -19,9 +19,9 @@ module Web.Scotty
-- ** Accessing the Request, Captures, and Query Parameters
, request, header, headers, body, bodyReader
, param, params
- , captureParam, formParam, queryParam
- , captureParamMaybe, formParamMaybe, queryParamMaybe
- , captureParams, formParams, queryParams
+ , pathParam, captureParam, formParam, queryParam
+ , pathParamMaybe, captureParamMaybe, formParamMaybe, queryParamMaybe
+ , pathParams, captureParams, formParams, queryParams
, jsonData, files
-- ** Modifying the Response and Redirecting
, status, addHeader, setHeader, redirect
@@ -141,12 +141,12 @@ throw = Trans.throw
-- ever run is if the first one calls 'next'.
--
-- > get "/foo/:bar" $ do
--- > w :: Text <- captureParam "bar"
+-- > w :: Text <- pathParam "bar"
-- > unless (w == "special") next
-- > text "You made a request to /foo/special"
-- >
-- > get "/foo/:baz" $ do
--- > w <- captureParam "baz"
+-- > w <- pathParam "baz"
-- > text $ "You made a request to: " <> w
next :: ActionM ()
next = Trans.next
@@ -158,7 +158,7 @@ next = Trans.next
-- content the text message.
--
-- > get "/foo/:bar" $ do
--- > w :: Text <- captureParam "bar"
+-- > w :: Text <- pathParam "bar"
-- > unless (w == "special") finish
-- > text "You made a request to /foo/special"
--
@@ -228,17 +228,21 @@ jsonData = Trans.jsonData
-- capture cannot be parsed.
param :: Trans.Parsable a => Text -> ActionM a
param = Trans.param . toStrict
-{-# DEPRECATED param "(#204) Not a good idea to treat all parameters identically. Use captureParam, formParam and queryParam instead. "#-}
+{-# DEPRECATED param "(#204) Not a good idea to treat all parameters identically. Use pathParam, formParam and queryParam instead. "#-}
--- | Get a capture parameter.
+-- | Synonym for 'pathParam'
+captureParam :: Trans.Parsable a => Text -> ActionM a
+captureParam = Trans.captureParam . toStrict
+
+-- | Get a path parameter.
--
-- * Raises an exception which can be caught by 'catch' if parameter is not found. If the exception is not caught, scotty will return a HTTP error code 500 ("Internal Server Error") to the client.
--
-- * If the parameter is found, but 'parseParam' fails to parse to the correct type, 'next' is called.
--
--- /Since: 0.20/
-captureParam :: Trans.Parsable a => Text -> ActionM a
-captureParam = Trans.captureParam . toStrict
+-- /Since: 0.21/
+pathParam :: Trans.Parsable a => Text -> ActionM a
+pathParam = Trans.pathParam . toStrict
-- | Get a form parameter.
--
@@ -261,14 +265,18 @@ queryParam :: Trans.Parsable a => Text -> ActionM a
queryParam = Trans.queryParam . toStrict
--- | Look up a capture parameter. Returns 'Nothing' if the parameter is not found or cannot be parsed at the right type.
+-- | Look up a path parameter. Returns 'Nothing' if the parameter is not found or cannot be parsed at the right type.
--
-- NB : Doesn't throw exceptions. In particular, route pattern matching will not continue, so developers
-- must 'raiseStatus' or 'throw' to signal something went wrong.
--
-- /Since: FIXME/
+pathParamMaybe :: (Trans.Parsable a) => Text -> ActionM (Maybe a)
+pathParamMaybe = Trans.pathParamMaybe . toStrict
+
+-- | Synonym for 'pathParamMaybe'
captureParamMaybe :: (Trans.Parsable a) => Text -> ActionM (Maybe a)
-captureParamMaybe = Trans.captureParamMaybe . toStrict
+captureParamMaybe = Trans.pathParamMaybe . toStrict
-- | Look up a form parameter. Returns 'Nothing' if the parameter is not found or cannot be parsed at the right type.
--
@@ -289,14 +297,17 @@ queryParamMaybe = Trans.queryParamMaybe . toStrict
--- | Get all parameters from capture, form and query (in that order).
+-- | Get all parameters from path, form and query (in that order).
params :: ActionM [Param]
params = Trans.params
-{-# DEPRECATED params "(#204) Not a good idea to treat all parameters identically. Use captureParams, formParams and queryParams instead. "#-}
+{-# DEPRECATED params "(#204) Not a good idea to treat all parameters identically. Use pathParams, formParams and queryParams instead. "#-}
--- | Get capture parameters
+-- | Synonym for 'pathParams'
captureParams :: ActionM [Param]
captureParams = Trans.captureParams
+-- | Get path parameters
+pathParams :: ActionM [Param]
+pathParams = Trans.pathParams
-- | Get form parameters
formParams :: ActionM [Param]
formParams = Trans.formParams
diff --git a/Web/Scotty/Action.hs b/Web/Scotty/Action.hs
index 5ec257e2..6e205289 100644
--- a/Web/Scotty/Action.hs
+++ b/Web/Scotty/Action.hs
@@ -22,13 +22,16 @@ module Web.Scotty.Action
, jsonData
, next
, param
+ , pathParam
, captureParam
, formParam
, queryParam
+ , pathParamMaybe
, captureParamMaybe
, formParamMaybe
, queryParamMaybe
, params
+ , pathParams
, captureParams
, formParams
, queryParams
@@ -169,12 +172,12 @@ throw = E.throw
-- ever run is if the first one calls 'next'.
--
-- > get "/foo/:bar" $ do
--- > w :: Text <- captureParam "bar"
+-- > w :: Text <- pathParam "bar"
-- > unless (w == "special") next
-- > text "You made a request to /foo/special"
-- >
-- > get "/foo/:baz" $ do
--- > w <- captureParam "baz"
+-- > w <- pathParam "baz"
-- > text $ "You made a request to: " <> w
next :: Monad m => ActionT m a
next = E.throw AENext
@@ -286,15 +289,19 @@ param k = do
Just v -> either (const next) return $ parseParam (TL.fromStrict v)
{-# DEPRECATED param "(#204) Not a good idea to treat all parameters identically. Use captureParam, formParam and queryParam instead. "#-}
--- | Look up a capture parameter.
+-- | Synonym for 'pathParam'
+captureParam :: (Parsable a, Monad m) => T.Text -> ActionT m a
+captureParam = pathParam
+
+-- | Look up a path parameter.
--
-- * Raises an exception which can be caught by 'catch' if parameter is not found. If the exception is not caught, scotty will return a HTTP error code 500 ("Internal Server Error") to the client.
--
-- * If the parameter is found, but 'parseParam' fails to parse to the correct type, 'next' is called.
--
-- /Since: 0.20/
-captureParam :: (Parsable a, Monad m) => T.Text -> ActionT m a
-captureParam = paramWith CaptureParam envCaptureParams status500
+pathParam :: (Parsable a, Monad m) => T.Text -> ActionT m a
+pathParam = paramWith PathParam envPathParams status500
-- | Look up a form parameter.
@@ -317,6 +324,15 @@ formParam = paramWith FormParam envFormParams status400
queryParam :: (Parsable a, Monad m) => T.Text -> ActionT m a
queryParam = paramWith QueryParam envQueryParams status400
+-- | Look up a path parameter. Returns 'Nothing' if the parameter is not found or cannot be parsed at the right type.
+--
+-- NB : Doesn't throw exceptions. In particular, route pattern matching will not continue, so developers
+-- must 'raiseStatus' or 'throw' to signal something went wrong.
+--
+-- /Since: FIXME/
+pathParamMaybe :: (Parsable a, Monad m) => T.Text -> ActionT m (Maybe a)
+pathParamMaybe = paramWithMaybe envPathParams
+
-- | Look up a capture parameter. Returns 'Nothing' if the parameter is not found or cannot be parsed at the right type.
--
-- NB : Doesn't throw exceptions. In particular, route pattern matching will not continue, so developers
@@ -324,7 +340,7 @@ queryParam = paramWith QueryParam envQueryParams status400
--
-- /Since: FIXME/
captureParamMaybe :: (Parsable a, Monad m) => T.Text -> ActionT m (Maybe a)
-captureParamMaybe = paramWithMaybe envCaptureParams
+captureParamMaybe = paramWithMaybe envPathParams
-- | Look up a form parameter. Returns 'Nothing' if the parameter is not found or cannot be parsed at the right type.
--
@@ -342,12 +358,12 @@ formParamMaybe = paramWithMaybe envFormParams
queryParamMaybe :: (Parsable a, Monad m) => T.Text -> ActionT m (Maybe a)
queryParamMaybe = paramWithMaybe envQueryParams
-data ParamType = CaptureParam
+data ParamType = PathParam
| FormParam
| QueryParam
instance Show ParamType where
show = \case
- CaptureParam -> "capture"
+ PathParam -> "path"
FormParam -> "form"
QueryParam -> "query"
@@ -363,7 +379,7 @@ paramWith ty f err k = do
Nothing -> raiseStatus err (T.unwords [T.pack (show ty), "parameter:", k, "not found!"])
Just v ->
let handleParseError = \case
- CaptureParam -> next
+ PathParam -> next
_ -> raiseStatus err (T.unwords ["Cannot parse", v, "as a", T.pack (show ty), "parameter"])
in either (const $ handleParseError ty) return $ parseParam $ TL.fromStrict v
@@ -382,14 +398,19 @@ paramWithMaybe f k = do
Nothing -> pure Nothing
Just v -> either (const $ pure Nothing) (pure . Just) $ parseParam $ TL.fromStrict v
--- | Get all parameters from capture, form and query (in that order).
+-- | Get all parameters from path, form and query (in that order).
params :: Monad m => ActionT m [Param]
params = paramsWith getParams
-{-# DEPRECATED params "(#204) Not a good idea to treat all parameters identically. Use captureParams, formParams and queryParams instead. "#-}
+{-# DEPRECATED params "(#204) Not a good idea to treat all parameters identically. Use pathParams, formParams and queryParams instead. "#-}
+
+-- | Get path parameters
+pathParams :: Monad m => ActionT m [Param]
+pathParams = paramsWith envPathParams
--- | Get capture parameters
+-- | Get path parameters
captureParams :: Monad m => ActionT m [Param]
-captureParams = paramsWith envCaptureParams
+captureParams = paramsWith envPathParams
+
-- | Get form parameters
formParams :: Monad m => ActionT m [Param]
formParams = paramsWith envFormParams
@@ -402,7 +423,7 @@ paramsWith f = ActionT (f <$> ask)
{-# DEPRECATED getParams "(#204) Not a good idea to treat all parameters identically" #-}
getParams :: ActionEnv -> [Param]
-getParams e = envCaptureParams e <> envFormParams e <> envQueryParams e
+getParams e = envPathParams e <> envFormParams e <> envQueryParams e
-- === access the fields of the Response being constructed
diff --git a/Web/Scotty/Internal/Types.hs b/Web/Scotty/Internal/Types.hs
index baa2f5f4..f397e707 100644
--- a/Web/Scotty/Internal/Types.hs
+++ b/Web/Scotty/Internal/Types.hs
@@ -156,7 +156,7 @@ type Param = (Text, Text)
type File = (Text, FileInfo LBS8.ByteString)
data ActionEnv = Env { envReq :: Request
- , envCaptureParams :: [Param]
+ , envPathParams :: [Param]
, envFormParams :: [Param]
, envQueryParams :: [Param]
, envBody :: IO LBS8.ByteString
diff --git a/Web/Scotty/Trans.hs b/Web/Scotty/Trans.hs
index 3c4a6a7d..65dda7be 100644
--- a/Web/Scotty/Trans.hs
+++ b/Web/Scotty/Trans.hs
@@ -24,9 +24,9 @@ module Web.Scotty.Trans
-- ** Accessing the Request, Captures, and Query Parameters
, request, Lazy.header, Lazy.headers, body, bodyReader
, param, params
- , captureParam, formParam, queryParam
- , captureParamMaybe, formParamMaybe, queryParamMaybe
- , captureParams, formParams, queryParams
+ , pathParam, captureParam, formParam, queryParam
+ , pathParamMaybe, captureParamMaybe, formParamMaybe, queryParamMaybe
+ , pathParams, captureParams, formParams, queryParams
, jsonData, files
-- ** Modifying the Response and Redirecting
, status, Lazy.addHeader, Lazy.setHeader, Lazy.redirect
diff --git a/changelog.md b/changelog.md
index 5d8d3aa6..a92f7ca6 100644
--- a/changelog.md
+++ b/changelog.md
@@ -5,6 +5,7 @@
* deprecate `rescue` and `liftAndCatchIO`
* add `Web.Scotty.Trans.Strict` and `Web.Scotty.Trans.Lazy`
* Reverted the `MonadReader` instance of `ActionT` so that it inherits the base monad
+* renamed `captureParam`, `captureParamMaybe`, and `captureParams` to `pathParam`, `pathParamMaybe`, `pathParams` respectively, keeping the old names as their synonyms
## 0.20.1 [2023.10.03]
diff --git a/examples/basic.hs b/examples/basic.hs
index 5bde742d..c489bdfd 100644
--- a/examples/basic.hs
+++ b/examples/basic.hs
@@ -38,7 +38,7 @@ main = scotty 3000 $ do
-- Using a parameter in the query string. Since it has
-- not been given, a 500 page is generated.
get "/foo" $ do
- v <- captureParam "fooparam"
+ v <- pathParam "fooparam"
html $ mconcat ["", v, "
"]
-- An uncaught error becomes a 500 page.
@@ -64,7 +64,7 @@ main = scotty 3000 $ do
-- any string, and capture that value as a parameter.
-- URL captures take precedence over query string parameters.
get "/foo/:bar/required" $ do
- v <- captureParam "bar"
+ v <- pathParam "bar"
html $ mconcat ["", v, "
"]
-- Files are streamed directly to the client.
@@ -81,7 +81,7 @@ main = scotty 3000 $ do
json $ take 20 $ randomRs (1::Int,100) g
get "/ints/:is" $ do
- is <- captureParam "is"
+ is <- pathParam "is"
json $ [(1::Int)..10] ++ is
get "/setbody" $ do
diff --git a/examples/cookies.hs b/examples/cookies.hs
index cd13dc36..7820c87b 100644
--- a/examples/cookies.hs
+++ b/examples/cookies.hs
@@ -33,7 +33,7 @@ main = scotty 3000 $ do
H.input H.! type_ "submit" H.! value "set a cookie"
post "/set-a-cookie" $ do
- name' <- captureParam "name"
- value' <- captureParam "value"
+ name' <- pathParam "name"
+ value' <- pathParam "value"
setSimpleCookie name' value'
redirect "/"
diff --git a/examples/exceptions.hs b/examples/exceptions.hs
index 3afa8f09..4faf1a69 100644
--- a/examples/exceptions.hs
+++ b/examples/exceptions.hs
@@ -49,7 +49,7 @@ main = scottyT 3000 id $ do -- note, we aren't using any additional transformer
]
get "/switch/:val" $ do
- v <- captureParam "val"
+ v <- pathParam "val"
_ <- if even v then throw Forbidden else throw (NotFound v)
text "this will never be reached"
diff --git a/examples/urlshortener.hs b/examples/urlshortener.hs
index d171eb1d..d27c3b42 100644
--- a/examples/urlshortener.hs
+++ b/examples/urlshortener.hs
@@ -49,7 +49,7 @@ main = do
H.input H.! type_ "submit"
post "/shorten" $ do
- url <- captureParam "url"
+ url <- formParam "url"
liftIO $ modifyMVar_ m $ \(i,db) -> return (i+1, M.insert i (T.pack url) db)
redirect "/list"
diff --git a/scotty.cabal b/scotty.cabal
index 808d4331..97b2cd12 100644
--- a/scotty.cabal
+++ b/scotty.cabal
@@ -22,7 +22,7 @@ Description:
.
main = scotty 3000 $
get "/:word" $ do
- beam <- captureParam "word"
+ beam <- pathParam "word"
html $ mconcat ["<h1>Scotty, ", beam, " me up!</h1>"]
@
.