repo_description: A full featured, fast Command Line Argument Parser for Rust
repo_topics: argument-parser argument-parsing command-line command-line-parser parsed-arguments positional-arguments rust subcommands
code: //! ## CLI Concepts
  //!
  //! Note: this will be speaking towards the general case.
  //!
  //! ### Environmental context
  //!
  //! When you run a command line application, it is inside a terminal emulator, or terminal.
  //! This handles integration with the rest of your system including user input,
  //! rendering, etc.
  //!
  //! The terminal will run inside of itself an interactive shell.
  //! The shell is responsible for showing the prompt, receiving input including the command you are writing,
  //! letting that command take over until completion, and then repeating.
  //! This is called a read-eval-print loop, or REPL.
  //! Typically the shell will take the command you typed and split it into separate arguments,
  //! including handling of quoting, escaping, and globbing.
  //! The parsing and evaluation of the command is shell specific.
  //! The shell will then determine which application to run and then pass the full command-line as
  //! individual arguments to your program.
  //! These arguments are exposed in Rust as [`std::env::args_os`].
  //!
  //! Windows is an exception in Shell behavior in that the command is passed as an individual
  //! string, verbatim, and the application must split the arguments.
  //! [`std::env::args_os`] will handle the splitting for you but will not handle globs.
  //!
  //! Takeaways:
  //! - Your application will only see quotes that have been escaped within the shell
  //!   - e.g. to receive `message="hello world"`, you may need to type `'message="hello world"'` or `message=\"hello world\"`
  //! - If your applications needs to parse a string into arguments,
  //!   you will need to pick a syntax and do it yourself
  //!   - POSIX's shell syntax is a common choice and available in packages like [shlex](https://docs.rs/shlex)
  //!   - See also our [REPL cookbook entry][crate::_cookbook::repl]
  //! - On Windows, you will need to handle globbing yourself if desired
  //!   - [`wild`](https://docs.rs/wild) can help with that
  //!
  //! ### Argument Parsing
  //!
  //! The first argument of [`std::env::args_os`] is the [`Command::bin_name`]
  //! which is usually limited to affecting [`Command::render_usage`].
  //! [`Command::no_binary_name`] and [`Command::multicall`] exist for rare cases when this assumption is not valid.
  //!
  //! Command-lines are a context-sensitive grammar,
  //! meaning the interpretation of an argument is based on the arguments that came before.
  //! Arguments come in one of several flavors:
  //! - Values
  //! - Flags
  //! - Subcommands
  //!
  //! When examining the next argument,
  //! 1. If it starts with a `--`,
  //!    then that is a long Flag and all remaining text up to a `=` or the end is
  //!    matched to a [`Arg::long`], [`Command::long_flag`], or alias.
  //!    - Everything after the `=` is taken as a Value and parsing a new argument is examined.
  //!    - If no `=` is present, then Values will be taken according to [`Arg::num_args`]
  //!    - We generally call a Flag that takes a Value an Option
  //! 2. If it starts with a `-`,
  //!    then that is a sequence of short Flags where each character is matched against a [`Arg::short`], [`Command::short_flag`] or
  //!    alias until `=`, the end, or a short Flag takes Values (see [`Arg::num_args`])
  //! 3. If its a `--`, that is an escape and all future arguments are considered to be a Value, even if
  //!    they start with `--` or `-`
  //! 4. If it matches a [`Command::name`],
  //!    then the argument is a subcommand
  //! 5. If there is an [`Arg`] at the next [`Arg::index`],
  //!    then the argument is considered a Positional argument
  //!
  //! When a subcommand matches,
  //! all further arguments are parsed by that [`Command`].
  //!
  //! There are many settings that tweak this behavior, including:
  //! - [`Arg::last`]: a positional that can only come after `--`
  //! - [`Arg::trailing_var_arg`]: all further arguments are captured as additional Values
  //! - [`Arg::allow_hyphen_values`] and [`Arg::allow_negative_numbers`]: assumes arguments
  //!   starting with `-` are Values and not Flags.
  //! - [`Command::subcommand_precedence_over_arg`]: when an [`Arg::num_args`] takes Values,
  //!   stop if one matches a subCommand
  //! - [`Command::allow_missing_positional`]: in limited cases a [`Arg::index`] may be skipped
  //! - [`Command::allow_external_subcommands`]: treat any unknown argument as a subcommand, capturing
  //!   all remaining arguments.
  //!
  //! Takeaways
  //! - Values that start with a `-` either need to be escaped by the user with `--`
  //!   (if a positional),
  //!   or you need to set [`Arg::allow_hyphen_values`] or [`Arg::allow_negative_numbers`]
  //! - [`Arg::num_args`],
  //!   [`ArgAction::Append`] (on a positional),
  //!   [`Arg::trailing_var_arg`],
  //!   and [`Command::allow_external_subcommands`]
  //!   all affect the parser in similar but slightly different ways and which to use depends on your
  //!   application
  //!
  //! ### Value Parsing
  //!
  //! When reacting to a Flag (no Value),
  //! [`Arg::default_missing_values`] will be applied.
  //!
  //! The Value will be split by [`Arg::value_delimiter`].
  //!
  //! The Value will then be stored according to its [`ArgAction`].
  //! For most [`ArgAction`]s,
  //! the Value will be parsed according to [`ValueParser`]
  //! and stored in the [`ArgMatches`].
  
  #![allow(unused_imports)]
  use clap_builder::Arg;
  use clap_builder::ArgAction;
  use clap_builder::ArgMatches;
  use clap_builder::Command;
  use clap_builder::builder::ValueParser;
  