This library has two primary modules:

• Url to build URLs for HTTP requests
• Url.Parser to parse URLs for “routing” in single-page apps (SPAs)

Check out those modules for specific usage examples!

A URL is defined by Tim Berners-Lee in this document. It is worth reading, but I will try to share some highlights. He shares an example like this:

  https://example.com:8042/over/there?name=ferret#nose
  \___/   \______________/\_________/ \_________/ \__/
    |            |            |            |        |
  scheme     authority       path        query   fragment

And here are some facts that I found surprising:

• ASCII only — Behavior with other encodings is undefined in the spec. So a browser may handle a non-ASCII character one way, while this library handles it another. No one is wrong. It is just unspecified. I would stick to ASCII to be safe.

• Escaping — The spec uses the term percent-encoded to reduce confusion with other escape mechanisms. The format is %XX allowing two hex digits. According to this table of ASCII characters, you could encode ? as %3F and = as %3D. There are many subtleties though, so I recommend reading this for more information!

Note: The difference between a URI and a URL is kind of subtle. This post explains the difference nicely. I decided to call this library elm-lang/url because it is primarily concerned with HTTP which does need actual locations.

The API in Url.Parser is quite distinctive. I first saw the general idea in Chris Done’s formatting library. Based on that, Noah and I outlined the API you see in Url.Parser. Noah then found Rudi Grinberg’s post about type safe routing in OCaml. It was exactly what we were going for. We had even used the names s and (</>) in our draft API! In the end, we ended up using the “final encoding” of the EDSL that had been left as an exercise for the reader. Very fun to work through!