yesod-core-1.6.28.1: Creation of type-safe, RESTful web applications.

Safe Haskell | None
Language | Haskell2010

Yesod.Core.Dispatch

Contents

- Quasi-quoted routing
  - More fine-grained
    - Route generation options
    - Helpers
  - Path pieces
- Convert to WAI
- WAI subsites

Synopsis

- parseRoutes :: QuasiQuoter
- parseRoutesNoCheck :: QuasiQuoter
- parseRoutesFile :: FilePath -> Q Exp
- parseRoutesFileNoCheck :: FilePath -> Q Exp
- mkYesod :: String -> [ResourceTree String] -> Q [Dec]
- mkYesodOpts :: RouteOpts -> String -> [ResourceTree String] -> Q [Dec]
- mkYesodWith :: [[String]] -> String -> [String] -> [ResourceTree String] -> Q [Dec]
- mkYesodData :: String -> [ResourceTree String] -> Q [Dec]
- mkYesodDataOpts :: RouteOpts -> String -> [ResourceTree String] -> Q [Dec]
- mkYesodSubData :: String -> [ResourceTree String] -> Q [Dec]
- mkYesodSubDataOpts :: RouteOpts -> String -> [ResourceTree String] -> Q [Dec]
- mkYesodDispatch :: String -> [ResourceTree String] -> Q [Dec]
- mkYesodDispatchOpts :: RouteOpts -> String -> [ResourceTree String] -> Q [Dec]
- mkYesodSubDispatch :: [ResourceTree a] -> Q Exp
- data RouteOpts
- defaultOpts :: RouteOpts
- setEqDerived :: Bool -> RouteOpts -> RouteOpts
- setShowDerived :: Bool -> RouteOpts -> RouteOpts
- setReadDerived :: Bool -> RouteOpts -> RouteOpts
- setCreateResources :: Bool -> RouteOpts -> RouteOpts
- setParameterizedSubroute :: Bool -> RouteOpts -> RouteOpts
- defaultGen :: IO Int
- getGetMaxExpires :: IO (IO Text)
- class PathPiece s where
  - fromPathPiece :: Text -> Maybe s
  - toPathPiece :: s -> Text
- class PathMultiPiece s where
  - fromPathMultiPiece :: [Text] -> Maybe s
  - toPathMultiPiece :: s -> [Text]
- type Texts = [Text]
- toWaiApp :: YesodDispatch site => site -> IO Application
- toWaiAppPlain :: YesodDispatch site => site -> IO Application
- toWaiAppYre :: YesodDispatch site => YesodRunnerEnv site -> Application
- warp :: YesodDispatch site => Int -> site -> IO ()
- warpDebug :: YesodDispatch site => Int -> site -> IO ()
- warpEnv :: YesodDispatch site => site -> IO ()
- mkDefaultMiddlewares :: Logger -> IO Middleware
- defaultMiddlewaresNoLogging :: Middleware
- newtype WaiSubsite = WaiSubsite {
  - runWaiSubsite :: Application
  }
- newtype WaiSubsiteWithAuth = WaiSubsiteWithAuth {
  - runWaiSubsiteWithAuth :: Application
  }

# Quasi-quoted routing

parseRoutes :: QuasiQuoter Source #

A quasi-quoter to parse a string into a list of `Resource`s. Checks for overlapping routes, failing if present; use `parseRoutesNoCheck` to skip the checking. See documentation site for details on syntax.

parseRoutesNoCheck :: QuasiQuoter Source #

Same as `parseRoutes`, but performs no overlap checking.

parseRoutesFile :: FilePath -> Q Exp Source #

Same as `parseRoutes`, but uses an external file instead of quasiquotation.

The recommended file extension is `.yesodroutes`.

parseRoutesFileNoCheck :: FilePath -> Q Exp Source #

Same as `parseRoutesNoCheck`, but uses an external file instead of quasiquotation.

The recommended file extension is `.yesodroutes`.

mkYesod Source #

Arguments

:: String | name of the argument datatype
-> [ResourceTree String] |
-> Q [Dec] |

Generates URL datatype and site function for the given `Resource`s. This is used for creating sites, not subsites. See `mkYesodSubData` and `mkYesodSubDispatch` for the latter. Use `parseRoutes` to create the `Resource`s.

Contexts and type variables in the name of the datatype are parsed. For example, a datatype `App a` with typeclass constraint `MyClass a` can be written as `"(MyClass a) => App a"`.

mkYesodOpts :: RouteOpts -> String -> [ResourceTree String] -> Q [Dec] Source #

`mkYesod` but with custom options.

Since: 1.6.25.0

mkYesodWith Source #

Arguments

:: [[String]] | list of contexts
-> String | name of the argument datatype
-> [String] | list of type variables
-> [ResourceTree String] |
-> Q [Dec] |

Deprecated: Contexts and type variables are now parsed from the name in `mkYesod`. https://github.com/yesodweb/yesod/pull/1366

Similar to `mkYesod`, except contexts and type variables are not parsed. Instead, they are explicitly provided. You can write `(MyClass a) => App a` with `mkYesodWith [["MyClass","a"]] "App" ["a"] ...`.

## More fine-grained

mkYesodData :: String -> [ResourceTree String] -> Q [Dec] Source #

Sometimes, you will want to declare your routes in one file and define your handlers elsewhere. For example, this is the only way to break up a monolithic file into smaller parts. Use this function, paired with `mkYesodDispatch`, to do just that.

mkYesodDataOpts :: RouteOpts -> String -> [ResourceTree String] -> Q [Dec] Source #

`mkYesodData` but with custom options.

Since: 1.6.25.0

mkYesodSubData :: String -> [ResourceTree String] -> Q [Dec] Source #

mkYesodSubDataOpts :: RouteOpts -> String -> [ResourceTree String] -> Q [Dec] Source #

Since: 1.6.25.0

mkYesodDispatch :: String -> [ResourceTree String] -> Q [Dec] Source #

See `mkYesodData`.

mkYesodDispatchOpts :: RouteOpts -> String -> [ResourceTree String] -> Q [Dec] Source #

See `mkYesodDataOpts`

Since: 1.6.25.0

mkYesodSubDispatch :: [ResourceTree a] -> Q Exp Source #

### Route generation options

data RouteOpts Source #

General opts data type for generating yesod.

Contains options for customizing code generation for the router in `mkYesodData`, including what type class instances will be derived for the route datatype, whether to parameterize subroutes, and whether or not to create the `resources :: [ResourceTree String]` value. Use the setting functions on `defaultOpts` to set specific fields.

Since: 1.6.25.0

defaultOpts :: RouteOpts Source #

Default options for generating routes.

Defaults to all instances derived, subroutes being unparameterized, and to create the `resourcesSite :: [ResourceTree String]` term.

Since: 1.6.25.0

setEqDerived :: Bool -> RouteOpts -> RouteOpts Source #

Since: 1.6.25.0

setShowDerived :: Bool -> RouteOpts -> RouteOpts Source #

Since: 1.6.25.0

setReadDerived :: Bool -> RouteOpts -> RouteOpts Source #

Since: 1.6.25.0

setCreateResources :: Bool -> RouteOpts -> RouteOpts Source #

Determine whether or not to generate the `resourcesApp` value.

Disabling this can be useful if you are creating the `routes :: [ResourceTree String]` elsewhere in your module, and referring to it here. The `resourcesApp` can become very large in large applications, and duplicating it can result in signifiacntly higher compile times.

Since: 1.6.28.0

setParameterizedSubroute :: Bool -> RouteOpts -> RouteOpts Source #

If True, we will correctly pass parameters for subroutes around.

Since: 1.6.28.0

### Helpers

defaultGen :: IO Int Source #

Generate a random number uniformly distributed in the full range of `Int`.

Note: Before 1.6.20, this generates pseudo-random number in an unspecified range. The range size may not be a power of 2. Since 1.6.20, this uses a secure entropy source and generates in the full range of `Int`.

Since: 1.6.21.0

getGetMaxExpires :: IO (IO Text) Source #

Default constructor for `yreGetMaxExpires` field. Low level function for simple manual construction of `YesodRunnerEnv`.

Since: 1.4.29

## Path pieces

class PathPiece s where Source #

Methods

fromPathPiece :: Text -> Maybe s Source #

toPathPiece :: s -> Text Source #

#### Instances

Instances details

PathPiece Int16 |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Int16 Source # toPathPiece :: Int16 -> Text Source #
PathPiece Int32 |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Int32 Source # toPathPiece :: Int32 -> Text Source #
PathPiece Int64 |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Int64 Source # toPathPiece :: Int64 -> Text Source #
PathPiece Int8 |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Int8 Source # toPathPiece :: Int8 -> Text Source #
PathPiece Word16 |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Word16 Source # toPathPiece :: Word16 -> Text Source #
PathPiece Word32 |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Word32 Source # toPathPiece :: Word32 -> Text Source #
PathPiece Word64 |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Word64 Source # toPathPiece :: Word64 -> Text Source #
PathPiece Word8 |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Word8 Source # toPathPiece :: Word8 -> Text Source #
PathPiece Text |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Text Source # toPathPiece :: Text -> Text Source #
PathPiece Text |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Text Source # toPathPiece :: Text -> Text Source #
PathPiece Day |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Day Source # toPathPiece :: Day -> Text Source #
PathPiece Integer |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Integer Source # toPathPiece :: Integer -> Text Source #
PathPiece String |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe String Source # toPathPiece :: String -> Text Source #
PathPiece () |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe () Source # toPathPiece :: () -> Text Source #
PathPiece Bool |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Bool Source # toPathPiece :: Bool -> Text Source #
PathPiece Int |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Int Source # toPathPiece :: Int -> Text Source #
PathPiece Word |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe Word Source # toPathPiece :: Word -> Text Source #
PathPiece a => PathPiece (Maybe a) |
Instance details Defined in Web.PathPieces Methods fromPathPiece :: Text -> Maybe (Maybe a) Source # toPathPiece :: Maybe a -> Text Source #

class PathMultiPiece s where Source #

Methods

fromPathMultiPiece :: [Text] -> Maybe s Source #

toPathMultiPiece :: s -> [Text] Source #

#### Instances

Instances details

PathPiece a => PathMultiPiece [a] |
Instance details Defined in Web.PathPieces Methods fromPathMultiPiece :: [Text] -> Maybe [a] Source # toPathMultiPiece :: [a] -> [Text] Source #

type Texts = [Text] Source #

# Convert to WAI

toWaiApp :: YesodDispatch site => site -> IO Application Source #

Same as `toWaiAppPlain`, but provides a default set of middlewares. This set may change with future releases, but currently covers:

- Logging
- GZIP compression
- Automatic HEAD method handling
- Request method override with the _method query string parameter
- Accept header override with the _accept query string parameter

toWaiAppPlain :: YesodDispatch site => site -> IO Application Source #

Convert the given argument into a WAI application, executable with any WAI handler. This function will provide no middlewares; if you want commonly used middlewares, please use `toWaiApp`.

toWaiAppYre :: YesodDispatch site => YesodRunnerEnv site -> Application Source #

Pure low level function to construct WAI application. Usefull when you need not standard way to run your app, or want to embed it inside another app.

Since: 1.4.29

warp :: YesodDispatch site => Int -> site -> IO () Source #

A convenience method to run an application using the Warp webserver on the specified port. Automatically calls `toWaiApp`. Provides a default set of middlewares. This set may change at any point without a breaking version number. Currently, it includes:

- Logging
- GZIP compression
- Automatic HEAD method handling
- Request method override with the _method query string parameter
- Accept header override with the _accept query string parameter

If you need more fine-grained control of middlewares, please use `toWaiApp` directly.

Since 1.2.0

warpDebug :: YesodDispatch site => Int -> site -> IO () Source #

Deprecated: Please use warp instead

Deprecated synonym for `warp`.

warpEnv :: YesodDispatch site => site -> IO () Source #

Runs your application using default middlewares (i.e., via `toWaiApp`). It reads port information from the PORT environment variable, as used by tools such as Keter and the FP Complete School of Haskell.

Note that the exact behavior of this function may be modified slightly over time to work correctly with external tools, without a change to the type signature.

mkDefaultMiddlewares :: Logger -> IO Middleware Source #

A default set of middlewares.

Since 1.2.0

defaultMiddlewaresNoLogging :: Middleware Source #

All of the default middlewares, excluding logging.

Since 1.2.12

# WAI subsites

newtype WaiSubsite Source #

Wrap up a normal WAI application as a Yesod subsite. Ignore parent site's middleware and isAuthorized.

Constructors

WaiSubsite |

Fields

- runWaiSubsite :: Application

#### Instances

Instances details

ParseRoute WaiSubsite Source # |
Instance details Defined in Yesod.Core.Types Methods parseRoute :: ([Text], [(Text, Text)]) -> Maybe (Route WaiSubsite) Source #
RenderRoute WaiSubsite Source # |

Instance details

Defined in Yesod.Core.Types

Associated Types

data Route WaiSubsite |
Instance details Defined in Yesod.Core.Types data Route WaiSubsite = WaiSubsiteRoute [Text] [(Text, Text)]

Methods

renderRoute :: Route WaiSubsite -> ([Text], [(Text, Text)]) Source #

YesodSubDispatch WaiSubsite master Source # |
Instance details Defined in Yesod.Core.Class.Dispatch Methods yesodSubDispatch :: YesodSubRunnerEnv WaiSubsite master -> Application Source #
Read (Route WaiSubsite) Source # |
Instance details Defined in Yesod.Core.Types Methods readsPrec :: Int -> ReadS (Route WaiSubsite) Source # readList :: ReadS [Route WaiSubsite] Source # readPrec :: ReadPrec (Route WaiSubsite) Source # readListPrec :: ReadPrec [Route WaiSubsite] Source #
Show (Route WaiSubsite) Source # |
Instance details Defined in Yesod.Core.Types Methods showsPrec :: Int -> Route WaiSubsite -> ShowS Source # show :: Route WaiSubsite -> String Source # showList :: [Route WaiSubsite] -> ShowS Source #
Eq (Route WaiSubsite) Source # |
Instance details Defined in Yesod.Core.Types Methods (==) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source # (/=) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #
Ord (Route WaiSubsite) Source # |

Instance details

Defined in Yesod.Core.Types

Methods

compare :: Route WaiSubsite -> Route WaiSubsite -> Ordering Source #

(<) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #

(<=) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #

(>) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #

(>=) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #

max :: Route WaiSubsite -> Route WaiSubsite -> Route WaiSubsite Source #

min :: Route WaiSubsite -> Route WaiSubsite -> Route WaiSubsite Source #

data Route WaiSubsite Source # |
Instance details Defined in Yesod.Core.Types data Route WaiSubsite = WaiSubsiteRoute [Text] [(Text, Text)]

newtype WaiSubsiteWithAuth Source #

Like `WaiSubsite`, but applies parent site's middleware and isAuthorized.

Since: 1.4.34

Constructors

WaiSubsiteWithAuth |

Fields

- runWaiSubsiteWithAuth :: Application

#### Instances

Instances details

ParseRoute WaiSubsiteWithAuth Source # |
Instance details Defined in Yesod.Core.Types Methods parseRoute :: ([Text], [(Text, Text)]) -> Maybe (Route WaiSubsiteWithAuth) Source #
RenderRoute WaiSubsiteWithAuth Source # |

Instance details

Defined in Yesod.Core.Types

Associated Types

data Route WaiSubsiteWithAuth |
Instance details Defined in Yesod.Core.Types data Route WaiSubsiteWithAuth = WaiSubsiteWithAuthRoute [Text] [(Text, Text)]

Methods

renderRoute :: Route WaiSubsiteWithAuth -> ([Text], [(Text, Text)]) Source #

YesodSubDispatch WaiSubsiteWithAuth master Source # |
Instance details Defined in Yesod.Core.Class.Dispatch Methods yesodSubDispatch :: YesodSubRunnerEnv WaiSubsiteWithAuth master -> Application Source #
Read (Route WaiSubsiteWithAuth) Source # |
Instance details Defined in Yesod.Core.Types Methods readsPrec :: Int -> ReadS (Route WaiSubsiteWithAuth) Source # readList :: ReadS [Route WaiSubsiteWithAuth] Source # readPrec :: ReadPrec (Route WaiSubsiteWithAuth) Source # readListPrec :: ReadPrec [Route WaiSubsiteWithAuth] Source #
Show (Route WaiSubsiteWithAuth) Source # |
Instance details Defined in Yesod.Core.Types Methods showsPrec :: Int -> Route WaiSubsiteWithAuth -> ShowS Source # show :: Route WaiSubsiteWithAuth -> String Source # showList :: [Route WaiSubsiteWithAuth] -> ShowS Source #
Eq (Route WaiSubsiteWithAuth) Source # |
Instance details Defined in Yesod.Core.Types Methods (==) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source # (/=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #
Ord (Route WaiSubsiteWithAuth) Source # |

Instance details

Defined in Yesod.Core.Types

Methods

compare :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Ordering Source #

(<) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #

(<=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #

(>) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #

(>=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #

max :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth Source #

min :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth Source #

data Route WaiSubsiteWithAuth Source # |
Instance details Defined in Yesod.Core.Types data Route WaiSubsiteWithAuth = WaiSubsiteWithAuthRoute [Text] [(Text, Text)]