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