Copyright	(C) 2016-2026 David M. Johnson
License	BSD3-style (see the file LICENSE)
Maintainer	David M. Johnson <code@dmj.io>
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Miso.Router

Contents

Classes
Types
Errors
Functions
Manual Routing
Construction
Parser combinators
Lexing
Orphan instances

Description

Overview

Miso.Router provides a type-safe, bidirectional client-side router. A Haskell sum type represents your application's routes; the Router class encodes and decodes between that type and URL strings. The router is used together with uriSub or routerSub to react to browser navigation.

Approach 1 — Generic deriving (recommended)

{-# LANGUAGE DeriveGeneric, DeriveAnyClass, DerivingStrategies #-}
import GHC.Generics (Generic)
import Miso.Router

data Route
  = Index                                                    -- "/"
  | About                                                    -- "/about"
  | User (Capture "id" Int)                                 -- "/user/42"
  | Search (QueryParam "q" MisoString)         -- "/search?q=foo"
  deriving stock (Show, Eq, Generic)
  deriving anyclass Router

Decoding:

toRoute "/user/42"  -- Right (User (Capture 42))
toRoute "/search?q=hello" -- Right (Search (QueryParam (Just "hello")))

Encoding (type-safe links):

prettyRoute (User (Capture 42))       -- "/user/42"
button_ [ href_ (User (Capture 42)) ] [ text "Profile" ]

Approach 2 — Manual instance

data Route = Widget Int deriving (Show, Eq)

instance Router Route where
  routeParser = routes [ Widget <$> (path "widget" *> capture) ]
  fromRoute (Widget n) = [ toPath "widget", toCapture n ]

Generic naming rules

Constructor name becomes the lowercase path segment: About → /about, UserProfile → /user (first camel-case hump only).
A constructor whose first camel-case hump is Index (Index, IndexPage) encodes the root path /. Its QueryParam and QueryFlag fields are encoded into the query string and decoded back: with a QueryParam "page" Int field, Index (QueryParam (Just 2)) is /?page=2. Capture, Path and nested route fields are not supported on an index route: their path segments are dropped when encoding, so the route can't be decoded from the URL it prints. A Fragment field is encoded but can't be decoded yet. Don't give one type two index constructors (say Index and IndexPage): both match /, so decoding it is ambiguous.
The position of Capture and Path fields in the constructor determines their order in the URL path. The position of QueryParam and QueryFlag does not matter.

URL types

Capture sym a: dynamic path segment — Capture 42 → /42
Path sym: fixed path segment — Path "foo" → /foo
QueryParam sym a: optional query key — QueryParam (Just 1) → ?sym=1, QueryParam Nothing → omitted
QueryFlag sym: boolean query flag — QueryFlag True → ?sym, QueryFlag False → omitted
Fragment sym: hash fragment — Fragment → #sym

Integration with history subscription

import Miso.Subscription.History (routerSub)

subs :: [Sub Action]
subs = [ routerSub RouteChanged ]

class Router route where
- fromRoute :: route -> [Token]
- toURI :: route -> URI
- route :: URI -> Either RoutingError route
- href_ :: route -> Attribute model action
- prettyRoute :: route -> MisoString
- dumpURI :: route -> MisoString
- toRoute :: MisoString -> Either RoutingError route
- routeParser :: RouteParser route
type RouteParser = ParserT URI [Token] []
class GRouter (f :: k -> Type) where
- gFromRoute :: forall (route :: k). f route -> [Token]
- gRouteParser :: forall (route :: k). RouteParser (f route)
newtype Capture (sym :: Symbol) a = Capture a
newtype Path (path :: Symbol) = Path MisoString
newtype QueryParam (path :: Symbol) a = QueryParam (Maybe a)
newtype QueryFlag (path :: Symbol) = QueryFlag Bool
data Fragment (path :: Symbol) = Fragment
data Token
- = QueryParamTokens [(MisoString, Maybe MisoString)]
- | QueryParamToken MisoString (Maybe MisoString)
- | CaptureOrPathToken MisoString
- | FragmentToken MisoString
- | IndexToken
data URI = URI {
- uriPath :: MisoString
- uriFragment :: MisoString
- uriQueryString :: Map MisoString (Maybe MisoString)
}
data RoutingError
- = ParseError MisoString [Token]
- | AmbiguousParse MisoString [Token]
- | LexError MisoString MisoString
- | LexErrorEOF MisoString
- | NoParses MisoString
parseURI :: MisoString -> Either MisoString URI
prettyURI :: URI -> MisoString
prettyQueryString :: URI -> MisoString
runRouter :: MisoString -> RouteParser route -> Either RoutingError route
routes :: [RouteParser route] -> RouteParser route
toQueryParam :: ToMisoString s => MisoString -> s -> Token
toCapture :: ToMisoString string => string -> Token
toPath :: MisoString -> Token
emptyURI :: URI
queryFlag :: forall (flag :: Symbol). KnownSymbol flag => RouteParser (QueryFlag flag)
queryParam :: forall (param :: Symbol) a. (FromMisoString a, KnownSymbol param) => RouteParser (QueryParam param a)
capture :: FromMisoString value => RouteParser value
path :: MisoString -> RouteParser MisoString
fragment :: MisoString -> RouteParser MisoString
lexTokens :: MisoString -> Either LexerError [Token]
tokensToURI :: [Token] -> URI

Classes

class Router route where Source #

Class used to facilitate routing for miso applications

Minimal complete definition

Nothing

Methods

fromRoute :: route -> [Token] Source #

default fromRoute :: (Generic route, GRouter (Rep route)) => route -> [Token] Source #

toURI :: route -> URI Source #

Convert a 'Router route => route' into a URI

route :: URI -> Either RoutingError route Source #

Map a URI back to a route

href_ :: route -> Attribute model action Source #

Convenience for specifying a URL as a hyperlink reference in View

prettyRoute :: route -> MisoString Source #

Route pretty printing

dumpURI :: route -> MisoString Source #

Route debugging

toRoute :: MisoString -> Either RoutingError route Source #

Route parsing from a MisoString

routeParser :: RouteParser route Source #

default routeParser :: (Generic route, GRouter (Rep route)) => RouteParser route Source #

Instances

Instances details

Router UUID Source #
Instance details Defined in Miso.UUID Methods fromRoute :: UUID -> [Token] Source # toURI :: UUID -> URI Source # route :: URI -> Either RoutingError UUID Source # href_ :: UUID -> Attribute model action Source # prettyRoute :: UUID -> MisoString Source # dumpURI :: UUID -> MisoString Source # toRoute :: MisoString -> Either RoutingError UUID Source # routeParser :: RouteParser UUID Source #

type RouteParser = ParserT URI [Token] [] Source #

State monad for parsing URI

class GRouter (f :: k -> Type) where Source #

Generic deriving for Router

Methods

gFromRoute :: forall (route :: k). f route -> [Token] Source #

gRouteParser :: forall (route :: k). RouteParser (f route) Source #

Instances

Instances details

GRouter (U1 :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). U1 route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (U1 route) Source #
(GRouter left, GRouter right) => GRouter (left :*: right :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). (left :: right) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser ((left :: right) route) Source #
(GRouter left, GRouter right) => GRouter (left :+: right :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). (left :+: right) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser ((left :+: right) route) Source #
(KnownSymbol name, GRouter next) => GRouter (C1 ('MetaCons name x y) next :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). C1 ('MetaCons name x y) next route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (C1 ('MetaCons name x y) next route) Source #
GRouter next => GRouter (D1 m next :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). D1 m next route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (D1 m next route) Source #
(FromMisoString a, ToMisoString a) => GRouter (K1 m (Capture sym a) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (Capture sym a) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (Capture sym a) route) Source #
KnownSymbol frag => GRouter (K1 m (Fragment frag) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (Fragment frag) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (Fragment frag) route) Source #
KnownSymbol path => GRouter (K1 m (Path path) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (Path path) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (Path path) route) Source #
KnownSymbol flag => GRouter (K1 m (QueryFlag flag) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (QueryFlag flag) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (QueryFlag flag) route) Source #
(ToMisoString a, FromMisoString a, KnownSymbol param) => GRouter (K1 m (QueryParam param a) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (QueryParam param a) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (QueryParam param a) route) Source #
Router a => GRouter (K1 m a :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m a route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m a route) Source #
GRouter next => GRouter (S1 m next :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). S1 m next route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (S1 m next route) Source #

Types

newtype Capture (sym :: Symbol) a Source #

Type used for representing capture variables

Constructors

Capture a

Instances

Instances details

(FromMisoString a, ToMisoString a) => GRouter (K1 m (Capture sym a) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (Capture sym a) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (Capture sym a) route) Source #
Eq a => Eq (Capture sym a) Source #
Instance details Defined in Miso.Router Methods (==) :: Capture sym a -> Capture sym a -> Bool # (/=) :: Capture sym a -> Capture sym a -> Bool #
Show a => Show (Capture sym a) Source #
Instance details Defined in Miso.Router Methods showsPrec :: Int -> Capture sym a -> ShowS # show :: Capture sym a -> String # showList :: [Capture sym a] -> ShowS #
FromMisoString a => FromMisoString (Capture sym a) Source #
Instance details Defined in Miso.Router Methods fromMisoStringEither :: MisoString -> Either String (Capture sym a) Source #
ToMisoString a => ToMisoString (Capture sym a) Source #
Instance details Defined in Miso.Router Methods toMisoString :: Capture sym a -> MisoString Source #

newtype Path (path :: Symbol) Source #

Type used for representing URL paths

Constructors

Path MisoString

Instances

Instances details

KnownSymbol path => GRouter (K1 m (Path path) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (Path path) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (Path path) route) Source #
Eq (Path path) Source #
Instance details Defined in Miso.Router Methods (==) :: Path path -> Path path -> Bool # (/=) :: Path path -> Path path -> Bool #
IsString (Path path) Source #
Instance details Defined in Miso.Router Methods fromString :: String -> Path path #
Show (Path path) Source #
Instance details Defined in Miso.Router Methods showsPrec :: Int -> Path path -> ShowS # show :: Path path -> String # showList :: [Path path] -> ShowS #
ToMisoString (Path path) Source #
Instance details Defined in Miso.Router Methods toMisoString :: Path path -> MisoString Source #

newtype QueryParam (path :: Symbol) a Source #

Type used for representing query parameters

Constructors

QueryParam (Maybe a)

Instances

Instances details

(ToMisoString a, FromMisoString a, KnownSymbol param) => GRouter (K1 m (QueryParam param a) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (QueryParam param a) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (QueryParam param a) route) Source #
Eq a => Eq (QueryParam path a) Source #
Instance details Defined in Miso.Router Methods (==) :: QueryParam path a -> QueryParam path a -> Bool # (/=) :: QueryParam path a -> QueryParam path a -> Bool #
Show a => Show (QueryParam path a) Source #
Instance details Defined in Miso.Router Methods showsPrec :: Int -> QueryParam path a -> ShowS # show :: QueryParam path a -> String # showList :: [QueryParam path a] -> ShowS #
(FromMisoString a, KnownSymbol path) => FromMisoString (QueryParam path a) Source #
Instance details Defined in Miso.Router Methods fromMisoStringEither :: MisoString -> Either String (QueryParam path a) Source #
(ToMisoString a, KnownSymbol path) => ToMisoString (QueryParam path a) Source #	Renders this one parameter as `?key=value`, or nothing for `Nothing`. Not a URL serializer: use `prettyRoute` to print a whole route.
Instance details Defined in Miso.Router Methods toMisoString :: QueryParam path a -> MisoString Source #

newtype QueryFlag (path :: Symbol) Source #

Type used for representing query flags

Constructors

QueryFlag Bool

Instances

Instances details

KnownSymbol flag => GRouter (K1 m (QueryFlag flag) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (QueryFlag flag) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (QueryFlag flag) route) Source #
Eq (QueryFlag path) Source #
Instance details Defined in Miso.Router Methods (==) :: QueryFlag path -> QueryFlag path -> Bool # (/=) :: QueryFlag path -> QueryFlag path -> Bool #
Show (QueryFlag path) Source #
Instance details Defined in Miso.Router Methods showsPrec :: Int -> QueryFlag path -> ShowS # show :: QueryFlag path -> String # showList :: [QueryFlag path] -> ShowS #
KnownSymbol name => ToMisoString (QueryFlag name) Source #	Renders this one flag as `?name`, or nothing for `False`. Not a URL serializer: use `prettyRoute` to print a whole route.
Instance details Defined in Miso.Router Methods toMisoString :: QueryFlag name -> MisoString Source #

data Fragment (path :: Symbol) Source #

Type used for representing fragments

Constructors

Fragment

Instances

Instances details

KnownSymbol frag => GRouter (K1 m (Fragment frag) :: k -> Type) Source #
Instance details Defined in Miso.Router Methods gFromRoute :: forall (route :: k). K1 m (Fragment frag) route -> [Token] Source # gRouteParser :: forall (route :: k). RouteParser (K1 m (Fragment frag) route) Source #
Eq (Fragment path) Source #
Instance details Defined in Miso.Router Methods (==) :: Fragment path -> Fragment path -> Bool # (/=) :: Fragment path -> Fragment path -> Bool #
Show (Fragment path) Source #
Instance details Defined in Miso.Router Methods showsPrec :: Int -> Fragment path -> ShowS # show :: Fragment path -> String # showList :: [Fragment path] -> ShowS #
KnownSymbol frag => ToMisoString (Fragment frag) Source #
Instance details Defined in Miso.Router Methods toMisoString :: Fragment frag -> MisoString Source #

data Token Source #

A list of tokens are returned from a successful lex of a URI

Constructors

QueryParamTokens [(MisoString, Maybe MisoString)]
QueryParamToken MisoString (Maybe MisoString)
CaptureOrPathToken MisoString
FragmentToken MisoString
IndexToken

Instances

Instances details

Eq Token Source #
Instance details Defined in Miso.Router Methods (==) :: Token -> Token -> Bool # (/=) :: Token -> Token -> Bool #
Show Token Source #
Instance details Defined in Miso.Router Methods showsPrec :: Int -> Token -> ShowS # show :: Token -> String # showList :: [Token] -> ShowS #
ToMisoString Token Source #	Renders a single `Token` for debugging. Each query token gets its own `?`, so this is not a URL serializer: use `prettyURI . tokensToURI` (as `prettyRoute` does) to print a list of tokens as a URL.
Instance details Defined in Miso.Router Methods toMisoString :: Token -> MisoString Source #

data URI Source #

URI type. See the official specification

Constructors

URI
Fields uriPath :: MisoString Path component, e.g. `"users/42"` uriFragment :: MisoString Fragment identifier (without the leading `#`), e.g. `"section-1"` uriQueryString :: Map MisoString (Maybe MisoString) Query parameters. `Just v` for `?key=v` pairs; `Nothing` for bare flags (`?flag`).

Instances

Instances details

Eq URI Source #

Instance details

Defined in Miso.Types

Methods

(==) :: URI -> URI -> Bool #

(/=) :: URI -> URI -> Bool #

Generic URI Source #

Instance details

Defined in Miso.Types

Associated Types

type Rep URI

Instance details

Defined in Miso.Types

type Rep URI = D1 ('MetaData "URI" "Miso.Types" "miso-1.14.0.0-inplace" 'False) (C1 ('MetaCons "URI" 'PrefixI 'True) (S1 ('MetaSel ('Just "uriPath") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 MisoString) :*: (S1 ('MetaSel ('Just "uriFragment") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 MisoString) :*: S1 ('MetaSel ('Just "uriQueryString") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map MisoString (Maybe MisoString))))))

Methods

from :: URI -> Rep URI x #

to :: Rep URI x -> URI #

Show URI Source #

Instance details

Defined in Miso.Types

Methods

showsPrec :: Int -> URI -> ShowS #

show :: URI -> String #

showList :: [URI] -> ShowS #

ToJSVal URI Source #

Instance details

Defined in Miso.Types

Methods

toJSVal :: URI -> IO JSVal Source #

ToObject URI Source #

Instance details

Defined in Miso.Types

Methods

toObject :: URI -> IO Object Source #

FromJSON URI Source #

Instance details

Defined in Miso.Router

Methods

parseJSON :: Value -> Parser URI Source #

ToJSON URI Source #

Instance details

Defined in Miso.Types

Methods

toJSON :: URI -> Value Source #

toJSONList :: [URI] -> Value Source #

FromMisoString URI Source #

Instance details

Defined in Miso.Router

Methods

fromMisoStringEither :: MisoString -> Either String URI Source #

ToMisoString URI Source #

Instance details

Defined in Miso.Types

Methods

toMisoString :: URI -> MisoString Source #

type Rep URI Source #

Instance details

Defined in Miso.Types

type Rep URI = D1 ('MetaData "URI" "Miso.Types" "miso-1.14.0.0-inplace" 'False) (C1 ('MetaCons "URI" 'PrefixI 'True) (S1 ('MetaSel ('Just "uriPath") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 MisoString) :*: (S1 ('MetaSel ('Just "uriFragment") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 MisoString) :*: S1 ('MetaSel ('Just "uriQueryString") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map MisoString (Maybe MisoString))))))

Errors

data RoutingError Source #

An error that can occur during lexing / parsing of a URI into a user-defined data type

Constructors

ParseError MisoString [Token]
AmbiguousParse MisoString [Token]
LexError MisoString MisoString
LexErrorEOF MisoString
NoParses MisoString

Instances

Instances details

Eq RoutingError Source #
Instance details Defined in Miso.Router Methods (==) :: RoutingError -> RoutingError -> Bool # (/=) :: RoutingError -> RoutingError -> Bool #
Show RoutingError Source #
Instance details Defined in Miso.Router Methods showsPrec :: Int -> RoutingError -> ShowS # show :: RoutingError -> String # showList :: [RoutingError] -> ShowS #

Functions

parseURI :: MisoString -> Either MisoString URI Source #

URI parsing

prettyURI :: URI -> MisoString Source #

Pretty-prints a URI.

A # is added before a non-empty uriFragment. A leading # already present in uriFragment is not repeated, so URI "foo" "#top" mempty and URI "foo" "top" mempty both print as /foo#top.

prettyQueryString :: URI -> MisoString Source #

Pretty-prints a URI query string.

Parameters and flags share a single ? and are separated by &, in key order: ?a=1&flag. Entries with an empty key are skipped, since they can't be parsed back, and an empty query string prints as nothing. Keys and values are printed exactly as stored; they are not percent-encoded.

Manual Routing

runRouter Source #

Arguments

:: MisoString	The raw URL string to parse
-> RouteParser route	Parser to apply against the tokenised URL
-> Either RoutingError route

Smart constructor for building a RouteParser

data Route = Widget MisoString Int

instance Router Route where
  routeParser = routes [ Widget <$> path "widget" <*> capture ]
  fromRoute (Widget path value) = [ toPath path, toCapture value ]

router :: Router router => RouteParser router
router = routes [ Widget <$> path "widget" <*> capture ]

> Right (Widget "widget" 10)

routes :: [RouteParser route] -> RouteParser route Source #

Convenience for specifying multiple routes

Construction

toQueryParam Source #

Arguments

:: ToMisoString s
=> MisoString	Query parameter key
-> s	Query parameter value
-> Token

Smart constructor for building a QueryParamToken

toCapture :: ToMisoString string => string -> Token Source #

Smart constructor for building a capture variable

toPath :: MisoString -> Token Source #

Smart constructor for building a path fragment

emptyURI :: URI Source #

Empty URI.

Parser combinators

queryFlag :: forall (flag :: Symbol). KnownSymbol flag => RouteParser (QueryFlag flag) Source #

Query flag parser from a route

queryParam :: forall (param :: Symbol) a. (FromMisoString a, KnownSymbol param) => RouteParser (QueryParam param a) Source #

Query parameter parser from a route.

A missing key, a bare key (?page), or a value that doesn't parse as a gives Nothing. An empty value (?page=) is passed to fromMisoStringEither, so it gives Just "" for a MisoString param and Nothing for an Int.

capture :: FromMisoString value => RouteParser value Source #

Combinator for parsing a capture variable out of a URI

path :: MisoString -> RouteParser MisoString Source #

Combinator for parsing a path out of a URI

fragment :: MisoString -> RouteParser MisoString Source #

Matches a literal URI fragment (the part after #), failing the parse if it differs. Returns the matched fragment.

Lexing

lexTokens :: MisoString -> Either LexerError [Token] Source #

Lexes a URI into route Tokens, or reports where lexing failed.

tokensToURI :: [Token] -> URI Source #

Converts a list of [Token] into an actual URI.

uriFragment is stored without the leading #. The lexer produces at most one FragmentToken, but fromRoute can produce several; those are joined with #, so they print back as /foo#a#b.

Orphan instances

FromJSON URI Source #
Instance details Methods parseJSON :: Value -> Parser URI Source #
FromMisoString URI Source #
Instance details Methods fromMisoStringEither :: MisoString -> Either String URI Source #

Overview

Approach 1 — Generic deriving (recommended)

Approach 2 — Manual instance

Generic naming rules

URL types

Integration with history subscription

See also

Classes

Instances

Instances

Types

Instances

Instances

Instances

Instances

Instances

Instances

Instances

Errors

Instances

Functions

Manual Routing

Construction

Parser combinators

Lexing

Orphan instances