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

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