Merge pull request #6137 from epage/docs

docs(concepts): Introduce a concept-focused document for clap

Author: epage

src/_concepts.rs

@@ -0,0 +1,94 @@
+//! ## 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
+//!
+//! ### 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(true)`]: a positional that can only come after `--`
+//! - [`Arg::trailing_var_arg(true)`]: all further arguments are captured as additional values
+//! - [`Arg::allow_hyphen_values(true)`] 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(true)`] 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
+
+#![allow(unused_imports)]
+use clap_builder::Arg;
+use clap_builder::ArgAction;
+use clap_builder::Command;

src/lib.rs

@@ -9,6 +9,7 @@
 //! - Derive [tutorial][_derive::_tutorial] and [reference][_derive]
 //! - Builder [tutorial][_tutorial] and [reference][Command]
 //! - [Cookbook][_cookbook]
+//! - [CLI Concepts][_concepts]
 //! - [FAQ][_faq]
 //! - [Discussions](https://github.com/clap-rs/clap/discussions)
 //! - [CHANGELOG](https://github.com/clap-rs/clap/blob/v4.5.47/CHANGELOG.md) (includes major version migration
@@ -91,6 +92,8 @@ pub use clap_builder::*;
 #[doc(hidden)]
 pub use clap_derive::{self, Args, Parser, Subcommand, ValueEnum};
 
+#[cfg(feature = "unstable-doc")]
+pub mod _concepts;
 #[cfg(feature = "unstable-doc")]
 pub mod _cookbook;
 #[cfg(feature = "unstable-doc")]