Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify percent-encoding documentation #44

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Clarify percent-encoding documentation #44

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions src/Url.elm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,8 +223,12 @@ addPrefixed prefix maybeSegment starter =


{-| **Use [Url.Builder](Url-Builder) instead!** Functions like `absolute`,
`relative`, and `crossOrigin` already do this automatically! `percentEncode`
is only available so that extremely custom cases are possible, if needed.
`relative`, and `crossOrigin` already encode query parameters automatically!
`percentEncode` is only available so that extremely custom cases are possible,
if needed. (Note that those functions do not percent-encode path components,
because [not everyone needs the same encoding](https://github.com/elm/url/issues/25#issuecomment-776365116).
If you need to do that, you need to call this function on each path, for example
`Url.Builder.absolute (List.map percentEncode ["encode me"]) []` to get `/encode%20me`.)

Percent-encoding is how [the official URI spec][uri] “escapes” special
characters. You can still represent a `?` even though it is reserved for
Expand Down Expand Up @@ -259,7 +263,11 @@ percentEncode =

{-| **Use [Url.Parser](Url-Parser) instead!** It will decode query
parameters appropriately already! `percentDecode` is only available so that
extremely custom cases are possible, if needed.
extremely custom cases are possible, if needed. (Note that Url.Parser
does not percent-decode path components, because [not everyone needs
the same encoding](https://github.com/elm/url/issues/25#issuecomment-776365116).
If you need to do that, you can create a [custom `Url.Parser` with
`custom "STRING" Url.percentDecode`](https://github.com/elm/url/issues/42#issue-805049603).)

Check out the `percentEncode` function to learn about percent-encoding.
This function does the opposite! Here are the reverse examples:
Expand Down