1 use 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]| 12 /// | ---------------------- | --- | ------- | 13 /// | `AnyPath` | Yes | Yes | 14 /// | `FilePath` | Yes | Yes | 15 /// | `DirPath` | Yes | Yes | 16 /// | `ExecutablePath` | Yes | Partial | 17 /// | `CommandName` | Yes | Yes | 18 /// | `CommandString` | Yes | Partial | 19 /// | `CommandWithArguments` | Yes | | 20 /// | `Username` | Yes | Yes | 21 /// | `Hostname` | Yes | Yes | 22 /// | `Url` | Yes | | 23 /// | `EmailAddress` | Yes | | 24 /// 25 /// [^1]: fish completions currently only support named arguments (e.g. -o or --opt), not 26 /// positional arguments. 27 #[derive(Debug, PartialEq, Eq, Hash, Copy, Clone)] 28 #[non_exhaustive] 29 pub enum ValueHint { 30 /// Default value if hint is not specified. Follows shell default behavior, which is usually 31 /// auto-completing filenames. 32 Unknown, 33 /// None of the hints below apply. Disables shell completion for this argument. 34 Other, 35 /// Any existing path. 36 AnyPath, 37 /// Path to a file. 38 FilePath, 39 /// Path to a directory. 40 DirPath, 41 /// Path to an executable file. 42 ExecutablePath, 43 /// Name of a command, without arguments. May be relative to PATH, or full path to executable. 44 CommandName, 45 /// A single string containing a command and its arguments. 46 CommandString, 47 /// Capture the remaining arguments as a command name and arguments for that command. This is 48 /// common when writing shell wrappers that execute anther command, for example `sudo` or `env`. 49 /// 50 /// This hint is special, the argument must be a positional argument and have 51 /// [`.num_args(1..)`] and Command must use [`Command::trailing_var_arg(true)`]. The result is that the 52 /// command line `my_app ls -la /` will be parsed as `["ls", "-la", "/"]` and clap won't try to 53 /// parse the `-la` argument itself. 54 /// 55 /// [`Command::trailing_var_arg(true)`]: crate::Command::trailing_var_arg 56 /// [`.num_args(1..)`]: crate::Arg::num_args() 57 CommandWithArguments, 58 /// Name of a local operating system user. 59 Username, 60 /// Host name of a computer. 61 /// Shells usually parse `/etc/hosts` and `.ssh/known_hosts` to complete hostnames. 62 Hostname, 63 /// Complete web address. 64 Url, 65 /// Email address. 66 EmailAddress, 67 } 68 69 impl Default for ValueHint { default() -> Self70 fn default() -> Self { 71 ValueHint::Unknown 72 } 73 } 74 75 impl FromStr for ValueHint { 76 type Err = String; from_str(s: &str) -> Result<Self, <Self as FromStr>::Err>77 fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> { 78 Ok(match &*s.to_ascii_lowercase() { 79 "unknown" => ValueHint::Unknown, 80 "other" => ValueHint::Other, 81 "anypath" => ValueHint::AnyPath, 82 "filepath" => ValueHint::FilePath, 83 "dirpath" => ValueHint::DirPath, 84 "executablepath" => ValueHint::ExecutablePath, 85 "commandname" => ValueHint::CommandName, 86 "commandstring" => ValueHint::CommandString, 87 "commandwitharguments" => ValueHint::CommandWithArguments, 88 "username" => ValueHint::Username, 89 "hostname" => ValueHint::Hostname, 90 "url" => ValueHint::Url, 91 "emailaddress" => ValueHint::EmailAddress, 92 _ => return Err(format!("unknown ValueHint: `{s}`")), 93 }) 94 } 95 } 96