Url.Parser

HTML & web

Turn a URL path into a typed value.

You describe the shape of the path with combinators, then call parse. For HTTP request routing on the BEAM, prefer [Server.Route]: it wraps these helpers and also matches the method.

import Url
import Url.Parser as Parser exposing ((</>), map, oneOf, parse, s, string)

type Route
    = Home
    | Topic String
    | Blog Int

route : Parser.Parser (Route -> a) a
route =
    oneOf
        [ map Home Parser.top
        , map Topic (s "topic" </> string)
        , map Blog (s "blog" </> Parser.int)
        ]

parse route (Url.fromString "https://example.com/topic/cats" |> Maybe.withDefault ...)
-- Just (Topic "cats")

Query strings use [Url.Parser.Query] with `<?>` / `query`. Building URLs the other way is [Url.Builder].

Types

Parser

type Parser a b = Parser (State a -> List (State b

A parser that turns path segments into a value. The two type parameters are the usual "remaining args" trick: start from (a -> a) when you call parse.

Examples

route : Parser (Route -> a) a
route =
    map Home top

Values

</>

infix right 7 (</>) = slash

Compose two path parsers in sequence.

Examples

s "blog" </> int

<?>

infix left 8 (<?>) = questionMark

Parse path, then query parameters.

Examples

s "search" <?> Query.string "q"

string

string : Parser (String -> a) a

Consume one path segment as a String.

Examples

s "topic" </> string

int

int : Parser (Int -> a) a

Consume one path segment as an Int.

Examples

s "blog" </> int

s

s : String -> Parser a a

Match a literal path segment.

Examples

s "blog" </> int
-- matches /blog/42

custom

custom : String -> (String -> Maybe a) -> Parser (a -> b) b

Consume one segment with your own String -> Maybe a decoder. The first argument is only a label for debugging.

Examples

custom "USER" UserId.fromString

slash

slash : Parser a b -> Parser b c -> Parser a c

Compose two parsers in sequence (same as </>).

Examples

slash (s "blog") int

map

map : a -> Parser a b -> Parser (b -> c) c

Wrap a successful parse in a constructor (or any function).

Examples

map Topic (s "topic" </> string)

oneOf

oneOf : List (Parser a b) -> Parser a b

Try each parser; first full match wins when you call parse.

Examples

oneOf
    [ map Home top
    , map Topic (s "topic" </> string)
    ]

top

top : Parser a a

Match an empty remaining path (the site root, or after other segments have already been consumed).

Examples

map Home top

questionMark

questionMark : Parser a (query -> b) -> Query.Parser query -> Parser a b

Parse path, then query parameters (same as <?>).

Examples

questionMark (s "search") (Query.string "q")

query

query : Query.Parser query -> Parser (query -> a) a

Apply a [Url.Parser.Query] parser to the URL's query string.

Examples

s "search" </> query (Query.string "q")

fragment

fragment : (Maybe String -> fragment) -> Parser (fragment -> a) a

Pass the URL fragment (#...) into your value as Maybe String.

Examples

map Hash (fragment identity)

parse

parse : Parser (a -> a) a -> Url -> Maybe a

Run a parser against a [Url]. Returns `Nothing` when no alternative consumes the whole path.

Examples

parse (map Home top) url == Just Home