Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/elm/url
Build and parse URLs. Useful for HTTP and "routing" in single-page apps (SPAs)
https://github.com/elm/url
elm escape percent-encode router routing single-page-app spa url
Last synced: 4 days ago
JSON representation
Build and parse URLs. Useful for HTTP and "routing" in single-page apps (SPAs)
- Host: GitHub
- URL: https://github.com/elm/url
- Owner: elm
- License: bsd-3-clause
- Created: 2017-08-10T02:22:53.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-09-23T12:14:58.000Z (over 1 year ago)
- Last Synced: 2024-12-18T08:11:23.291Z (26 days ago)
- Topics: elm, escape, percent-encode, router, routing, single-page-app, spa, url
- Language: Elm
- Homepage: https://package.elm-lang.org/packages/elm/url/latest/
- Size: 102 KB
- Stars: 74
- Watchers: 13
- Forks: 43
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ccamel - elm/url - Build and parse URLs. Useful for HTTP and "routing" in single-page apps (SPAs) (Elm)
README
# Work with URLs
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 with [`Browser.application`](https://package.elm-lang.org/packages/elm/browser/latest/Browser#application)!
## What is a URL?
A URL is defined by Tim Berners-Lee in [this document](https://tools.ietf.org/html/rfc3986). 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 this [percent-encoding](https://tools.ietf.org/html/rfc3986#section-2.1). The basic idea is to look up the hex code in [the ASCII table](https://ascii.cl/) and put a `%` in front. There are many subtleties though, so I recommend reading [this](https://en.wikipedia.org/wiki/Percent-encoding) for more details!
> **Note:** The difference between a URI and a URL is kind of subtle. [This post](https://danielmiessler.com/study/url-uri/) explains the difference nicely. I decided to call this library `elm/url` because it is primarily concerned with HTTP which does need actual locations.
## Related Work
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!
[formatting]: https://chrisdone.com/posts/formatting
[post]: http://rgrinberg.com/posts/primitive-type-safe-routing/