Url

HTML & web

Absolute URLs: protocol, host, path, query, and fragment.

Parse a string with fromString, turn a record back with toString, and percent-encode path or query pieces when you build URLs by hand. Path routing lives in [Url.Parser]. Building paths with query params is easier with [Url.Builder]. HTTP servers usually parse request paths with [Server.Route], which uses the same combinators under the hood.

Url.fromString "https://example.com:443/blog/1?x=1#top"
-- Just { protocol = Https, host = "example.com", port_ = Just 443
--      , path = "/blog/1", query = Just "x=1", fragment = Just "top" }

Types

Url

type alias Url =
{ protocol : Protocol
, host : String
, port_ : Maybe Int
, path : String
, query : Maybe String
, fragment : Maybe String
}

A fully absolute URL. port_ is Nothing when the URL omits an explicit port.

Examples

url : Url
url =
    { protocol = Https
    , host = "example.com"
    , port_ = Nothing
    , path = "/blog"
    , query = Nothing
    , fragment = Nothing
    }

Protocol

type Protocol
= Http
| Https

http or https.

Examples

Https
Http

Values

fromString

fromString : String -> Maybe Url

Parse an absolute URL string. Returns Nothing when the string is not a usable absolute URL (missing scheme/host, and so on).

Examples

fromString "https://example.com/a"
    == Just { protocol = Https, host = "example.com", port_ = Nothing
            , path = "/a", query = Nothing, fragment = Nothing }

fromString "/relative" == Nothing

percentDecode

percentDecode : String -> Maybe String

Decode a percent-encoded string (%20 becomes a space). Returns Nothing on invalid encoding.

Examples

percentDecode "a%20b" == Just "a b"
percentDecode "%ZZ" == Nothing

percentEncode

percentEncode : String -> String

Percent-encode a string for use in a path segment or query value.

Examples

Url.percentEncode "a b"  == "a%20b"

toString

toString : Url -> String

Turn a Url back into an absolute string.

Examples

toString
    { protocol = Https
    , host = "example.com"
    , port_ = Nothing
    , path = "/a"
    , query = Just "x=1"
    , fragment = Nothing
    }
    == "https://example.com/a?x=1"