Web.Route.Invertible.Internal

This module exposes more of the inner workings of route construction for extensiblity and direct access. You may need interfaces like IsMethod or QueryParams to add support for a new web framework, for example. In particular, functions like foldRoute and pathValues can be used to extract low-level information about individual routes.

General

class (Eq s, IsString s, Hashable s, Monoid s) => RouteString s where

Representions of request data that can be used in routing

Methods

toString :: s -> String

Must be the inverse of fromString

Instances

RouteString String

Defined in Web.Route.Invertible.String

Methods

toString :: String -> String

RouteString ByteString

Defined in Web.Route.Invertible.String

Methods

toString :: ByteString -> String

RouteString Text

Defined in Web.Route.Invertible.String

Methods

toString :: Text -> String

data Placeholder s a where

A segment of a parser over strings s, which may be a fixed string (usually created through IsString), only accepting a single fixed value, or a dynamic parameter (created through Parameterized), which encapsulates a Parameter type.

Constructors

PlaceholderFixed :: !s -> Placeholder s ()

PlaceholderParameter :: Parameter s a => Placeholder s a

Instances

RouteString s => Parameterized s (Placeholder s)

Defined in Web.Route.Invertible.Placeholder

Methods

parameter :: Parameter s a => Placeholder s a

Eq s => Eq (Placeholder s a)

Defined in Web.Route.Invertible.Placeholder

Methods

(==) :: Placeholder s a -> Placeholder s a -> Bool

(/=) :: Placeholder s a -> Placeholder s a -> Bool

Ord s => Ord (Placeholder s a)

Defined in Web.Route.Invertible.Placeholder

Methods

compare :: Placeholder s a -> Placeholder s a -> Ordering

(<) :: Placeholder s a -> Placeholder s a -> Bool

(<=) :: Placeholder s a -> Placeholder s a -> Bool

(>) :: Placeholder s a -> Placeholder s a -> Bool

(>=) :: Placeholder s a -> Placeholder s a -> Bool

max :: Placeholder s a -> Placeholder s a -> Placeholder s a

min :: Placeholder s a -> Placeholder s a -> Placeholder s a

Show s => Show (Placeholder s a)

Defined in Web.Route.Invertible.Placeholder

Methods

showsPrec :: Int -> Placeholder s a -> ShowS

show :: Placeholder s a -> String

showList :: [Placeholder s a] -> ShowS

IsString s => IsString (Placeholder s ())

Defined in Web.Route.Invertible.Placeholder

Methods

fromString :: String -> Placeholder s ()

data PlaceholderValue s where

A concrete, untyped representation of a parsed Placeholder value, distinguishing fixed components from parameters but abstracting over the parsed type.

Constructors

PlaceholderValueFixed :: !s -> PlaceholderValue s

PlaceholderValueParameter :: Parameter s a => a -> PlaceholderValue s

Instances

Eq s => Eq (PlaceholderValue s)

Defined in Web.Route.Invertible.Placeholder

Methods

(==) :: PlaceholderValue s -> PlaceholderValue s -> Bool

(/=) :: PlaceholderValue s -> PlaceholderValue s -> Bool

Ord s => Ord (PlaceholderValue s)

Defined in Web.Route.Invertible.Placeholder

Methods

compare :: PlaceholderValue s -> PlaceholderValue s -> Ordering

(<) :: PlaceholderValue s -> PlaceholderValue s -> Bool

(<=) :: PlaceholderValue s -> PlaceholderValue s -> Bool

(>) :: PlaceholderValue s -> PlaceholderValue s -> Bool

(>=) :: PlaceholderValue s -> PlaceholderValue s -> Bool

max :: PlaceholderValue s -> PlaceholderValue s -> PlaceholderValue s

min :: PlaceholderValue s -> PlaceholderValue s -> PlaceholderValue s

(RouteString s, Show s) => Show (PlaceholderValue s)

Defined in Web.Route.Invertible.Placeholder

Methods

showsPrec :: Int -> PlaceholderValue s -> ShowS

show :: PlaceholderValue s -> String

showList :: [PlaceholderValue s] -> ShowS

newtype Sequence s a

A parser/reverse-router isomorphism between sequences of strings (represented as [s]) and a value a. These can be constructed using:

• fromString s (or simply s with OverloadedStrings), which matches a single literal component.
• parameter (or param (undefined :: T) for an explicit type), which matches a place-holder component for a Parameter type.

Sequence values can then be composed using Monoidal and MonoidalAlt.

Constructors

Sequence

Fields

• freeSequence :: Free (Placeholder s) a

Instances

Parameterized s (Sequence s)

Defined in Web.Route.Invertible.Sequence

Methods

parameter :: Parameter s a => Sequence s a

Monoidal (Sequence s)

Defined in Web.Route.Invertible.Sequence

Methods

unit :: Sequence s ()

(>*<) :: Sequence s a -> Sequence s b -> Sequence s (a, b)

MonoidalAlt (Sequence s)

Defined in Web.Route.Invertible.Sequence

Methods

zero :: Sequence s Void

(>|<) :: Sequence s a -> Sequence s b -> Sequence s (Either a b)

Functor (Sequence s)

Defined in Web.Route.Invertible.Sequence

Methods

fmap :: (a <-> b) -> Sequence s a -> Sequence s b

Show s => Show (Sequence s a)

Defined in Web.Route.Invertible.Sequence

Methods

showsPrec :: Int -> Sequence s a -> ShowS

show :: Sequence s a -> String

showList :: [Sequence s a] -> ShowS

IsString s => IsString (Sequence s ())

Defined in Web.Route.Invertible.Sequence

Methods

fromString :: String -> Sequence s ()

Path

newtype Path a

A URL path parser/generator. These should typically be constructed using the IsString and Parameterized instances. Note that the individual components are decoded path segments, so a literal slash in a component (e.g., as produced with fromString) will match "%2F". Example:

"get" *< parameter >*< "value" *< parameter :: Path (String, Int)

matches (or generates) /get/$x/value/$y for any string $x and any int $y and returns those values.

Constructors

Path

Fields

• pathSequence :: Sequence PathString a

Instances

Monoidal Path

Defined in Web.Route.Invertible.Path

Methods

unit :: Path ()

(>*<) :: Path a -> Path b -> Path (a, b)

MonoidalAlt Path

Defined in Web.Route.Invertible.Path

Methods

zero :: Path Void

(>|<) :: Path a -> Path b -> Path (Either a b)

Functor Path

Defined in Web.Route.Invertible.Path

Methods

fmap :: (a <-> b) -> Path a -> Path b

Parameterized PathString Path

Defined in Web.Route.Invertible.Path

Methods

parameter :: Parameter PathString a => Path a

Show (Path a)

Defined in Web.Route.Invertible.Path

Methods

showsPrec :: Int -> Path a -> ShowS

show :: Path a -> String

showList :: [Path a] -> ShowS

IsString (Path ())

Defined in Web.Route.Invertible.Path

Methods

fromString :: String -> Path ()

normalizePath :: [PathString] -> [PathString]

Remove double- and trailing-slashes (i.e., empty path segments).

pathValues :: Path a -> a -> [PlaceholderValue PathString]

Render a Path as instantiated by a value to a list of placeholder values.

renderPath :: Path a -> a -> [PathString]

Render a Path as instantiated by a value to a list of string segments.

urlPathBuilder :: Path a -> a -> Builder

Build a Path as applied to a value into a bytestring Builder by encoding the segments with urlEncodePath and joining them with "/".

Host

newtype Host a

A hostname matcher. These should typically be constructed using the IsString and Parameterized instances. This matches hostnames in reverse order (from TLD down), but the Monoidal instance and splitHost automatically deal with this for you. Example:

parameter >* "domain" >* "com" :: Host String

matches (or generates) *.domain.com and returns the * component.

Constructors

HostRev

Fields

• hostSequence :: Sequence HostString a

Instances

Monoidal Host

Defined in Web.Route.Invertible.Host

Methods

unit :: Host ()

(>*<) :: Host a -> Host b -> Host (a, b)

MonoidalAlt Host

Defined in Web.Route.Invertible.Host

Methods

zero :: Host Void

(>|<) :: Host a -> Host b -> Host (Either a b)

Functor Host

Defined in Web.Route.Invertible.Host

Methods

fmap :: (a <-> b) -> Host a -> Host b

Parameterized HostString Host

Defined in Web.Route.Invertible.Host

Methods

parameter :: Parameter HostString a => Host a

Show (Host a)

Defined in Web.Route.Invertible.Host

Methods

showsPrec :: Int -> Host a -> ShowS

show :: Host a -> String

showList :: [Host a] -> ShowS

IsString (Host ())

Since domain components cannot contain ".", "foo.com" is equivalent to "foo" *< "com" (unlike other Sequences).

Defined in Web.Route.Invertible.Host

Methods

fromString :: String -> Host ()

splitHost :: ByteString -> [HostString]

Split (and reverse) a domainname on "." for use with Host.

joinHost :: [HostString] -> ByteString

Reverse and join a hostname with ".".

renderHost :: Host a -> a -> ByteString

Instantiate a host with a value and render it as a domainname.

Method

class IsMethod m where

Any types that represent an HTTP method.

Methods

toMethod :: m -> Method

fromMethod :: Method -> Maybe m

Instances

IsMethod ByteString

Defined in Web.Route.Invertible.Method

Methods

toMethod :: ByteString -> Method

fromMethod :: Method -> Maybe ByteString

IsMethod StdMethod

Defined in Web.Route.Invertible.Method

Methods

toMethod :: StdMethod -> Method

fromMethod :: Method -> Maybe StdMethod

IsMethod Method

Defined in Web.Route.Invertible.Method

Methods

toMethod :: Method -> Method0

fromMethod :: Method0 -> Maybe Method

IsMethod Method

Defined in Web.Route.Invertible.Method

Methods

toMethod :: Method -> Method

fromMethod :: Method -> Maybe Method

IsMethod (Either ByteString StdMethod)

Defined in Web.Route.Invertible.Method

Methods

toMethod :: Either ByteString StdMethod -> Method

fromMethod :: Method -> Maybe (Either ByteString StdMethod)

Query

type QueryParams = HashMap QueryString [QueryString]

A map from query variables to values, based on SimpleQuery.

paramsQuerySimple :: QueryParams -> SimpleQuery

simpleQueryParams :: SimpleQuery -> QueryParams

Route

blankRequest :: Request

A blank/unknown request; effectively the default value

data RoutePredicate a where

A term, qualifier, or component of a route, each specifying one filterattributeparser/generator for a request.

Constructors

RouteHost :: !(Host h) -> RoutePredicate h

RouteSecure :: !Bool -> RoutePredicate ()

RoutePath :: !(Path p) -> RoutePredicate p

RouteMethod :: !Method -> RoutePredicate ()

RouteQuery :: !QueryString -> !(Placeholder QueryString a) -> RoutePredicate a

RouteAccept :: !ContentType -> RoutePredicate ()

RouteCustom :: Typeable a => (Request -> Maybe a) -> (a -> Request -> Request) -> RoutePredicate a

RoutePriority :: !Int -> RoutePredicate ()

Instances

Show (RoutePredicate a)

Defined in Web.Route.Invertible.Route

Methods

showsPrec :: Int -> RoutePredicate a -> ShowS

show :: RoutePredicate a -> String

showList :: [RoutePredicate a] -> ShowS

newtype Route a

A Monoidal collection of routing predicates. For example:

routeHost ("www" >* "domain.com") *< routePath ("object" *< parameter) :: Route Int

Constructors

Route

Fields

• freeRoute :: Free RoutePredicate a

Instances

Monoidal Route

Defined in Web.Route.Invertible.Route

Methods

unit :: Route ()

(>*<) :: Route a -> Route b -> Route (a, b)

MonoidalAlt Route

Defined in Web.Route.Invertible.Route

Methods

zero :: Route Void

(>|<) :: Route a -> Route b -> Route (Either a b)

Functor Route

Defined in Web.Route.Invertible.Route

Methods

fmap :: (a <-> b) -> Route a -> Route b

Show (Route a)

Defined in Web.Route.Invertible.Route

Methods

showsPrec :: Int -> Route a -> ShowS

show :: Route a -> String

showList :: [Route a] -> ShowS

normRoute :: Route a -> Route a

By default, route predicates are matched in the order they are specified, so each test is done only if all preceding tests succeed. However, in most cases routing rules should be tested in a specific order in order to produce sensible errors (e.g., a 405 error that offers available methods should only apply to other routes with the same path). This re-orders the predicates in a route in order of the constructors in RoutePredicate (i.e., host, secure, path, method, ...), allowing you to construct your routes in any order but still produce sensible matching behavior. Alternatively, since there are cases you may watch to match in a different order (e.g., for routePriority), you can specify your routes in specific order and avoid this function (which would also be more efficient). Note that there are some "de-normalized" cases that this will not correct, such as having duplicate routeMethod specifications (in which case all must match, but each is done independently).

foldRoute :: Monoid b => (forall a'. RoutePredicate a' -> a' -> b) -> Route a -> a -> b

Fold over the predicates in an instatiated route.

requestRoute' :: Route a -> a -> Request -> Request

Given an instantiation of a Route with its value, add the relevant reverse-route information to a Request.

requestRoute :: Route a -> a -> Request

Apply requestRoute' to blankRequest.