feat: Add ArgumentSafety and Url::*_as_argument() methods

This adds three methods to `Url`:

- `Url::user_as_argument`
- `Url::host_as_argument`
- `Url::path_as_argument`

They return `ArgumentSafety` values that distingiush three cases:

1. There is no wrapped value (`Absent`).

2. The wrapped value is usable and presumably safe (`Usable`).

3. The wrapped value is dangerous and should not be passed as a
   command-line argument because it could be interpreted as an
   option due to starting with `-`. The value itself may still be
   useful and safe to include in error messages.

`user_as_argument` and `host_as_argument` are the most useful ones,
as they serve as alternatives to `user_argument_safe` and
`host_argument_safe` whose return values are unambiguous. The
`user_argument_safe` and `host_argument_safe` methods don't
distinguish between the absence of a username or host, and the
presence of a username or host that is unsafe to pass as an
argument.

`path_as_argument` included for parity, in case it is useful to
write code that handles the three cases similarly. However, there
is no underlying ambiguity in the return value of the corresponding
`path_argument_safe` method, since unlike `user` and `host`, the
`path` is not an option type.

Author: EliahKagan

gix-url/src/lib.rs

@@ -66,13 +66,13 @@ pub fn expand_path(user: Option<&expand_path::ForUser>, path: &BStr) -> Result<P
 ///
 /// This type only expresses known *syntactic* risk. It does not cover other risks, such as passing a personal access
 /// token as a username rather than a password in an application that logs usernames.
-enum ArgumentSafety<'a, T> {
+pub enum ArgumentSafety<T> {
     /// May be safe. There is nothing to pass, so there is nothing dangerous.
     Absent,
     /// May be safe. The argument does not begin with a `-` and so will not be confused as an option.
-    Usable(&'a T),
+    Usable(T),
     /// Dangerous! Begins with `-` and could be treated as an option. Use the value in error messages only.
-    Dangerous(&'a T),
+    Dangerous(T),
 }
 
 /// A URL with support for specialized git related capabilities.
@@ -200,7 +200,7 @@ impl Url {
     ///
     /// Use this method instead of [Self::user()] if the host is going to be passed to a command-line application.
     /// If the unsafe and absent cases need not be distinguished, [Self::user_argument_safe()] may also be used.
-    pub fn user_as_argument(&self) -> ArgumentSafety<str> {
+    pub fn user_as_argument(&self) -> ArgumentSafety<&str> {
         match self.user() {
             Some(user) if looks_like_command_line_option(user.as_bytes()) => ArgumentSafety::Dangerous(user),
             Some(user) => ArgumentSafety::Usable(user),
@@ -242,7 +242,7 @@ impl Url {
     ///
     /// Use this method instead of [Self::host()] if the host is going to be passed to a command-line application.
     /// If the unsafe and absent cases need not be distinguished, [Self::host_argument_safe()] may also be used.
-    pub fn host_as_argument(&self) -> ArgumentSafety<str> {
+    pub fn host_as_argument(&self) -> ArgumentSafety<&str> {
         match self.host() {
             Some(host) if looks_like_command_line_option(host.as_bytes()) => ArgumentSafety::Dangerous(host),
             Some(host) => ArgumentSafety::Usable(host),
@@ -269,7 +269,7 @@ impl Url {
     /// passed to a command-line application, unless it is certain that the leading `/` will always be included.
     ///
     /// This method never returns an [ArgumentSafety::Absent].
-    pub fn path_as_argument(&self) -> ArgumentSafety<BStr> {
+    pub fn path_as_argument(&self) -> ArgumentSafety<&BStr> {
         match self.path_argument_safe() {
             Some(path) => ArgumentSafety::Usable(path),
             None => ArgumentSafety::Dangerous(self.path.as_ref()),