Yesod.Core.Dispatch

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.

mkYesodData but with custom options.

See mkYesodData.

See mkYesodDataOpts

Generate both YesodSubDispatch and YesodSubDispatchNested instances for a parameterized subsite. This is the subsite equivalent of using mkYesod for top-level sites.

Usage:

mkYesodSubDispatchInstance "(MyClass a) => MySub a" resourcesMySub

This generates:

1. A YesodSubDispatch instance using mkYesodSubDispatch

2. YesodSubDispatchNested instances for any nested route fragments

The generated instances quantify over the master site and constrain it only through the subsite's own class. For a parameterized subsite this normally means the subsite's class carries a subsite -> master functional dependency (so master is determined) and the using module enables UndecidableInstances (the instance contexts mention type-family applications and non-variable arguments), along with FlexibleContexts, FlexibleInstances, MultiParamTypeClasses and TypeFamilies. The nested route datatype must also declare exactly as many type parameters as the subsite has type arguments (see the arity note below).

Like mkYesodSubDispatchInstance, but takes a RouteOpts so a subsite can control nested-route generation — most usefully setNestedRouteFallthrough (which mkYesodSubDispatchInstance leaves at its default of False). The flag is threaded into both the yesodSubDispatch body (so the subsite's own top-level parent clauses fall through to later siblings on an inner miss) and the generated YesodSubDispatchNested fragment instances.

Generate a YesodSubDispatchNested instance for a nested route within a subsite, for hand-written split-route modules (see the subsite-splitting recipe in docs/split-route-compilation.md).

Takes the resources as [ResourceTree String] — exactly the form the parseRoutes quasi-quoter produces — and parses them to Type internally via parseResourceTypes, so the caller never touches the partial parseType/dropBracket. A malformed type fails the splice with an attributed error instead.

The type arguments of a route datatype, paired with the source Name each was derived from. A monomorphic site like App has NoTyArgs; a parameterized one like MySub subsite has SomeTyArgs.

Carrying the (non-)emptiness in the type — rather than as a bare list with a separate null check — keeps "are there type args?" and "what are they?" a single fact, so the populated branch hands you the NonEmpty directly.

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.

Default options for generating routes.

The defaults are:

• setEqDerived, setShowDerived, setReadDerived: True — derive Eq, Show and Read for the route datatype.

• setCreateResources: True — emit the resourcesSite :: [ResourceTree String] term.

• setParameterizedSubroute: False — subroutes are unparameterized.

• setFocusOnNestedRoute: unset — generate the whole route tree rather than focusing on a single nested route.

• setNestedRouteFallthrough: False — a nested route that fails to match throws notFound instead of falling through.

Use the set* functions to override individual fields.

When True, derive an Eq instance for the route datatype.

Default: True.

When True, derive a Show instance for the route datatype.

Default: True.

When True, derive a Read instance for the route datatype.

Default: True.

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.

Default: True.

If you set this with routeName, then the code generation will generate code for the routeName to be imported in the main dispatch class. This allows you to generate code in separate modules.

Example:

First, you would put your route definitions into their own file.

module App.Routes.Resources where

import Yesod.Core

appResources :: [ResourceTree String]
appResources = [parseRoutes|
    /  HomeR GET

    /nest NestR:
        /     NestIndexR GET POST
        /#Int NestShowR  GET POST

|]

We have defined a nested route called NestR here. A nested route is created with the : after the route name.

Then, in a module for the route specifically, we can generate the route datatype and instances for later hooking in to the main instance.

module App.Routes.NestR where

import App.Routes.Resources
import Yesod.Core

mkYesodOpts (setFocusOnNestedRoute NestR defaultOpts) App appResources

If you only want to generate the datatypes, you can separate things further using mkYesodDataOpts and mkYesodDispatchOpts.

Finally, import that type into your main yesod macro code.

module App where

import App.Routes.Resources (appResources)
import App.Routes.NestR (NestR(..))

mkYesod App appResources

The call to mkYesod will delegate to the generated code for NestR rather than regenerating it.

By default, defaultOpts starts unfocused (the whole route tree is generated). Use unsetFocusOnNestedRoute to clear a previously-set focus.

For a full walkthrough — including subsites, linking to nested routes, and why split sites should enable setNestedRouteFallthrough — see the guide at https://github.com/yesodweb/yesod/blob/master/yesod-core/docs/split-route-compilation.md.

Clear any nested-route focus set by setFocusOnNestedRoute, so that the whole route tree is generated.

defaultOpts already starts unfocused, so this is only needed to undo a previous setFocusOnNestedRoute.

If True, generate nested-discovery code (separate subroute datatypes and RenderRouteNested dispatch instances) for a parameterized/ site instead of the backwards-compatible inline output. The subroute datatypes then carry the parent site's type variables so that the ParentSite / ParentArgs associated types stay well-scoped.

Because the generated nested instances are parameterized over the site's type variables, the splice emits instance heads with non-variable arguments; a module using this typically needs FlexibleContexts, FlexibleInstances, MultiParamTypeClasses, TypeFamilies and, for a parameterized subsite whose master is determined by the subsite (a subsite -> master functional dependency on the user's class), UndecidableInstances.

Monomorphic sites always use nested discovery regardless of this flag; see discoveryMode.

Default: False.

When True, a nested route that fails to match falls through to the enclosing dispatch rather than throwing notFound. When False, a non-matching nested route throws notFound.

Default: False.

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.

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