Use "pathParam" instead of "captureParam" to refer to path parameters

README.md

@@ -8,7 +8,7 @@ import Web.Scotty
 
 main = scotty 3000 $
     get "/:word" $ do
-        beam <- captureParam "word"
+        beam <- pathParam "word"
         html $ mconcat ["<h1>Scotty, ", beam, " me up!</h1>"]
 ```
 

Web/Scotty.hs

@@ -19,9 +19,9 @@
       -- ** 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 @@
 -- 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 @@
 -- 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"
 --
@@ -170,12 +170,12 @@
 --
 -- > raise JustKidding `catch` (\msg -> text msg)
 rescue :: E.Exception e => ActionM a -> (e -> ActionM a) -> ActionM a
 rescue = Trans.rescue
 {-# DEPRECATED rescue "Use catch instead" #-}
 
 -- | Like 'liftIO', but catch any IO exceptions and turn them into Scotty exceptions.
 liftAndCatchIO :: IO a -> ActionM a
 liftAndCatchIO = Trans.liftAndCatchIO
 {-# DEPRECATED liftAndCatchIO "Use liftIO instead" #-}
 
 -- | Redirect to given URL. Like throwing an uncatchable exception. Any code after the call to redirect
@@ -227,18 +227,22 @@
 --   This means captures are somewhat typed, in that a route won't match if a correctly typed
 --   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.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 @@
 
 
 
--- | 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

Web/Scotty/Action.hs

@@ -22,13 +22,16 @@
     , jsonData
     , next
     , param
+    , pathParam
     , captureParam
     , formParam
     , queryParam
+    , pathParamMaybe
     , captureParamMaybe
     , formParamMaybe
     , queryParamMaybe
     , params
+    , pathParams
     , captureParams
     , formParams
     , queryParams
@@ -89,7 +92,7 @@
 import           Numeric.Natural
 
 import           Web.Scotty.Internal.Types
 import           Web.Scotty.Util (mkResponse, addIfNotPresent, add, replace, lazyTextToStrictByteString, decodeUtf8Lenient)
 import           UnliftIO.Exception (Handler(..), catch, catches)
 
 import Network.Wai.Internal (ResponseReceived(..))
@@ -169,12 +172,12 @@
 -- 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 @@
         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,14 +324,23 @@
 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
 -- must 'raiseStatus' or 'throw' to signal something went wrong.
 --
 -- /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 @@
 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 @@
       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 @@
       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 @@
 
 {-# 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

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

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

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]
 

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 ["<h1>", v, "</h1>"]
 
     -- 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 ["<h1>", v, "</h1>"]
 
     -- 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

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 "/"

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"
 

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"
 

scotty.cabal

@@ -22,7 +22,7 @@ Description:
     .
     main = scotty 3000 $
       get "/:word" $ do
-    &#32;&#32;&#32;&#32;beam <- captureParam &#34;word&#34;
+    &#32;&#32;&#32;&#32;beam <- pathParam &#34;word&#34;
     &#32;&#32;&#32;&#32;html $ mconcat [&#34;&#60;h1&#62;Scotty, &#34;, beam, &#34; me up!&#60;/h1&#62;&#34;]
   @
   .