clap/app/mod.rs
1mod settings;
2pub mod parser;
3mod meta;
4mod help;
5mod validator;
6mod usage;
7
8// Std
9use std::env;
10use std::ffi::{OsStr, OsString};
11use std::fmt;
12use std::io::{self, BufRead, BufWriter, Write};
13use std::path::Path;
14use std::process;
15use std::rc::Rc;
16use std::result::Result as StdResult;
17
18// Third Party
19#[cfg(feature = "yaml")]
20use yaml_rust::Yaml;
21
22// Internal
23use app::help::Help;
24use app::parser::Parser;
25use args::{AnyArg, Arg, ArgGroup, ArgMatcher, ArgMatches, ArgSettings};
26use errors::Result as ClapResult;
27pub use self::settings::AppSettings;
28use completions::Shell;
29use map::{self, VecMap};
30
31/// Used to create a representation of a command line program and all possible command line
32/// arguments. Application settings are set using the "builder pattern" with the
33/// [`App::get_matches`] family of methods being the terminal methods that starts the
34/// runtime-parsing process. These methods then return information about the user supplied
35/// arguments (or lack there of).
36///
37/// **NOTE:** There aren't any mandatory "options" that one must set. The "options" may
38/// also appear in any order (so long as one of the [`App::get_matches`] methods is the last method
39/// called).
40///
41/// # Examples
42///
43/// ```no_run
44/// # use clap::{App, Arg};
45/// let m = App::new("My Program")
46/// .author("Me, me@mail.com")
47/// .version("1.0.2")
48/// .about("Explains in brief what the program does")
49/// .arg(
50/// Arg::with_name("in_file").index(1)
51/// )
52/// .after_help("Longer explanation to appear after the options when \
53/// displaying the help information from --help or -h")
54/// .get_matches();
55///
56/// // Your program logic starts here...
57/// ```
58/// [`App::get_matches`]: ./struct.App.html#method.get_matches
59#[allow(missing_debug_implementations)]
60pub struct App<'a, 'b>
61where
62 'a: 'b,
63{
64 #[doc(hidden)] pub p: Parser<'a, 'b>,
65}
66
67
68impl<'a, 'b> App<'a, 'b> {
69 /// Creates a new instance of an application requiring a name. The name may be, but doesn't
70 /// have to be same as the binary. The name will be displayed to the user when they request to
71 /// print version or help and usage information.
72 ///
73 /// # Examples
74 ///
75 /// ```no_run
76 /// # use clap::{App, Arg};
77 /// let prog = App::new("My Program")
78 /// # ;
79 /// ```
80 pub fn new<S: Into<String>>(n: S) -> Self {
81 App {
82 p: Parser::with_name(n.into()),
83 }
84 }
85
86 /// Get the name of the app
87 pub fn get_name(&self) -> &str { &self.p.meta.name }
88
89 /// Get the name of the binary
90 pub fn get_bin_name(&self) -> Option<&str> { self.p.meta.bin_name.as_ref().map(|s| s.as_str()) }
91
92 /// Creates a new instance of an application requiring a name, but uses the [`crate_authors!`]
93 /// and [`crate_version!`] macros to fill in the [`App::author`] and [`App::version`] fields.
94 ///
95 /// # Examples
96 ///
97 /// ```no_run
98 /// # use clap::{App, Arg};
99 /// let prog = App::with_defaults("My Program")
100 /// # ;
101 /// ```
102 /// [`crate_authors!`]: ./macro.crate_authors!.html
103 /// [`crate_version!`]: ./macro.crate_version!.html
104 /// [`App::author`]: ./struct.App.html#method.author
105 /// [`App::version`]: ./struct.App.html#method.author
106 #[deprecated(since="2.14.1", note="Can never work; use explicit App::author() and App::version() calls instead")]
107 pub fn with_defaults<S: Into<String>>(n: S) -> Self {
108 let mut a = App {
109 p: Parser::with_name(n.into()),
110 };
111 a.p.meta.author = Some("Kevin K. <kbknapp@gmail.com>");
112 a.p.meta.version = Some("2.19.2");
113 a
114 }
115
116 /// Creates a new instance of [`App`] from a .yml (YAML) file. A full example of supported YAML
117 /// objects can be found in [`examples/17_yaml.rs`] and [`examples/17_yaml.yml`]. One great use
118 /// for using YAML is when supporting multiple languages and dialects, as each language could
119 /// be a distinct YAML file and determined at compiletime via `cargo` "features" in your
120 /// `Cargo.toml`
121 ///
122 /// In order to use this function you must compile `clap` with the `features = ["yaml"]` in
123 /// your settings for the `[dependencies.clap]` table of your `Cargo.toml`
124 ///
125 /// **NOTE:** Due to how the YAML objects are built there is a convenience macro for loading
126 /// the YAML file at compile time (relative to the current file, like modules work). That YAML
127 /// object can then be passed to this function.
128 ///
129 /// # Panics
130 ///
131 /// The YAML file must be properly formatted or this function will [`panic!`]. A good way to
132 /// ensure this doesn't happen is to run your program with the `--help` switch. If this passes
133 /// without error, you needn't worry because the YAML is properly formatted.
134 ///
135 /// # Examples
136 ///
137 /// The following example shows how to load a properly formatted YAML file to build an instance
138 /// of an [`App`] struct.
139 ///
140 /// ```ignore
141 /// # #[macro_use]
142 /// # extern crate clap;
143 /// # use clap::App;
144 /// # fn main() {
145 /// let yml = load_yaml!("app.yml");
146 /// let app = App::from_yaml(yml);
147 ///
148 /// // continued logic goes here, such as `app.get_matches()` etc.
149 /// # }
150 /// ```
151 /// [`App`]: ./struct.App.html
152 /// [`examples/17_yaml.rs`]: https://github.com/clap-rs/clap/blob/master/examples/17_yaml.rs
153 /// [`examples/17_yaml.yml`]: https://github.com/clap-rs/clap/blob/master/examples/17_yaml.yml
154 /// [`panic!`]: https://doc.rust-lang.org/std/macro.panic!.html
155 #[cfg(feature = "yaml")]
156 pub fn from_yaml(yaml: &'a Yaml) -> App<'a, 'a> { App::from(yaml) }
157
158 /// Sets a string of author(s) that will be displayed to the user when they
159 /// request the help information with `--help` or `-h`.
160 ///
161 /// **Pro-tip:** Use `clap`s convenience macro [`crate_authors!`] to automatically set your
162 /// application's author(s) to the same thing as your crate at compile time. See the [`examples/`]
163 /// directory for more information
164 ///
165 /// See the [`examples/`]
166 /// directory for more information
167 ///
168 /// # Examples
169 ///
170 /// ```no_run
171 /// # use clap::{App, Arg};
172 /// App::new("myprog")
173 /// .author("Me, me@mymain.com")
174 /// # ;
175 /// ```
176 /// [`crate_authors!`]: ./macro.crate_authors!.html
177 /// [`examples/`]: https://github.com/clap-rs/clap/tree/master/examples
178 pub fn author<S: Into<&'b str>>(mut self, author: S) -> Self {
179 self.p.meta.author = Some(author.into());
180 self
181 }
182
183 /// Overrides the system-determined binary name. This should only be used when absolutely
184 /// necessary, such as when the binary name for your application is misleading, or perhaps
185 /// *not* how the user should invoke your program.
186 ///
187 /// **Pro-tip:** When building things such as third party `cargo` subcommands, this setting
188 /// **should** be used!
189 ///
190 /// **NOTE:** This command **should not** be used for [`SubCommand`]s.
191 ///
192 /// # Examples
193 ///
194 /// ```no_run
195 /// # use clap::{App, Arg};
196 /// App::new("My Program")
197 /// .bin_name("my_binary")
198 /// # ;
199 /// ```
200 /// [`SubCommand`]: ./struct.SubCommand.html
201 pub fn bin_name<S: Into<String>>(mut self, name: S) -> Self {
202 self.p.meta.bin_name = Some(name.into());
203 self
204 }
205
206 /// Sets a string describing what the program does. This will be displayed when displaying help
207 /// information with `-h`.
208 ///
209 /// **NOTE:** If only `about` is provided, and not [`App::long_about`] but the user requests
210 /// `--help` clap will still display the contents of `about` appropriately
211 ///
212 /// **NOTE:** Only [`App::about`] is used in completion script generation in order to be
213 /// concise
214 ///
215 /// # Examples
216 ///
217 /// ```no_run
218 /// # use clap::{App, Arg};
219 /// App::new("myprog")
220 /// .about("Does really amazing things to great people")
221 /// # ;
222 /// ```
223 /// [`App::long_about`]: ./struct.App.html#method.long_about
224 pub fn about<S: Into<&'b str>>(mut self, about: S) -> Self {
225 self.p.meta.about = Some(about.into());
226 self
227 }
228
229 /// Sets a string describing what the program does. This will be displayed when displaying help
230 /// information.
231 ///
232 /// **NOTE:** If only `long_about` is provided, and not [`App::about`] but the user requests
233 /// `-h` clap will still display the contents of `long_about` appropriately
234 ///
235 /// **NOTE:** Only [`App::about`] is used in completion script generation in order to be
236 /// concise
237 ///
238 /// # Examples
239 ///
240 /// ```no_run
241 /// # use clap::{App, Arg};
242 /// App::new("myprog")
243 /// .long_about(
244 /// "Does really amazing things to great people. Now let's talk a little
245 /// more in depth about how this subcommand really works. It may take about
246 /// a few lines of text, but that's ok!")
247 /// # ;
248 /// ```
249 /// [`App::about`]: ./struct.App.html#method.about
250 pub fn long_about<S: Into<&'b str>>(mut self, about: S) -> Self {
251 self.p.meta.long_about = Some(about.into());
252 self
253 }
254
255 /// Sets the program's name. This will be displayed when displaying help information.
256 ///
257 /// **Pro-top:** This function is particularly useful when configuring a program via
258 /// [`App::from_yaml`] in conjunction with the [`crate_name!`] macro to derive the program's
259 /// name from its `Cargo.toml`.
260 ///
261 /// # Examples
262 /// ```ignore
263 /// # #[macro_use]
264 /// # extern crate clap;
265 /// # use clap::App;
266 /// # fn main() {
267 /// let yml = load_yaml!("app.yml");
268 /// let app = App::from_yaml(yml)
269 /// .name(crate_name!());
270 ///
271 /// // continued logic goes here, such as `app.get_matches()` etc.
272 /// # }
273 /// ```
274 ///
275 /// [`App::from_yaml`]: ./struct.App.html#method.from_yaml
276 /// [`crate_name!`]: ./macro.crate_name.html
277 pub fn name<S: Into<String>>(mut self, name: S) -> Self {
278 self.p.meta.name = name.into();
279 self
280 }
281
282 /// Adds additional help information to be displayed in addition to auto-generated help. This
283 /// information is displayed **after** the auto-generated help information. This is often used
284 /// to describe how to use the arguments, or caveats to be noted.
285 ///
286 /// # Examples
287 ///
288 /// ```no_run
289 /// # use clap::App;
290 /// App::new("myprog")
291 /// .after_help("Does really amazing things to great people...but be careful with -R")
292 /// # ;
293 /// ```
294 pub fn after_help<S: Into<&'b str>>(mut self, help: S) -> Self {
295 self.p.meta.more_help = Some(help.into());
296 self
297 }
298
299 /// Adds additional help information to be displayed in addition to auto-generated help. This
300 /// information is displayed **before** the auto-generated help information. This is often used
301 /// for header information.
302 ///
303 /// # Examples
304 ///
305 /// ```no_run
306 /// # use clap::App;
307 /// App::new("myprog")
308 /// .before_help("Some info I'd like to appear before the help info")
309 /// # ;
310 /// ```
311 pub fn before_help<S: Into<&'b str>>(mut self, help: S) -> Self {
312 self.p.meta.pre_help = Some(help.into());
313 self
314 }
315
316 /// Sets a string of the version number to be displayed when displaying version or help
317 /// information with `-V`.
318 ///
319 /// **NOTE:** If only `version` is provided, and not [`App::long_version`] but the user
320 /// requests `--version` clap will still display the contents of `version` appropriately
321 ///
322 /// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to automatically set your
323 /// application's version to the same thing as your crate at compile time. See the [`examples/`]
324 /// directory for more information
325 ///
326 /// # Examples
327 ///
328 /// ```no_run
329 /// # use clap::{App, Arg};
330 /// App::new("myprog")
331 /// .version("v0.1.24")
332 /// # ;
333 /// ```
334 /// [`crate_version!`]: ./macro.crate_version!.html
335 /// [`examples/`]: https://github.com/clap-rs/clap/tree/master/examples
336 /// [`App::long_version`]: ./struct.App.html#method.long_version
337 pub fn version<S: Into<&'b str>>(mut self, ver: S) -> Self {
338 self.p.meta.version = Some(ver.into());
339 self
340 }
341
342 /// Sets a string of the version number to be displayed when displaying version or help
343 /// information with `--version`.
344 ///
345 /// **NOTE:** If only `long_version` is provided, and not [`App::version`] but the user
346 /// requests `-V` clap will still display the contents of `long_version` appropriately
347 ///
348 /// **Pro-tip:** Use `clap`s convenience macro [`crate_version!`] to automatically set your
349 /// application's version to the same thing as your crate at compile time. See the [`examples/`]
350 /// directory for more information
351 ///
352 /// # Examples
353 ///
354 /// ```no_run
355 /// # use clap::{App, Arg};
356 /// App::new("myprog")
357 /// .long_version(
358 /// "v0.1.24
359 /// commit: abcdef89726d
360 /// revision: 123
361 /// release: 2
362 /// binary: myprog")
363 /// # ;
364 /// ```
365 /// [`crate_version!`]: ./macro.crate_version!.html
366 /// [`examples/`]: https://github.com/clap-rs/clap/tree/master/examples
367 /// [`App::version`]: ./struct.App.html#method.version
368 pub fn long_version<S: Into<&'b str>>(mut self, ver: S) -> Self {
369 self.p.meta.long_version = Some(ver.into());
370 self
371 }
372
373 /// Sets a custom usage string to override the auto-generated usage string.
374 ///
375 /// This will be displayed to the user when errors are found in argument parsing, or when you
376 /// call [`ArgMatches::usage`]
377 ///
378 /// **CAUTION:** Using this setting disables `clap`s "context-aware" usage strings. After this
379 /// setting is set, this will be the only usage string displayed to the user!
380 ///
381 /// **NOTE:** You do not need to specify the "USAGE: \n\t" portion, as that will
382 /// still be applied by `clap`, you only need to specify the portion starting
383 /// with the binary name.
384 ///
385 /// **NOTE:** This will not replace the entire help message, *only* the portion
386 /// showing the usage.
387 ///
388 /// # Examples
389 ///
390 /// ```no_run
391 /// # use clap::{App, Arg};
392 /// App::new("myprog")
393 /// .usage("myapp [-clDas] <some_file>")
394 /// # ;
395 /// ```
396 /// [`ArgMatches::usage`]: ./struct.ArgMatches.html#method.usage
397 pub fn usage<S: Into<&'b str>>(mut self, usage: S) -> Self {
398 self.p.meta.usage_str = Some(usage.into());
399 self
400 }
401
402 /// Sets a custom help message and overrides the auto-generated one. This should only be used
403 /// when the auto-generated message does not suffice.
404 ///
405 /// This will be displayed to the user when they use `--help` or `-h`
406 ///
407 /// **NOTE:** This replaces the **entire** help message, so nothing will be auto-generated.
408 ///
409 /// **NOTE:** This **only** replaces the help message for the current command, meaning if you
410 /// are using subcommands, those help messages will still be auto-generated unless you
411 /// specify a [`Arg::help`] for them as well.
412 ///
413 /// # Examples
414 ///
415 /// ```no_run
416 /// # use clap::{App, Arg};
417 /// App::new("myapp")
418 /// .help("myapp v1.0\n\
419 /// Does awesome things\n\
420 /// (C) me@mail.com\n\n\
421 ///
422 /// USAGE: myapp <opts> <command>\n\n\
423 ///
424 /// Options:\n\
425 /// -h, --help Display this message\n\
426 /// -V, --version Display version info\n\
427 /// -s <stuff> Do something with stuff\n\
428 /// -v Be verbose\n\n\
429 ///
430 /// Commmands:\n\
431 /// help Prints this message\n\
432 /// work Do some work")
433 /// # ;
434 /// ```
435 /// [`Arg::help`]: ./struct.Arg.html#method.help
436 pub fn help<S: Into<&'b str>>(mut self, help: S) -> Self {
437 self.p.meta.help_str = Some(help.into());
438 self
439 }
440
441 /// Sets the [`short`] for the auto-generated `help` argument.
442 ///
443 /// By default `clap` automatically assigns `h`, but this can be overridden if you have a
444 /// different argument which you'd prefer to use the `-h` short with. This can be done by
445 /// defining your own argument with a lowercase `h` as the [`short`].
446 ///
447 /// `clap` lazily generates these `help` arguments **after** you've defined any arguments of
448 /// your own.
449 ///
450 /// **NOTE:** Any leading `-` characters will be stripped, and only the first
451 /// non `-` character will be used as the [`short`] version
452 ///
453 /// # Examples
454 ///
455 /// ```no_run
456 /// # use clap::{App, Arg};
457 /// App::new("myprog")
458 /// .help_short("H") // Using an uppercase `H` instead of the default lowercase `h`
459 /// # ;
460 /// ```
461 /// [`short`]: ./struct.Arg.html#method.short
462 pub fn help_short<S: AsRef<str> + 'b>(mut self, s: S) -> Self {
463 self.p.help_short(s.as_ref());
464 self
465 }
466
467 /// Sets the [`short`] for the auto-generated `version` argument.
468 ///
469 /// By default `clap` automatically assigns `V`, but this can be overridden if you have a
470 /// different argument which you'd prefer to use the `-V` short with. This can be done by
471 /// defining your own argument with an uppercase `V` as the [`short`].
472 ///
473 /// `clap` lazily generates these `version` arguments **after** you've defined any arguments of
474 /// your own.
475 ///
476 /// **NOTE:** Any leading `-` characters will be stripped, and only the first
477 /// non `-` character will be used as the `short` version
478 ///
479 /// # Examples
480 ///
481 /// ```no_run
482 /// # use clap::{App, Arg};
483 /// App::new("myprog")
484 /// .version_short("v") // Using a lowercase `v` instead of the default capital `V`
485 /// # ;
486 /// ```
487 /// [`short`]: ./struct.Arg.html#method.short
488 pub fn version_short<S: AsRef<str>>(mut self, s: S) -> Self {
489 self.p.version_short(s.as_ref());
490 self
491 }
492
493 /// Sets the help text for the auto-generated `help` argument.
494 ///
495 /// By default `clap` sets this to `"Prints help information"`, but if you're using a
496 /// different convention for your help messages and would prefer a different phrasing you can
497 /// override it.
498 ///
499 /// # Examples
500 ///
501 /// ```no_run
502 /// # use clap::{App, Arg};
503 /// App::new("myprog")
504 /// .help_message("Print help information") // Perhaps you want imperative help messages
505 ///
506 /// # ;
507 /// ```
508 pub fn help_message<S: Into<&'a str>>(mut self, s: S) -> Self {
509 self.p.help_message = Some(s.into());
510 self
511 }
512
513 /// Sets the help text for the auto-generated `version` argument.
514 ///
515 /// By default `clap` sets this to `"Prints version information"`, but if you're using a
516 /// different convention for your help messages and would prefer a different phrasing then you
517 /// can change it.
518 ///
519 /// # Examples
520 /// ```no_run
521 /// # use clap::{App, Arg};
522 /// App::new("myprog")
523 /// .version_message("Print version information") // Perhaps you want imperative help messages
524 /// # ;
525 /// ```
526 pub fn version_message<S: Into<&'a str>>(mut self, s: S) -> Self {
527 self.p.version_message = Some(s.into());
528 self
529 }
530
531 /// Sets the help template to be used, overriding the default format.
532 ///
533 /// Tags arg given inside curly brackets.
534 ///
535 /// Valid tags are:
536 ///
537 /// * `{bin}` - Binary name.
538 /// * `{version}` - Version number.
539 /// * `{author}` - Author information.
540 /// * `{about}` - General description (from [`App::about`])
541 /// * `{usage}` - Automatically generated or given usage string.
542 /// * `{all-args}` - Help for all arguments (options, flags, positionals arguments,
543 /// and subcommands) including titles.
544 /// * `{unified}` - Unified help for options and flags. Note, you must *also* set
545 /// [`AppSettings::UnifiedHelpMessage`] to fully merge both options and
546 /// flags, otherwise the ordering is "best effort"
547 /// * `{flags}` - Help for flags.
548 /// * `{options}` - Help for options.
549 /// * `{positionals}` - Help for positionals arguments.
550 /// * `{subcommands}` - Help for subcommands.
551 /// * `{after-help}` - Help from [`App::after_help`]
552 /// * `{before-help}` - Help from [`App::before_help`]
553 ///
554 /// # Examples
555 ///
556 /// ```no_run
557 /// # use clap::{App, Arg};
558 /// App::new("myprog")
559 /// .version("1.0")
560 /// .template("{bin} ({version}) - {usage}")
561 /// # ;
562 /// ```
563 /// **NOTE:** The template system is, on purpose, very simple. Therefore the tags have to be
564 /// written in lowercase and without spacing.
565 ///
566 /// [`App::about`]: ./struct.App.html#method.about
567 /// [`App::after_help`]: ./struct.App.html#method.after_help
568 /// [`App::before_help`]: ./struct.App.html#method.before_help
569 /// [`AppSettings::UnifiedHelpMessage`]: ./enum.AppSettings.html#variant.UnifiedHelpMessage
570 pub fn template<S: Into<&'b str>>(mut self, s: S) -> Self {
571 self.p.meta.template = Some(s.into());
572 self
573 }
574
575 /// Enables a single command, or [`SubCommand`], level settings.
576 ///
577 /// See [`AppSettings`] for a full list of possibilities and examples.
578 ///
579 /// # Examples
580 ///
581 /// ```no_run
582 /// # use clap::{App, Arg, AppSettings};
583 /// App::new("myprog")
584 /// .setting(AppSettings::SubcommandRequired)
585 /// .setting(AppSettings::WaitOnError)
586 /// # ;
587 /// ```
588 /// [`SubCommand`]: ./struct.SubCommand.html
589 /// [`AppSettings`]: ./enum.AppSettings.html
590 pub fn setting(mut self, setting: AppSettings) -> Self {
591 self.p.set(setting);
592 self
593 }
594
595 /// Enables multiple command, or [`SubCommand`], level settings
596 ///
597 /// See [`AppSettings`] for a full list of possibilities and examples.
598 ///
599 /// # Examples
600 ///
601 /// ```no_run
602 /// # use clap::{App, Arg, AppSettings};
603 /// App::new("myprog")
604 /// .settings(&[AppSettings::SubcommandRequired,
605 /// AppSettings::WaitOnError])
606 /// # ;
607 /// ```
608 /// [`SubCommand`]: ./struct.SubCommand.html
609 /// [`AppSettings`]: ./enum.AppSettings.html
610 pub fn settings(mut self, settings: &[AppSettings]) -> Self {
611 for s in settings {
612 self.p.set(*s);
613 }
614 self
615 }
616
617 /// Enables a single setting that is propagated down through all child [`SubCommand`]s.
618 ///
619 /// See [`AppSettings`] for a full list of possibilities and examples.
620 ///
621 /// **NOTE**: The setting is *only* propagated *down* and not up through parent commands.
622 ///
623 /// # Examples
624 ///
625 /// ```no_run
626 /// # use clap::{App, Arg, AppSettings};
627 /// App::new("myprog")
628 /// .global_setting(AppSettings::SubcommandRequired)
629 /// # ;
630 /// ```
631 /// [`SubCommand`]: ./struct.SubCommand.html
632 /// [`AppSettings`]: ./enum.AppSettings.html
633 pub fn global_setting(mut self, setting: AppSettings) -> Self {
634 self.p.set(setting);
635 self.p.g_settings.set(setting);
636 self
637 }
638
639 /// Enables multiple settings which are propagated *down* through all child [`SubCommand`]s.
640 ///
641 /// See [`AppSettings`] for a full list of possibilities and examples.
642 ///
643 /// **NOTE**: The setting is *only* propagated *down* and not up through parent commands.
644 ///
645 /// # Examples
646 ///
647 /// ```no_run
648 /// # use clap::{App, Arg, AppSettings};
649 /// App::new("myprog")
650 /// .global_settings(&[AppSettings::SubcommandRequired,
651 /// AppSettings::ColoredHelp])
652 /// # ;
653 /// ```
654 /// [`SubCommand`]: ./struct.SubCommand.html
655 /// [`AppSettings`]: ./enum.AppSettings.html
656 pub fn global_settings(mut self, settings: &[AppSettings]) -> Self {
657 for s in settings {
658 self.p.set(*s);
659 self.p.g_settings.set(*s)
660 }
661 self
662 }
663
664 /// Disables a single command, or [`SubCommand`], level setting.
665 ///
666 /// See [`AppSettings`] for a full list of possibilities and examples.
667 ///
668 /// # Examples
669 ///
670 /// ```no_run
671 /// # use clap::{App, AppSettings};
672 /// App::new("myprog")
673 /// .unset_setting(AppSettings::ColorAuto)
674 /// # ;
675 /// ```
676 /// [`SubCommand`]: ./struct.SubCommand.html
677 /// [`AppSettings`]: ./enum.AppSettings.html
678 pub fn unset_setting(mut self, setting: AppSettings) -> Self {
679 self.p.unset(setting);
680 self
681 }
682
683 /// Disables multiple command, or [`SubCommand`], level settings.
684 ///
685 /// See [`AppSettings`] for a full list of possibilities and examples.
686 ///
687 /// # Examples
688 ///
689 /// ```no_run
690 /// # use clap::{App, AppSettings};
691 /// App::new("myprog")
692 /// .unset_settings(&[AppSettings::ColorAuto,
693 /// AppSettings::AllowInvalidUtf8])
694 /// # ;
695 /// ```
696 /// [`SubCommand`]: ./struct.SubCommand.html
697 /// [`AppSettings`]: ./enum.AppSettings.html
698 pub fn unset_settings(mut self, settings: &[AppSettings]) -> Self {
699 for s in settings {
700 self.p.unset(*s);
701 }
702 self
703 }
704
705 /// Sets the terminal width at which to wrap help messages. Defaults to `120`. Using `0` will
706 /// ignore terminal widths and use source formatting.
707 ///
708 /// `clap` automatically tries to determine the terminal width on Unix, Linux, macOS and Windows
709 /// if the `wrap_help` cargo "feature" has been used while compiling. If the terminal width
710 /// cannot be determined, `clap` defaults to `120`.
711 ///
712 /// **NOTE:** This setting applies globally and *not* on a per-command basis.
713 ///
714 /// **NOTE:** This setting must be set **before** any subcommands are added!
715 ///
716 /// # Platform Specific
717 ///
718 /// Only Unix, Linux, macOS and Windows support automatic determination of terminal width.
719 /// Even on those platforms, this setting is useful if for any reason the terminal width
720 /// cannot be determined.
721 ///
722 /// # Examples
723 ///
724 /// ```no_run
725 /// # use clap::App;
726 /// App::new("myprog")
727 /// .set_term_width(80)
728 /// # ;
729 /// ```
730 pub fn set_term_width(mut self, width: usize) -> Self {
731 self.p.meta.term_w = Some(width);
732 self
733 }
734
735 /// Sets the max terminal width at which to wrap help messages. Using `0` will ignore terminal
736 /// widths and use source formatting.
737 ///
738 /// `clap` automatically tries to determine the terminal width on Unix, Linux, macOS and Windows
739 /// if the `wrap_help` cargo "feature" has been used while compiling, but one might want to
740 /// limit the size (e.g. when the terminal is running fullscreen).
741 ///
742 /// **NOTE:** This setting applies globally and *not* on a per-command basis.
743 ///
744 /// **NOTE:** This setting must be set **before** any subcommands are added!
745 ///
746 /// # Platform Specific
747 ///
748 /// Only Unix, Linux, macOS and Windows support automatic determination of terminal width.
749 ///
750 /// # Examples
751 ///
752 /// ```no_run
753 /// # use clap::App;
754 /// App::new("myprog")
755 /// .max_term_width(100)
756 /// # ;
757 /// ```
758 pub fn max_term_width(mut self, w: usize) -> Self {
759 self.p.meta.max_w = Some(w);
760 self
761 }
762
763 /// Adds an [argument] to the list of valid possibilities.
764 ///
765 /// # Examples
766 ///
767 /// ```no_run
768 /// # use clap::{App, Arg};
769 /// App::new("myprog")
770 /// // Adding a single "flag" argument with a short and help text, using Arg::with_name()
771 /// .arg(
772 /// Arg::with_name("debug")
773 /// .short("d")
774 /// .help("turns on debugging mode")
775 /// )
776 /// // Adding a single "option" argument with a short, a long, and help text using the less
777 /// // verbose Arg::from_usage()
778 /// .arg(
779 /// Arg::from_usage("-c --config=[CONFIG] 'Optionally sets a config file to use'")
780 /// )
781 /// # ;
782 /// ```
783 /// [argument]: ./struct.Arg.html
784 pub fn arg<A: Into<Arg<'a, 'b>>>(mut self, a: A) -> Self {
785 self.p.add_arg(a.into());
786 self
787 }
788
789 /// Adds multiple [arguments] to the list of valid possibilities
790 ///
791 /// # Examples
792 ///
793 /// ```no_run
794 /// # use clap::{App, Arg};
795 /// App::new("myprog")
796 /// .args(
797 /// &[Arg::from_usage("[debug] -d 'turns on debugging info'"),
798 /// Arg::with_name("input").index(1).help("the input file to use")]
799 /// )
800 /// # ;
801 /// ```
802 /// [arguments]: ./struct.Arg.html
803 pub fn args(mut self, args: &[Arg<'a, 'b>]) -> Self {
804 for arg in args {
805 self.p.add_arg_ref(arg);
806 }
807 self
808 }
809
810 /// A convenience method for adding a single [argument] from a usage type string. The string
811 /// used follows the same rules and syntax as [`Arg::from_usage`]
812 ///
813 /// **NOTE:** The downside to using this method is that you can not set any additional
814 /// properties of the [`Arg`] other than what [`Arg::from_usage`] supports.
815 ///
816 /// # Examples
817 ///
818 /// ```no_run
819 /// # use clap::{App, Arg};
820 /// App::new("myprog")
821 /// .arg_from_usage("-c --config=<FILE> 'Sets a configuration file to use'")
822 /// # ;
823 /// ```
824 /// [argument]: ./struct.Arg.html
825 /// [`Arg`]: ./struct.Arg.html
826 /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage
827 pub fn arg_from_usage(mut self, usage: &'a str) -> Self {
828 self.p.add_arg(Arg::from_usage(usage));
829 self
830 }
831
832 /// Adds multiple [arguments] at once from a usage string, one per line. See
833 /// [`Arg::from_usage`] for details on the syntax and rules supported.
834 ///
835 /// **NOTE:** Like [`App::arg_from_usage`] the downside is you only set properties for the
836 /// [`Arg`]s which [`Arg::from_usage`] supports.
837 ///
838 /// # Examples
839 ///
840 /// ```no_run
841 /// # use clap::{App, Arg};
842 /// App::new("myprog")
843 /// .args_from_usage(
844 /// "-c --config=[FILE] 'Sets a configuration file to use'
845 /// [debug]... -d 'Sets the debugging level'
846 /// <FILE> 'The input file to use'"
847 /// )
848 /// # ;
849 /// ```
850 /// [arguments]: ./struct.Arg.html
851 /// [`Arg::from_usage`]: ./struct.Arg.html#method.from_usage
852 /// [`App::arg_from_usage`]: ./struct.App.html#method.arg_from_usage
853 /// [`Arg`]: ./struct.Arg.html
854 pub fn args_from_usage(mut self, usage: &'a str) -> Self {
855 for line in usage.lines() {
856 let l = line.trim();
857 if l.is_empty() {
858 continue;
859 }
860 self.p.add_arg(Arg::from_usage(l));
861 }
862 self
863 }
864
865 /// Allows adding a [`SubCommand`] alias, which function as "hidden" subcommands that
866 /// automatically dispatch as if this subcommand was used. This is more efficient, and easier
867 /// than creating multiple hidden subcommands as one only needs to check for the existence of
868 /// this command, and not all variants.
869 ///
870 /// # Examples
871 ///
872 /// ```no_run
873 /// # use clap::{App, Arg, SubCommand};
874 /// let m = App::new("myprog")
875 /// .subcommand(SubCommand::with_name("test")
876 /// .alias("do-stuff"))
877 /// .get_matches_from(vec!["myprog", "do-stuff"]);
878 /// assert_eq!(m.subcommand_name(), Some("test"));
879 /// ```
880 /// [`SubCommand`]: ./struct.SubCommand.html
881 pub fn alias<S: Into<&'b str>>(mut self, name: S) -> Self {
882 if let Some(ref mut als) = self.p.meta.aliases {
883 als.push((name.into(), false));
884 } else {
885 self.p.meta.aliases = Some(vec![(name.into(), false)]);
886 }
887 self
888 }
889
890 /// Allows adding [`SubCommand`] aliases, which function as "hidden" subcommands that
891 /// automatically dispatch as if this subcommand was used. This is more efficient, and easier
892 /// than creating multiple hidden subcommands as one only needs to check for the existence of
893 /// this command, and not all variants.
894 ///
895 /// # Examples
896 ///
897 /// ```rust
898 /// # use clap::{App, Arg, SubCommand};
899 /// let m = App::new("myprog")
900 /// .subcommand(SubCommand::with_name("test")
901 /// .aliases(&["do-stuff", "do-tests", "tests"]))
902 /// .arg(Arg::with_name("input")
903 /// .help("the file to add")
904 /// .index(1)
905 /// .required(false))
906 /// .get_matches_from(vec!["myprog", "do-tests"]);
907 /// assert_eq!(m.subcommand_name(), Some("test"));
908 /// ```
909 /// [`SubCommand`]: ./struct.SubCommand.html
910 pub fn aliases(mut self, names: &[&'b str]) -> Self {
911 if let Some(ref mut als) = self.p.meta.aliases {
912 for n in names {
913 als.push((n, false));
914 }
915 } else {
916 self.p.meta.aliases = Some(names.iter().map(|n| (*n, false)).collect::<Vec<_>>());
917 }
918 self
919 }
920
921 /// Allows adding a [`SubCommand`] alias that functions exactly like those defined with
922 /// [`App::alias`], except that they are visible inside the help message.
923 ///
924 /// # Examples
925 ///
926 /// ```no_run
927 /// # use clap::{App, Arg, SubCommand};
928 /// let m = App::new("myprog")
929 /// .subcommand(SubCommand::with_name("test")
930 /// .visible_alias("do-stuff"))
931 /// .get_matches_from(vec!["myprog", "do-stuff"]);
932 /// assert_eq!(m.subcommand_name(), Some("test"));
933 /// ```
934 /// [`SubCommand`]: ./struct.SubCommand.html
935 /// [`App::alias`]: ./struct.App.html#method.alias
936 pub fn visible_alias<S: Into<&'b str>>(mut self, name: S) -> Self {
937 if let Some(ref mut als) = self.p.meta.aliases {
938 als.push((name.into(), true));
939 } else {
940 self.p.meta.aliases = Some(vec![(name.into(), true)]);
941 }
942 self
943 }
944
945 /// Allows adding multiple [`SubCommand`] aliases that functions exactly like those defined
946 /// with [`App::aliases`], except that they are visible inside the help message.
947 ///
948 /// # Examples
949 ///
950 /// ```no_run
951 /// # use clap::{App, Arg, SubCommand};
952 /// let m = App::new("myprog")
953 /// .subcommand(SubCommand::with_name("test")
954 /// .visible_aliases(&["do-stuff", "tests"]))
955 /// .get_matches_from(vec!["myprog", "do-stuff"]);
956 /// assert_eq!(m.subcommand_name(), Some("test"));
957 /// ```
958 /// [`SubCommand`]: ./struct.SubCommand.html
959 /// [`App::aliases`]: ./struct.App.html#method.aliases
960 pub fn visible_aliases(mut self, names: &[&'b str]) -> Self {
961 if let Some(ref mut als) = self.p.meta.aliases {
962 for n in names {
963 als.push((n, true));
964 }
965 } else {
966 self.p.meta.aliases = Some(names.iter().map(|n| (*n, true)).collect::<Vec<_>>());
967 }
968 self
969 }
970
971 /// Adds an [`ArgGroup`] to the application. [`ArgGroup`]s are a family of related arguments.
972 /// By placing them in a logical group, you can build easier requirement and exclusion rules.
973 /// For instance, you can make an entire [`ArgGroup`] required, meaning that one (and *only*
974 /// one) argument from that group must be present at runtime.
975 ///
976 /// You can also do things such as name an [`ArgGroup`] as a conflict to another argument.
977 /// Meaning any of the arguments that belong to that group will cause a failure if present with
978 /// the conflicting argument.
979 ///
980 /// Another added benefit of [`ArgGroup`]s is that you can extract a value from a group instead
981 /// of determining exactly which argument was used.
982 ///
983 /// Finally, using [`ArgGroup`]s to ensure exclusion between arguments is another very common
984 /// use
985 ///
986 /// # Examples
987 ///
988 /// The following example demonstrates using an [`ArgGroup`] to ensure that one, and only one,
989 /// of the arguments from the specified group is present at runtime.
990 ///
991 /// ```no_run
992 /// # use clap::{App, ArgGroup};
993 /// App::new("app")
994 /// .args_from_usage(
995 /// "--set-ver [ver] 'set the version manually'
996 /// --major 'auto increase major'
997 /// --minor 'auto increase minor'
998 /// --patch 'auto increase patch'")
999 /// .group(ArgGroup::with_name("vers")
1000 /// .args(&["set-ver", "major", "minor","patch"])
1001 /// .required(true))
1002 /// # ;
1003 /// ```
1004 /// [`ArgGroup`]: ./struct.ArgGroup.html
1005 pub fn group(mut self, group: ArgGroup<'a>) -> Self {
1006 self.p.add_group(group);
1007 self
1008 }
1009
1010 /// Adds multiple [`ArgGroup`]s to the [`App`] at once.
1011 ///
1012 /// # Examples
1013 ///
1014 /// ```no_run
1015 /// # use clap::{App, ArgGroup};
1016 /// App::new("app")
1017 /// .args_from_usage(
1018 /// "--set-ver [ver] 'set the version manually'
1019 /// --major 'auto increase major'
1020 /// --minor 'auto increase minor'
1021 /// --patch 'auto increase patch'
1022 /// -c [FILE] 'a config file'
1023 /// -i [IFACE] 'an interface'")
1024 /// .groups(&[
1025 /// ArgGroup::with_name("vers")
1026 /// .args(&["set-ver", "major", "minor","patch"])
1027 /// .required(true),
1028 /// ArgGroup::with_name("input")
1029 /// .args(&["c", "i"])
1030 /// ])
1031 /// # ;
1032 /// ```
1033 /// [`ArgGroup`]: ./struct.ArgGroup.html
1034 /// [`App`]: ./struct.App.html
1035 pub fn groups(mut self, groups: &[ArgGroup<'a>]) -> Self {
1036 for g in groups {
1037 self = self.group(g.into());
1038 }
1039 self
1040 }
1041
1042 /// Adds a [`SubCommand`] to the list of valid possibilities. Subcommands are effectively
1043 /// sub-[`App`]s, because they can contain their own arguments, subcommands, version, usage,
1044 /// etc. They also function just like [`App`]s, in that they get their own auto generated help,
1045 /// version, and usage.
1046 ///
1047 /// # Examples
1048 ///
1049 /// ```no_run
1050 /// # use clap::{App, Arg, SubCommand};
1051 /// App::new("myprog")
1052 /// .subcommand(SubCommand::with_name("config")
1053 /// .about("Controls configuration features")
1054 /// .arg_from_usage("<config> 'Required configuration file to use'"))
1055 /// # ;
1056 /// ```
1057 /// [`SubCommand`]: ./struct.SubCommand.html
1058 /// [`App`]: ./struct.App.html
1059 pub fn subcommand(mut self, subcmd: App<'a, 'b>) -> Self {
1060 self.p.add_subcommand(subcmd);
1061 self
1062 }
1063
1064 /// Adds multiple subcommands to the list of valid possibilities by iterating over an
1065 /// [`IntoIterator`] of [`SubCommand`]s
1066 ///
1067 /// # Examples
1068 ///
1069 /// ```rust
1070 /// # use clap::{App, Arg, SubCommand};
1071 /// # App::new("myprog")
1072 /// .subcommands( vec![
1073 /// SubCommand::with_name("config").about("Controls configuration functionality")
1074 /// .arg(Arg::with_name("config_file").index(1)),
1075 /// SubCommand::with_name("debug").about("Controls debug functionality")])
1076 /// # ;
1077 /// ```
1078 /// [`SubCommand`]: ./struct.SubCommand.html
1079 /// [`IntoIterator`]: https://doc.rust-lang.org/std/iter/trait.IntoIterator.html
1080 pub fn subcommands<I>(mut self, subcmds: I) -> Self
1081 where
1082 I: IntoIterator<Item = App<'a, 'b>>,
1083 {
1084 for subcmd in subcmds {
1085 self.p.add_subcommand(subcmd);
1086 }
1087 self
1088 }
1089
1090 /// Allows custom ordering of [`SubCommand`]s within the help message. Subcommands with a lower
1091 /// value will be displayed first in the help message. This is helpful when one would like to
1092 /// emphasise frequently used subcommands, or prioritize those towards the top of the list.
1093 /// Duplicate values **are** allowed. Subcommands with duplicate display orders will be
1094 /// displayed in alphabetical order.
1095 ///
1096 /// **NOTE:** The default is 999 for all subcommands.
1097 ///
1098 /// # Examples
1099 ///
1100 /// ```rust
1101 /// # use clap::{App, SubCommand};
1102 /// let m = App::new("cust-ord")
1103 /// .subcommand(SubCommand::with_name("alpha") // typically subcommands are grouped
1104 /// // alphabetically by name. Subcommands
1105 /// // without a display_order have a value of
1106 /// // 999 and are displayed alphabetically with
1107 /// // all other 999 subcommands
1108 /// .about("Some help and text"))
1109 /// .subcommand(SubCommand::with_name("beta")
1110 /// .display_order(1) // In order to force this subcommand to appear *first*
1111 /// // all we have to do is give it a value lower than 999.
1112 /// // Any other subcommands with a value of 1 will be displayed
1113 /// // alphabetically with this one...then 2 values, then 3, etc.
1114 /// .about("I should be first!"))
1115 /// .get_matches_from(vec![
1116 /// "cust-ord", "--help"
1117 /// ]);
1118 /// ```
1119 ///
1120 /// The above example displays the following help message
1121 ///
1122 /// ```text
1123 /// cust-ord
1124 ///
1125 /// USAGE:
1126 /// cust-ord [FLAGS] [OPTIONS]
1127 ///
1128 /// FLAGS:
1129 /// -h, --help Prints help information
1130 /// -V, --version Prints version information
1131 ///
1132 /// SUBCOMMANDS:
1133 /// beta I should be first!
1134 /// alpha Some help and text
1135 /// ```
1136 /// [`SubCommand`]: ./struct.SubCommand.html
1137 pub fn display_order(mut self, ord: usize) -> Self {
1138 self.p.meta.disp_ord = ord;
1139 self
1140 }
1141
1142 /// Prints the full help message to [`io::stdout()`] using a [`BufWriter`] using the same
1143 /// method as if someone ran `-h` to request the help message
1144 ///
1145 /// **NOTE:** clap has the ability to distinguish between "short" and "long" help messages
1146 /// depending on if the user ran [`-h` (short)] or [`--help` (long)]
1147 ///
1148 /// # Examples
1149 ///
1150 /// ```rust
1151 /// # use clap::App;
1152 /// let mut app = App::new("myprog");
1153 /// app.print_help();
1154 /// ```
1155 /// [`io::stdout()`]: https://doc.rust-lang.org/std/io/fn.stdout.html
1156 /// [`BufWriter`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html
1157 /// [`-h` (short)]: ./struct.Arg.html#method.help
1158 /// [`--help` (long)]: ./struct.Arg.html#method.long_help
1159 pub fn print_help(&mut self) -> ClapResult<()> {
1160 // If there are global arguments, or settings we need to propagate them down to subcommands
1161 // before parsing incase we run into a subcommand
1162 self.p.propagate_globals();
1163 self.p.propagate_settings();
1164 self.p.derive_display_order();
1165
1166 self.p.create_help_and_version();
1167 let out = io::stdout();
1168 let mut buf_w = BufWriter::new(out.lock());
1169 self.write_help(&mut buf_w)
1170 }
1171
1172 /// Prints the full help message to [`io::stdout()`] using a [`BufWriter`] using the same
1173 /// method as if someone ran `--help` to request the help message
1174 ///
1175 /// **NOTE:** clap has the ability to distinguish between "short" and "long" help messages
1176 /// depending on if the user ran [`-h` (short)] or [`--help` (long)]
1177 ///
1178 /// # Examples
1179 ///
1180 /// ```rust
1181 /// # use clap::App;
1182 /// let mut app = App::new("myprog");
1183 /// app.print_long_help();
1184 /// ```
1185 /// [`io::stdout()`]: https://doc.rust-lang.org/std/io/fn.stdout.html
1186 /// [`BufWriter`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html
1187 /// [`-h` (short)]: ./struct.Arg.html#method.help
1188 /// [`--help` (long)]: ./struct.Arg.html#method.long_help
1189 pub fn print_long_help(&mut self) -> ClapResult<()> {
1190 let out = io::stdout();
1191 let mut buf_w = BufWriter::new(out.lock());
1192 self.write_long_help(&mut buf_w)
1193 }
1194
1195 /// Writes the full help message to the user to a [`io::Write`] object in the same method as if
1196 /// the user ran `-h`
1197 ///
1198 /// **NOTE:** clap has the ability to distinguish between "short" and "long" help messages
1199 /// depending on if the user ran [`-h` (short)] or [`--help` (long)]
1200 ///
1201 /// **NOTE:** There is a known bug where this method does not write propagated global arguments
1202 /// or autogenerated arguments (i.e. the default help/version args). Prefer
1203 /// [`App::write_long_help`] instead if possible!
1204 ///
1205 /// # Examples
1206 ///
1207 /// ```rust
1208 /// # use clap::App;
1209 /// use std::io;
1210 /// let mut app = App::new("myprog");
1211 /// let mut out = io::stdout();
1212 /// app.write_help(&mut out).expect("failed to write to stdout");
1213 /// ```
1214 /// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
1215 /// [`-h` (short)]: ./struct.Arg.html#method.help
1216 /// [`--help` (long)]: ./struct.Arg.html#method.long_help
1217 pub fn write_help<W: Write>(&self, w: &mut W) -> ClapResult<()> {
1218 // PENDING ISSUE: 808
1219 // https://github.com/clap-rs/clap/issues/808
1220 // If there are global arguments, or settings we need to propagate them down to subcommands
1221 // before parsing incase we run into a subcommand
1222 // self.p.propagate_globals();
1223 // self.p.propagate_settings();
1224 // self.p.derive_display_order();
1225 // self.p.create_help_and_version();
1226
1227 Help::write_app_help(w, self, false)
1228 }
1229
1230 /// Writes the full help message to the user to a [`io::Write`] object in the same method as if
1231 /// the user ran `--help`
1232 ///
1233 /// **NOTE:** clap has the ability to distinguish between "short" and "long" help messages
1234 /// depending on if the user ran [`-h` (short)] or [`--help` (long)]
1235 ///
1236 /// # Examples
1237 ///
1238 /// ```rust
1239 /// # use clap::App;
1240 /// use std::io;
1241 /// let mut app = App::new("myprog");
1242 /// let mut out = io::stdout();
1243 /// app.write_long_help(&mut out).expect("failed to write to stdout");
1244 /// ```
1245 /// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
1246 /// [`-h` (short)]: ./struct.Arg.html#method.help
1247 /// [`--help` (long)]: ./struct.Arg.html#method.long_help
1248 pub fn write_long_help<W: Write>(&mut self, w: &mut W) -> ClapResult<()> {
1249 // If there are global arguments, or settings we need to propagate them down to subcommands
1250 // before parsing incase we run into a subcommand
1251 self.p.propagate_globals();
1252 self.p.propagate_settings();
1253 self.p.derive_display_order();
1254 self.p.create_help_and_version();
1255
1256 Help::write_app_help(w, self, true)
1257 }
1258
1259 /// Writes the version message to the user to a [`io::Write`] object as if the user ran `-V`.
1260 ///
1261 /// **NOTE:** clap has the ability to distinguish between "short" and "long" version messages
1262 /// depending on if the user ran [`-V` (short)] or [`--version` (long)]
1263 ///
1264 /// # Examples
1265 ///
1266 /// ```rust
1267 /// # use clap::App;
1268 /// use std::io;
1269 /// let mut app = App::new("myprog");
1270 /// let mut out = io::stdout();
1271 /// app.write_version(&mut out).expect("failed to write to stdout");
1272 /// ```
1273 /// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
1274 /// [`-V` (short)]: ./struct.App.html#method.version
1275 /// [`--version` (long)]: ./struct.App.html#method.long_version
1276 pub fn write_version<W: Write>(&self, w: &mut W) -> ClapResult<()> {
1277 self.p.write_version(w, false).map_err(From::from)
1278 }
1279
1280 /// Writes the version message to the user to a [`io::Write`] object
1281 ///
1282 /// **NOTE:** clap has the ability to distinguish between "short" and "long" version messages
1283 /// depending on if the user ran [`-V` (short)] or [`--version` (long)]
1284 ///
1285 /// # Examples
1286 ///
1287 /// ```rust
1288 /// # use clap::App;
1289 /// use std::io;
1290 /// let mut app = App::new("myprog");
1291 /// let mut out = io::stdout();
1292 /// app.write_long_version(&mut out).expect("failed to write to stdout");
1293 /// ```
1294 /// [`io::Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
1295 /// [`-V` (short)]: ./struct.App.html#method.version
1296 /// [`--version` (long)]: ./struct.App.html#method.long_version
1297 pub fn write_long_version<W: Write>(&self, w: &mut W) -> ClapResult<()> {
1298 self.p.write_version(w, true).map_err(From::from)
1299 }
1300
1301 /// Generate a completions file for a specified shell at compile time.
1302 ///
1303 /// **NOTE:** to generate the file at compile time you must use a `build.rs` "Build Script"
1304 ///
1305 /// # Examples
1306 ///
1307 /// The following example generates a bash completion script via a `build.rs` script. In this
1308 /// simple example, we'll demo a very small application with only a single subcommand and two
1309 /// args. Real applications could be many multiple levels deep in subcommands, and have tens or
1310 /// potentially hundreds of arguments.
1311 ///
1312 /// First, it helps if we separate out our `App` definition into a separate file. Whether you
1313 /// do this as a function, or bare App definition is a matter of personal preference.
1314 ///
1315 /// ```
1316 /// // src/cli.rs
1317 ///
1318 /// use clap::{App, Arg, SubCommand};
1319 ///
1320 /// pub fn build_cli() -> App<'static, 'static> {
1321 /// App::new("compl")
1322 /// .about("Tests completions")
1323 /// .arg(Arg::with_name("file")
1324 /// .help("some input file"))
1325 /// .subcommand(SubCommand::with_name("test")
1326 /// .about("tests things")
1327 /// .arg(Arg::with_name("case")
1328 /// .long("case")
1329 /// .takes_value(true)
1330 /// .help("the case to test")))
1331 /// }
1332 /// ```
1333 ///
1334 /// In our regular code, we can simply call this `build_cli()` function, then call
1335 /// `get_matches()`, or any of the other normal methods directly after. For example:
1336 ///
1337 /// ```ignore
1338 /// // src/main.rs
1339 ///
1340 /// mod cli;
1341 ///
1342 /// fn main() {
1343 /// let m = cli::build_cli().get_matches();
1344 ///
1345 /// // normal logic continues...
1346 /// }
1347 /// ```
1348 ///
1349 /// Next, we set up our `Cargo.toml` to use a `build.rs` build script.
1350 ///
1351 /// ```toml
1352 /// # Cargo.toml
1353 /// build = "build.rs"
1354 ///
1355 /// [build-dependencies]
1356 /// clap = "2.23"
1357 /// ```
1358 ///
1359 /// Next, we place a `build.rs` in our project root.
1360 ///
1361 /// ```ignore
1362 /// extern crate clap;
1363 ///
1364 /// use clap::Shell;
1365 ///
1366 /// include!("src/cli.rs");
1367 ///
1368 /// fn main() {
1369 /// let outdir = match env::var_os("OUT_DIR") {
1370 /// None => return,
1371 /// Some(outdir) => outdir,
1372 /// };
1373 /// let mut app = build_cli();
1374 /// app.gen_completions("myapp", // We need to specify the bin name manually
1375 /// Shell::Bash, // Then say which shell to build completions for
1376 /// outdir); // Then say where write the completions to
1377 /// }
1378 /// ```
1379 /// Now, once we compile there will be a `{bin_name}.bash` file in the directory.
1380 /// Assuming we compiled with debug mode, it would be somewhere similar to
1381 /// `<project>/target/debug/build/myapp-<hash>/out/myapp.bash`.
1382 ///
1383 /// Fish shell completions will use the file format `{bin_name}.fish`
1384 pub fn gen_completions<T: Into<OsString>, S: Into<String>>(
1385 &mut self,
1386 bin_name: S,
1387 for_shell: Shell,
1388 out_dir: T,
1389 ) {
1390 self.p.meta.bin_name = Some(bin_name.into());
1391 self.p.gen_completions(for_shell, out_dir.into());
1392 }
1393
1394
1395 /// Generate a completions file for a specified shell at runtime. Until `cargo install` can
1396 /// install extra files like a completion script, this may be used e.g. in a command that
1397 /// outputs the contents of the completion script, to be redirected into a file by the user.
1398 ///
1399 /// # Examples
1400 ///
1401 /// Assuming a separate `cli.rs` like the [example above](./struct.App.html#method.gen_completions),
1402 /// we can let users generate a completion script using a command:
1403 ///
1404 /// ```ignore
1405 /// // src/main.rs
1406 ///
1407 /// mod cli;
1408 /// use std::io;
1409 ///
1410 /// fn main() {
1411 /// let matches = cli::build_cli().get_matches();
1412 ///
1413 /// if matches.is_present("generate-bash-completions") {
1414 /// cli::build_cli().gen_completions_to("myapp", Shell::Bash, &mut io::stdout());
1415 /// }
1416 ///
1417 /// // normal logic continues...
1418 /// }
1419 ///
1420 /// ```
1421 ///
1422 /// Usage:
1423 ///
1424 /// ```shell
1425 /// $ myapp generate-bash-completions > /usr/share/bash-completion/completions/myapp.bash
1426 /// ```
1427 pub fn gen_completions_to<W: Write, S: Into<String>>(
1428 &mut self,
1429 bin_name: S,
1430 for_shell: Shell,
1431 buf: &mut W,
1432 ) {
1433 self.p.meta.bin_name = Some(bin_name.into());
1434 self.p.gen_completions_to(for_shell, buf);
1435 }
1436
1437 /// Starts the parsing process, upon a failed parse an error will be displayed to the user and
1438 /// the process will exit with the appropriate error code. By default this method gets all user
1439 /// provided arguments from [`env::args_os`] in order to allow for invalid UTF-8 code points,
1440 /// which are legal on many platforms.
1441 ///
1442 /// # Examples
1443 ///
1444 /// ```no_run
1445 /// # use clap::{App, Arg};
1446 /// let matches = App::new("myprog")
1447 /// // Args and options go here...
1448 /// .get_matches();
1449 /// ```
1450 /// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html
1451 pub fn get_matches(self) -> ArgMatches<'a> { self.get_matches_from(&mut env::args_os()) }
1452
1453 /// Starts the parsing process. This method will return a [`clap::Result`] type instead of exiting
1454 /// the process on failed parse. By default this method gets matches from [`env::args_os`]
1455 ///
1456 /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
1457 /// used. It will return a [`clap::Error`], where the [`kind`] is a
1458 /// [`ErrorKind::HelpDisplayed`] or [`ErrorKind::VersionDisplayed`] respectively. You must call
1459 /// [`Error::exit`] or perform a [`std::process::exit`].
1460 ///
1461 /// # Examples
1462 ///
1463 /// ```no_run
1464 /// # use clap::{App, Arg};
1465 /// let matches = App::new("myprog")
1466 /// // Args and options go here...
1467 /// .get_matches_safe()
1468 /// .unwrap_or_else( |e| e.exit() );
1469 /// ```
1470 /// [`env::args_os`]: https://doc.rust-lang.org/std/env/fn.args_os.html
1471 /// [`ErrorKind::HelpDisplayed`]: ./enum.ErrorKind.html#variant.HelpDisplayed
1472 /// [`ErrorKind::VersionDisplayed`]: ./enum.ErrorKind.html#variant.VersionDisplayed
1473 /// [`Error::exit`]: ./struct.Error.html#method.exit
1474 /// [`std::process::exit`]: https://doc.rust-lang.org/std/process/fn.exit.html
1475 /// [`clap::Result`]: ./type.Result.html
1476 /// [`clap::Error`]: ./struct.Error.html
1477 /// [`kind`]: ./struct.Error.html
1478 pub fn get_matches_safe(self) -> ClapResult<ArgMatches<'a>> {
1479 // Start the parsing
1480 self.get_matches_from_safe(&mut env::args_os())
1481 }
1482
1483 /// Starts the parsing process. Like [`App::get_matches`] this method does not return a [`clap::Result`]
1484 /// and will automatically exit with an error message. This method, however, lets you specify
1485 /// what iterator to use when performing matches, such as a [`Vec`] of your making.
1486 ///
1487 /// **NOTE:** The first argument will be parsed as the binary name unless
1488 /// [`AppSettings::NoBinaryName`] is used
1489 ///
1490 /// # Examples
1491 ///
1492 /// ```no_run
1493 /// # use clap::{App, Arg};
1494 /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
1495 ///
1496 /// let matches = App::new("myprog")
1497 /// // Args and options go here...
1498 /// .get_matches_from(arg_vec);
1499 /// ```
1500 /// [`App::get_matches`]: ./struct.App.html#method.get_matches
1501 /// [`clap::Result`]: ./type.Result.html
1502 /// [`Vec`]: https://doc.rust-lang.org/std/vec/struct.Vec.html
1503 /// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
1504 pub fn get_matches_from<I, T>(mut self, itr: I) -> ArgMatches<'a>
1505 where
1506 I: IntoIterator<Item = T>,
1507 T: Into<OsString> + Clone,
1508 {
1509 self.get_matches_from_safe_borrow(itr).unwrap_or_else(|e| {
1510 // Otherwise, write to stderr and exit
1511 if e.use_stderr() {
1512 wlnerr!("{}", e.message);
1513 if self.p.is_set(AppSettings::WaitOnError) {
1514 wlnerr!("\nPress [ENTER] / [RETURN] to continue...");
1515 let mut s = String::new();
1516 let i = io::stdin();
1517 i.lock().read_line(&mut s).unwrap();
1518 }
1519 drop(self);
1520 drop(e);
1521 process::exit(1);
1522 }
1523
1524 drop(self);
1525 e.exit()
1526 })
1527 }
1528
1529 /// Starts the parsing process. A combination of [`App::get_matches_from`], and
1530 /// [`App::get_matches_safe`]
1531 ///
1532 /// **NOTE:** This method WILL NOT exit when `--help` or `--version` (or short versions) are
1533 /// used. It will return a [`clap::Error`], where the [`kind`] is a [`ErrorKind::HelpDisplayed`]
1534 /// or [`ErrorKind::VersionDisplayed`] respectively. You must call [`Error::exit`] or
1535 /// perform a [`std::process::exit`] yourself.
1536 ///
1537 /// **NOTE:** The first argument will be parsed as the binary name unless
1538 /// [`AppSettings::NoBinaryName`] is used
1539 ///
1540 /// # Examples
1541 ///
1542 /// ```no_run
1543 /// # use clap::{App, Arg};
1544 /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
1545 ///
1546 /// let matches = App::new("myprog")
1547 /// // Args and options go here...
1548 /// .get_matches_from_safe(arg_vec)
1549 /// .unwrap_or_else( |e| { panic!("An error occurs: {}", e) });
1550 /// ```
1551 /// [`App::get_matches_from`]: ./struct.App.html#method.get_matches_from
1552 /// [`App::get_matches_safe`]: ./struct.App.html#method.get_matches_safe
1553 /// [`ErrorKind::HelpDisplayed`]: ./enum.ErrorKind.html#variant.HelpDisplayed
1554 /// [`ErrorKind::VersionDisplayed`]: ./enum.ErrorKind.html#variant.VersionDisplayed
1555 /// [`Error::exit`]: ./struct.Error.html#method.exit
1556 /// [`std::process::exit`]: https://doc.rust-lang.org/std/process/fn.exit.html
1557 /// [`clap::Error`]: ./struct.Error.html
1558 /// [`Error::exit`]: ./struct.Error.html#method.exit
1559 /// [`kind`]: ./struct.Error.html
1560 /// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
1561 pub fn get_matches_from_safe<I, T>(mut self, itr: I) -> ClapResult<ArgMatches<'a>>
1562 where
1563 I: IntoIterator<Item = T>,
1564 T: Into<OsString> + Clone,
1565 {
1566 self.get_matches_from_safe_borrow(itr)
1567 }
1568
1569 /// Starts the parsing process without consuming the [`App`] struct `self`. This is normally not
1570 /// the desired functionality, instead prefer [`App::get_matches_from_safe`] which *does*
1571 /// consume `self`.
1572 ///
1573 /// **NOTE:** The first argument will be parsed as the binary name unless
1574 /// [`AppSettings::NoBinaryName`] is used
1575 ///
1576 /// # Examples
1577 ///
1578 /// ```no_run
1579 /// # use clap::{App, Arg};
1580 /// let arg_vec = vec!["my_prog", "some", "args", "to", "parse"];
1581 ///
1582 /// let mut app = App::new("myprog");
1583 /// // Args and options go here...
1584 /// let matches = app.get_matches_from_safe_borrow(arg_vec)
1585 /// .unwrap_or_else( |e| { panic!("An error occurs: {}", e) });
1586 /// ```
1587 /// [`App`]: ./struct.App.html
1588 /// [`App::get_matches_from_safe`]: ./struct.App.html#method.get_matches_from_safe
1589 /// [`AppSettings::NoBinaryName`]: ./enum.AppSettings.html#variant.NoBinaryName
1590 pub fn get_matches_from_safe_borrow<I, T>(&mut self, itr: I) -> ClapResult<ArgMatches<'a>>
1591 where
1592 I: IntoIterator<Item = T>,
1593 T: Into<OsString> + Clone,
1594 {
1595 // If there are global arguments, or settings we need to propagate them down to subcommands
1596 // before parsing incase we run into a subcommand
1597 if !self.p.is_set(AppSettings::Propagated) {
1598 self.p.propagate_globals();
1599 self.p.propagate_settings();
1600 self.p.derive_display_order();
1601 self.p.set(AppSettings::Propagated);
1602 }
1603
1604 let mut matcher = ArgMatcher::new();
1605
1606 let mut it = itr.into_iter();
1607 // Get the name of the program (argument 1 of env::args()) and determine the
1608 // actual file
1609 // that was used to execute the program. This is because a program called
1610 // ./target/release/my_prog -a
1611 // will have two arguments, './target/release/my_prog', '-a' but we don't want
1612 // to display
1613 // the full path when displaying help messages and such
1614 if !self.p.is_set(AppSettings::NoBinaryName) {
1615 if let Some(name) = it.next() {
1616 let bn_os = name.into();
1617 let p = Path::new(&*bn_os);
1618 if let Some(f) = p.file_name() {
1619 if let Some(s) = f.to_os_string().to_str() {
1620 if self.p.meta.bin_name.is_none() {
1621 self.p.meta.bin_name = Some(s.to_owned());
1622 }
1623 }
1624 }
1625 }
1626 }
1627
1628 // do the real parsing
1629 if let Err(e) = self.p.get_matches_with(&mut matcher, &mut it.peekable()) {
1630 return Err(e);
1631 }
1632
1633 let global_arg_vec: Vec<&str> = (&self).p.global_args.iter().map(|ga| ga.b.name).collect();
1634 matcher.propagate_globals(&global_arg_vec);
1635
1636 Ok(matcher.into())
1637 }
1638}
1639
1640#[cfg(feature = "yaml")]
1641impl<'a> From<&'a Yaml> for App<'a, 'a> {
1642 fn from(mut yaml: &'a Yaml) -> Self {
1643 use args::SubCommand;
1644 // We WANT this to panic on error...so expect() is good.
1645 let mut is_sc = None;
1646 let mut a = if let Some(name) = yaml["name"].as_str() {
1647 App::new(name)
1648 } else {
1649 let yaml_hash = yaml.as_hash().unwrap();
1650 let sc_key = yaml_hash.keys().nth(0).unwrap();
1651 is_sc = Some(yaml_hash.get(sc_key).unwrap());
1652 App::new(sc_key.as_str().unwrap())
1653 };
1654 yaml = if let Some(sc) = is_sc { sc } else { yaml };
1655
1656 macro_rules! yaml_str {
1657 ($a:ident, $y:ident, $i:ident) => {
1658 if let Some(v) = $y[stringify!($i)].as_str() {
1659 $a = $a.$i(v);
1660 } else if $y[stringify!($i)] != Yaml::BadValue {
1661 panic!("Failed to convert YAML value {:?} to a string", $y[stringify!($i)]);
1662 }
1663 };
1664 }
1665
1666 yaml_str!(a, yaml, version);
1667 yaml_str!(a, yaml, long_version);
1668 yaml_str!(a, yaml, author);
1669 yaml_str!(a, yaml, bin_name);
1670 yaml_str!(a, yaml, about);
1671 yaml_str!(a, yaml, long_about);
1672 yaml_str!(a, yaml, before_help);
1673 yaml_str!(a, yaml, after_help);
1674 yaml_str!(a, yaml, template);
1675 yaml_str!(a, yaml, usage);
1676 yaml_str!(a, yaml, help);
1677 yaml_str!(a, yaml, help_short);
1678 yaml_str!(a, yaml, version_short);
1679 yaml_str!(a, yaml, help_message);
1680 yaml_str!(a, yaml, version_message);
1681 yaml_str!(a, yaml, alias);
1682 yaml_str!(a, yaml, visible_alias);
1683
1684 if let Some(v) = yaml["display_order"].as_i64() {
1685 a = a.display_order(v as usize);
1686 } else if yaml["display_order"] != Yaml::BadValue {
1687 panic!(
1688 "Failed to convert YAML value {:?} to a u64",
1689 yaml["display_order"]
1690 );
1691 }
1692 if let Some(v) = yaml["setting"].as_str() {
1693 a = a.setting(v.parse().expect("unknown AppSetting found in YAML file"));
1694 } else if yaml["setting"] != Yaml::BadValue {
1695 panic!(
1696 "Failed to convert YAML value {:?} to an AppSetting",
1697 yaml["setting"]
1698 );
1699 }
1700 if let Some(v) = yaml["settings"].as_vec() {
1701 for ys in v {
1702 if let Some(s) = ys.as_str() {
1703 a = a.setting(s.parse().expect("unknown AppSetting found in YAML file"));
1704 }
1705 }
1706 } else if let Some(v) = yaml["settings"].as_str() {
1707 a = a.setting(v.parse().expect("unknown AppSetting found in YAML file"));
1708 } else if yaml["settings"] != Yaml::BadValue {
1709 panic!(
1710 "Failed to convert YAML value {:?} to a string",
1711 yaml["settings"]
1712 );
1713 }
1714 if let Some(v) = yaml["global_setting"].as_str() {
1715 a = a.setting(v.parse().expect("unknown AppSetting found in YAML file"));
1716 } else if yaml["global_setting"] != Yaml::BadValue {
1717 panic!(
1718 "Failed to convert YAML value {:?} to an AppSetting",
1719 yaml["setting"]
1720 );
1721 }
1722 if let Some(v) = yaml["global_settings"].as_vec() {
1723 for ys in v {
1724 if let Some(s) = ys.as_str() {
1725 a = a.global_setting(s.parse().expect("unknown AppSetting found in YAML file"));
1726 }
1727 }
1728 } else if let Some(v) = yaml["global_settings"].as_str() {
1729 a = a.global_setting(v.parse().expect("unknown AppSetting found in YAML file"));
1730 } else if yaml["global_settings"] != Yaml::BadValue {
1731 panic!(
1732 "Failed to convert YAML value {:?} to a string",
1733 yaml["global_settings"]
1734 );
1735 }
1736
1737 macro_rules! vec_or_str {
1738 ($a:ident, $y:ident, $as_vec:ident, $as_single:ident) => {{
1739 let maybe_vec = $y[stringify!($as_vec)].as_vec();
1740 if let Some(vec) = maybe_vec {
1741 for ys in vec {
1742 if let Some(s) = ys.as_str() {
1743 $a = $a.$as_single(s);
1744 } else {
1745 panic!("Failed to convert YAML value {:?} to a string", ys);
1746 }
1747 }
1748 } else {
1749 if let Some(s) = $y[stringify!($as_vec)].as_str() {
1750 $a = $a.$as_single(s);
1751 } else if $y[stringify!($as_vec)] != Yaml::BadValue {
1752 panic!("Failed to convert YAML value {:?} to either a vec or string", $y[stringify!($as_vec)]);
1753 }
1754 }
1755 $a
1756 }
1757 };
1758 }
1759
1760 a = vec_or_str!(a, yaml, aliases, alias);
1761 a = vec_or_str!(a, yaml, visible_aliases, visible_alias);
1762
1763 if let Some(v) = yaml["args"].as_vec() {
1764 for arg_yaml in v {
1765 a = a.arg(Arg::from_yaml(arg_yaml.as_hash().unwrap()));
1766 }
1767 }
1768 if let Some(v) = yaml["subcommands"].as_vec() {
1769 for sc_yaml in v {
1770 a = a.subcommand(SubCommand::from_yaml(sc_yaml));
1771 }
1772 }
1773 if let Some(v) = yaml["groups"].as_vec() {
1774 for ag_yaml in v {
1775 a = a.group(ArgGroup::from(ag_yaml.as_hash().unwrap()));
1776 }
1777 }
1778
1779 a
1780 }
1781}
1782
1783impl<'a, 'b> Clone for App<'a, 'b> {
1784 fn clone(&self) -> Self { App { p: self.p.clone() } }
1785}
1786
1787impl<'n, 'e> AnyArg<'n, 'e> for App<'n, 'e> {
1788 fn name(&self) -> &'n str {
1789 ""
1790 }
1791 fn overrides(&self) -> Option<&[&'e str]> { None }
1792 fn requires(&self) -> Option<&[(Option<&'e str>, &'n str)]> { None }
1793 fn blacklist(&self) -> Option<&[&'e str]> { None }
1794 fn required_unless(&self) -> Option<&[&'e str]> { None }
1795 fn val_names(&self) -> Option<&VecMap<&'e str>> { None }
1796 fn is_set(&self, _: ArgSettings) -> bool { false }
1797 fn val_terminator(&self) -> Option<&'e str> { None }
1798 fn set(&mut self, _: ArgSettings) {
1799 unreachable!("App struct does not support AnyArg::set, this is a bug!")
1800 }
1801 fn has_switch(&self) -> bool { false }
1802 fn max_vals(&self) -> Option<u64> { None }
1803 fn num_vals(&self) -> Option<u64> { None }
1804 fn possible_vals(&self) -> Option<&[&'e str]> { None }
1805 fn validator(&self) -> Option<&Rc<Fn(String) -> StdResult<(), String>>> { None }
1806 fn validator_os(&self) -> Option<&Rc<Fn(&OsStr) -> StdResult<(), OsString>>> { None }
1807 fn min_vals(&self) -> Option<u64> { None }
1808 fn short(&self) -> Option<char> { None }
1809 fn long(&self) -> Option<&'e str> { None }
1810 fn val_delim(&self) -> Option<char> { None }
1811 fn takes_value(&self) -> bool { true }
1812 fn help(&self) -> Option<&'e str> { self.p.meta.about }
1813 fn long_help(&self) -> Option<&'e str> { self.p.meta.long_about }
1814 fn default_val(&self) -> Option<&'e OsStr> { None }
1815 fn default_vals_ifs(&self) -> Option<map::Values<(&'n str, Option<&'e OsStr>, &'e OsStr)>> {
1816 None
1817 }
1818 fn env<'s>(&'s self) -> Option<(&'n OsStr, Option<&'s OsString>)> { None }
1819 fn longest_filter(&self) -> bool { true }
1820 fn aliases(&self) -> Option<Vec<&'e str>> {
1821 if let Some(ref aliases) = self.p.meta.aliases {
1822 let vis_aliases: Vec<_> = aliases
1823 .iter()
1824 .filter_map(|&(n, v)| if v { Some(n) } else { None })
1825 .collect();
1826 if vis_aliases.is_empty() {
1827 None
1828 } else {
1829 Some(vis_aliases)
1830 }
1831 } else {
1832 None
1833 }
1834 }
1835}
1836
1837impl<'n, 'e> fmt::Display for App<'n, 'e> {
1838 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "{}", self.p.meta.name) }
1839}