Repository files navigation

This package helps you (1) build new URLs and (2) parse existing URLs into nice Elm data structures.

These tasks are quite common when building web apps in Elm withBrowser.application!

A URL is defined by Tim Berners-Lee inthis 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 — The spec only talks about ASCII characters. Behavior with other encodings is unspecified, so if you use a UTF-8 character directly, it may be handled differently by browsers, packages, and servers! No one is wrong. It is just unspecified. So I would stick to ASCII to be safe.
• Escaping — There are some reserved characters in the spec, like/,?, and#. So what happens when you need those in your query? The spec allows you to “escape” characters (/ =>%2F,? =>%3F,# =>%23) so it is clearly not a reserved characters anymore. The spec calls thispercent-encoding. The basic idea is to look up the hex code inthe ASCII table and put a% in front. There are many subtleties though, so I recommend readingthis for more details!

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

The API inUrl.Parser is quite distinctive. I first saw the general idea in Chris Done’sformatting library. Based on that, Noah and I outlined the API you see inUrl.Parser. Noah then found Rudi Grinberg’spost about type safe routing in OCaml. It was exactly what we were going for. We had even used the namess 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!