feat(stdlib): Add Uri module

[alex-snezhko]

URI parsing and utility module, mostly conforming to RFC 3986.

module Main

include "uri"

let uri = Result.unwrap(Uri.parse("https://grain-lang.org"))
print(Uri.scheme(uri)) // https
print(Uri.host(uri)) // grain-lang.org

Uri.encode("a:b") // a%3Ab

[spotandjake]

This looks great.

Also looks like the docs need to be regenerated.

[marcusroberts]

Alex, this looks fantastic and really useful. I also learnt a lot about what are valid URLs (I swore you could only include? once!). My only comment before I press approve is that pretty much every language calls urlEncode what you call percentageEncode, and I wondered if we should standardize on that?

(although wikipedia says it's officially percent encode... https://en.wikipedia.org/wiki/Percent-encoding)

[ospencer]

What made you return an abstract record and have access methods rather than just return the record?

[alex-snezhko]

@ospencer This is following the pattern I've seen used in OCaml libraries for encapsulating data/providing a uniform interface for simple & computed data. In this particular instance not much is really being encapsulated but I think having these access methods still provides a degree of uniformity. Kind of like the idea behind properties in C# or getters in Java, where the interface to a data type can remain disconnected from the implementation.

I guess just providing the record directly here would be simpler though and would make the API smaller. I'm not heavily set in either direction so I'm open to arguments in either direction

[ospencer]

I don't mind it, I was just curious! I looked at the API first and it made me think some kind of computation was happening since I already called this parse function but then I'm still asking about specific pieces. I feel like in one, isolated case, I would just want the record, but we can think about it in the context of similar libraries we want to have.

[alex-snezhko]

Yeah that makes sense. I can change it to a provided record

[ospencer]

I'd wait to hear what the stdlib experts say :P

[alex-snezhko]

@marcusroberts good point, I also just did a survey of a handful of languages and they all seem to prefer the terminology of "URL encoding". Though RFC 3986 uses the terminology of "percent encoding" so I guess it's a decision on whether we want to use the official terminology or the common lingo 🤷

[phated]

it made me think some kind of computation was happening

I think I agree here. Usually if you are calling a function on some abstract type, it'd be due to delayed processing. For example, a Rust library I was using was storing the full cookie key=value string as &'a str and then storing the key and value range as integers. When you want to get the key, you'd call cookie.key() and cookie.value() which would do the processing. Since you are immediately doing processing in parse, it's probably good to just return the record.

The caveat to the above is returning records with functions attached; instead, I would say should be functions that take the record (such as our Queue, Map, etc data structures).

[spotandjake]

@marcusroberts good point, I also just did a survey of a handful of languages and they all seem to prefer the terminology of "URL encoding". Though RFC 3986 uses the terminology of "percent encoding" so I guess it's a decision on whether we want to use the official terminology or the common lingo 🤷

I think we should use the common terminology but keep our docs searchable by including the percent encoding wording somewhere in the description.

[alex-snezhko]

@spotandjake @marcusroberts What about just encode and decode? The fact that it's "URL" encoding should be implicit since it's in this module

[marcusroberts]

Thanks for changing the name - it looks great to me now!

[ospencer]

Thoughts on changing all of the places we say percentEncode/percentDecode to just encode/decode?

[ospencer]

I think we should make issues for String.lowercaseAscii and String.uppercaseAscii and todos that reference it here.

[alex-snezhko]

What do you mean here? This function uses the char toAsciiLowercase function

[ospencer]

Instead of exploding and iterating the Char version, it'd be handy to just call lowercase on the string. Unless I didn't read this hard enough.

[alex-snezhko]

I think you'd still need some custom logic to only lowercase the characters that aren't percent-encode triples so not sure if there'd be a super huge advantage to using lowercase on the whole string

[ospencer]

Phenomenal work on this! I learned a ton about URIs just from reading your implementation. Excited to use this soon.

[phated]

Looks like this needs docs regenerated

[phated]

Sorry I did those as individuals. I always thought "surely this will be the last one" until the actual last one.