clap_builder/builder/
value_hint.rs

1use std::str::FromStr;
2
3/// Provide shell with hint on how to complete an argument.
4///
5/// See [`Arg::value_hint`][crate::Arg::value_hint] to set this on an argument.
6///
7/// See the `clap_complete` crate for completion script generation.
8///
9/// Overview of which hints are supported by which shell:
10///
11/// | Hint                   | zsh | fish[^1] | dynamic |
12/// | ---------------------- | --- | ---------|---------|
13/// | `AnyPath`              | Yes | Yes      | Yes     |
14/// | `FilePath`             | Yes | Yes      | Yes     |
15/// | `DirPath`              | Yes | Yes      | Yes     |
16/// | `ExecutablePath`       | Yes | Partial  | Yes     |
17/// | `CommandName`          | Yes | Yes      | No      |
18/// | `CommandString`        | Yes | Partial  | No      |
19/// | `CommandWithArguments` | Yes |          | No      |
20/// | `Username`             | Yes | Yes      | No      |
21/// | `Hostname`             | Yes | Yes      | No      |
22/// | `Url`                  | Yes |          | No      |
23/// | `EmailAddress`         | Yes |          | No      |
24///
25/// [^1]: fish completions currently only support named arguments (e.g. -o or --opt), not
26///       positional arguments.
27#[derive(#[automatically_derived]
impl ::core::fmt::Debug for ValueHint {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::write_str(f,
            match self {
                ValueHint::Unknown => "Unknown",
                ValueHint::Other => "Other",
                ValueHint::AnyPath => "AnyPath",
                ValueHint::FilePath => "FilePath",
                ValueHint::DirPath => "DirPath",
                ValueHint::ExecutablePath => "ExecutablePath",
                ValueHint::CommandName => "CommandName",
                ValueHint::CommandString => "CommandString",
                ValueHint::CommandWithArguments => "CommandWithArguments",
                ValueHint::Username => "Username",
                ValueHint::Hostname => "Hostname",
                ValueHint::Url => "Url",
                ValueHint::EmailAddress => "EmailAddress",
            })
    }
}Debug, #[automatically_derived]
impl ::core::default::Default for ValueHint {
    #[inline]
    fn default() -> ValueHint { Self::Unknown }
}Default, #[automatically_derived]
impl ::core::cmp::PartialEq for ValueHint {
    #[inline]
    fn eq(&self, other: &ValueHint) -> bool {
        let __self_discr = ::core::intrinsics::discriminant_value(self);
        let __arg1_discr = ::core::intrinsics::discriminant_value(other);
        __self_discr == __arg1_discr
    }
}PartialEq, #[automatically_derived]
impl ::core::cmp::Eq for ValueHint {
    #[inline]
    #[doc(hidden)]
    #[coverage(off)]
    fn assert_fields_are_eq(&self) {}
}Eq, #[automatically_derived]
impl ::core::hash::Hash for ValueHint {
    #[inline]
    fn hash<__H: ::core::hash::Hasher>(&self, state: &mut __H) {
        let __self_discr = ::core::intrinsics::discriminant_value(self);
        ::core::hash::Hash::hash(&__self_discr, state)
    }
}Hash, #[automatically_derived]
impl ::core::marker::Copy for ValueHint { }Copy, #[automatically_derived]
impl ::core::clone::Clone for ValueHint {
    #[inline]
    fn clone(&self) -> ValueHint { *self }
}Clone)]
28#[non_exhaustive]
29pub enum ValueHint {
30    /// Default value if hint is not specified. Follows shell default behavior, which is usually
31    /// auto-completing filenames.
32    #[default]
33    Unknown,
34    /// None of the hints below apply. Disables shell completion for this argument.
35    Other,
36    /// Any existing path.
37    AnyPath,
38    /// Path to a file.
39    FilePath,
40    /// Path to a directory.
41    DirPath,
42    /// Path to an executable file.
43    ExecutablePath,
44    /// Name of a command, without arguments. May be relative to PATH, or full path to executable.
45    CommandName,
46    /// A single string containing a command and its arguments.
47    CommandString,
48    /// Capture the remaining arguments as a command name and arguments for that command. This is
49    /// common when writing shell wrappers that execute another command, for example `sudo` or `env`.
50    ///
51    /// This hint is special, the argument must be a positional argument and have
52    /// [`.num_args(1..)`] and Command must use [`Command::trailing_var_arg(true)`]. The result is that the
53    /// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to
54    /// parse the `-la` argument itself.
55    ///
56    /// [`Command::trailing_var_arg(true)`]: crate::Command::trailing_var_arg
57    /// [`.num_args(1..)`]: crate::Arg::num_args()
58    CommandWithArguments,
59    /// Name of a local operating system user.
60    Username,
61    /// Host name of a computer.
62    /// Shells usually parse `/etc/hosts` and `.ssh/known_hosts` to complete hostnames.
63    Hostname,
64    /// Complete web address.
65    Url,
66    /// Email address.
67    EmailAddress,
68}
69
70#[cfg(feature = "unstable-ext")]
71impl crate::builder::ArgExt for ValueHint {}
72
73impl FromStr for ValueHint {
74    type Err = String;
75    fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
76        Ok(match &*s.to_ascii_lowercase() {
77            "unknown" => ValueHint::Unknown,
78            "other" => ValueHint::Other,
79            "anypath" => ValueHint::AnyPath,
80            "filepath" => ValueHint::FilePath,
81            "dirpath" => ValueHint::DirPath,
82            "executablepath" => ValueHint::ExecutablePath,
83            "commandname" => ValueHint::CommandName,
84            "commandstring" => ValueHint::CommandString,
85            "commandwitharguments" => ValueHint::CommandWithArguments,
86            "username" => ValueHint::Username,
87            "hostname" => ValueHint::Hostname,
88            "url" => ValueHint::Url,
89            "emailaddress" => ValueHint::EmailAddress,
90            _ => return Err(::alloc::__export::must_use({
        ::alloc::fmt::format(format_args!("unknown ValueHint: `{0}`", s))
    })format!("unknown ValueHint: `{s}`")),
91        })
92    }
93}
clap_builder/builder/value_hint.rs

clap_builder/builder/
value_hint.rs
