Add `gix_url::Url` manipulation methods

[samvv]

Summary 💡

Right now it is not possible to manipulate a gix_url::Url easily. I propose a small addition to the API to allow e.g. transforming the path of a URL.

let url = gix_url::url::parse("https://github.com/samvv/mage").unwrap();
let new_url = url.map_path(|p| format!("{}.git").into());
println!("{}", new_url); // outputs https://github.com/samvv/mage.git

Note that a bformat (a format! for BString) would make this even easier and also less buggy, but such a macro doesn't exist.

Alternatively, one could provide a group of setters to manipulate a URL:

let url = gix_url::url::parse("https://github.com/samvv/mage").unwrap();
url.set_path(format!("{}.git", url.path).into());
println!("{}", url); // outputs https://github.com/samvv/mage.git

Or maybe a builder pattern:

let new_url = gix_url::Url::build()
    .schema(url.schema)
    .user(url.user())
    .password(url.password())
    .host(url.host())
    .path(format!("{}.git", url.path).into());

Motivation 🔦

I'm writing a build system for Linux packages and need to transform a raw repo URL (e.g. https://github.com/samvv/mage) to its Git URL (e.g. https://github.com/samvv/mage.git), just like NPM does.

[Byron]

Thanks for the suggestion.

I think the reason setters don't exist is that they are probably fallible, and there are a few unknowns to me at least to see what's needed to assure only valid URLs are allowed.

However, it looks like even today one can set the path field as it's public, which means it's already possible to set it to an invalid value. Maybe that's also something to address, to define what the user of a Url instance can be certain of.

My basic expectation would be that every Url instance can be round-tripped, and thus can also be parsed back after serialisation. Alternatively, and it's the path we are on now, the instance itself doesn't necessarily contain valid path data, and serialisation might fail because of it? Right now, it seems to happily write out garbage as there is no failure case, so the whole thing is a bit wonky if the type would be used to pass Urls around.

In practice, I think Urls are always passed as BString and then parsed, so invalid URLs are weeded out that way.

To keep it simple, it feels like everything that is relatively easy to use can be pub field: type, and things that have more constraints on them can be done with setters maybe for additional safety.
But most importantly there should be a remark that due to the mutability of the type it's possible that the Url serializes to something invalid, so it should be accepted as parameter directly (i.e. document the status quo).

[samvv]

Yup, it looks like I overlooked the mutable .path field on the Url object, thanks!

I'd personally vote for making EITHER all fields public OR providing getters (and possibly setters) for all fields. This could avoid some confusion like the one I was having.

If we can agree on a design I'm happy to fire up a pull request.

[Byron]

I truly think I am missing something as thus far I refrained from making everything public, but maybe I just wasn't honest to myself. The agent can have a go real quick, let's see what comes out of this :D.