A full featured, fast Command Line Argument Parser for Rust
APACHE-2.0 License
Bot releases are hidden (Show)
Note: clap v3 has been in development for several years and has changed
hands multiple times. Unfortunately, our changelog might be incomplete,
whether in changes or their motivation.
A special thanks to the maintainers, contributors, beta users, and sponsors who
have helped along this journey, especially kbknapp.
StructOpt Integration
StructOpt provides a serde-like declarative
approach to defining your parser. The main benefits we've seen so far from integrating are:
StructOpt
traits so crates built on clap3 can beCustom Help Headings
Previously, clap automatically grouped arguments in the help as either
ARGS
, FLAGS
, OPTIONS
, and SUBCOMMANDS
.
You can now override the default group with Arg::help_heading
and
App::subcommand_help_heading
. To apply a heading to a series of arguments,
you can set App::help_heading
.
Deprecations
While a lot of deprecations have been added to clean up the API (overloaded
meaning of Arg::multiple
) or make things more consistent, some particular
highlights are:
clap_app!
has been deprecated in favor of the builder API with arg!
(clap-rs/clap#2835)Arg::from_usage
has been deprecated in favor of arg!
(clap-rs/clap#3087)
From clap v2
-h
and --help
output at a minimum (recommendation: trycmd for snapshot testing)no-default-features
: add the std
featureApp
creation to a function and add a test similar to the one below, resolving any of its assertionsArgMatches
asserts regarding AllowInvalidUtf8
.Example test:
fn app() -> clap::App<'static> {
...
}
#[test]
fn verify_app() {
app().debug_assert();
}
From structopt 0.3.25
-h
and --help
output at a minimum (recommendation: trycmd for snapshot testing)derive
feature flag
no-default-features
: add the std
featureuse
statements from structopt
and structopt::clap
to clap
Example test:
#[derive(clap::StructOpt)]
struct Args {
...
}
#[test]
fn verify_app() {
use clap::IntoApp;
Args::into_app().debug_assert()
}
From clap v3.0.0-beta.5
-h
and --help
output at a minimum (recommendation: trycmd for snapshot testing)derive
, env
, cargo
, or unicode
feature flags as neededyaml
, clap_app!
, or usage parser: revert any changes you made for clap3Arg::about
Arg::long_about
back to help
and long_help
and change PossibleValue::about
to help
(clap-rs/clap#3075)AppSettings::HelpRequired
to AppSettings::HelpExpected
PossibleValue::hidden
to PossibleValue::hide
App::subcommand_placeholder
to App::subcommand_value_name
/ App::subcommand_help_heading
derive
: see the structopt breaking changes section for Vec
changesArgMatches
asserts regarding AllowInvalidUtf8
.From clap 2
Subtle changes (i.e. compiler won't catch):
AppSettings::UnifiedHelpMessage
is now default behaviour
{flags}
and {unified}
will assert if present in App::help_template
AppSettings::EnableColoredHelp
is now the default behavior but can beAppSettings::DisableColoredHelp
App::override_usage
no longer implies a leading \t
, allowing multi lined usagesArg::require_equals
no longer implies ArgSettings::ForbidEmptyValues
(#2233)Arg::require_delimiter
no longer implies ArgSettings::TakesValue
and ArgSettings::UseValueDelimiter
(#2233)Arg::env
, Arg::env_os
, Arg::last
, Arg::require_equals
, Arg::allow_hyphen_values
,Arg::hide_possible_values
, Arg::hide_default_value
, Arg::hide_env_values
,Arg::case_insensitive
and Arg::multiple_values
no longer imply ArgSettings::TakesValue
(#2233)ArgMatches::is_present
no longer checks subcommand names...
s meaning in usage parser. Before, it always meant multiple
which is still true for --option [val]...
. Now [name]... --option [val]
results in ArgSettings::MultipleOccurrences
.Easier to catch changes:
no-default-features
, you now have to specify the std
feature (reserved for future work)env
feature flag
Arg::env
, Arg::env_os
, Arg::hide_env_values
, ArgSettings::HideEnvValues
cargo
feature flag
crate_name!
, crate_version!
, crate_authors!
, crate_description!
, app_from_crate!
AppSettings::StrictUtf8
is now default behaviour and asserts ifAppSettings::AllowInvalidUtf8ForExternalSubcommands
andArgSettings::AllowInvalidUtf8
and ArgMatches::value_of_os
aren't usedAppSettings::AllowInvalidUtf8
has been removedArg::short
and Arg::value_delimiter
now take a char
instead of a &str
ArgMatches
panics on unknown argumentsVersionlessSubcommands
, making it the default (see clap-rs/clap#2812)ArgSettings::EmptyValues
in favor of ArgSettings::ForbidEmptyValues
Arg::validator
now takes first argument as Fn(&str) -> Result<O, E: ToString>
instead ofFn(String) -> Result<(), String>
Arg::validator_os
now takes first argument as Fn(&OsStr) -> Result<O, OsString>
instead ofFn(&OsStr) -> Result<(), OsString>
Arg::value_name
now sets, rather than appends (see clap-rs/clap#2634)yaml-rust
from 0.3 to 0.4ArgGroup::from(BTreeMap)
to ArgGroup::from(yaml)
ArgMatches::usage
with App::generate_usage
Arg::settings
with Arg::setting(Setting1 | Setting2)
App
and Arg
now need only one lifetimeApp::with_defaults
, replaced with app_from_crate
AppSettings::PropagateGlobalValuesDown
(now the default)App
functions, like App::write_help
now take &mut self
instead of &self
Error::message
is now private, use Error::to_string
Arg::default_value_if
, Arg::default_value_if_os
, Arg::default_value_ifs
,Arg::default_value_ifs_os
now takes the default value parameter as an option (clap-rs/clap#1406)App::print_help
& App::print_long_help
to now return std::io::Result
App::write_help
& App::write_long_help
to now return std::io::Result
Arg::index
, Arg::number_of_values
, Arg::min_values
, Arg::max_values
to taking usize
instead of u64Error::info
to type Vec<String>
instead of Option<Vec<String>>
ArgMatches::subcommand
to now return Option<(&str, &ArgMatches)>
ErrorKind::MissingArgumentOrSubcommand
to ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
ErrorKind::HelpDisplayed
to ErrorKind::DisplayHelp
ErrorKind::VersionDisplayed
to ErrorKind::DisplayVersion
#[non_exhaustive]
to clap::{ValueHint, ErrorKind, AppSettings, ArgSettings}
(clap-rs/clap#3167)From structopt 0.3.25
App
isn't initialized with crate information anymore. Now opt-in via #[clap(author)]
, #[clap(about)]
, #[clap(version)]
(clap-rs/clap#3034)#[clap(default_value)]
is replaced with #[clap(default_value_t)]
(clap-rs/clap#1694)#[clap(subcommand)]
attribute (clap-rs/clap#2587)Vec<_>
and Option<Vec<_>>
have changed from multiple
to multiple_occurrences
On top of the clap 2 changes
From clap 2
unicode
feature flag for faster builds and smaller binaries for ASCII-only CLIs.env
feature flag for faster builds and smaller binaries.From clap 2
Integration of structopt::StructOpt
via clap::Parser
(requires derive
feature flag)
Custom help headings
App::help_heading
(apply to all future args)Arg::help_heading
(apply to current arg)App::subcommand_help_heading
along with App::subcommand_value_name
(apply to subcommands)AppSettings::UnifiedHelpMessage
is now default behaviour (clap-rs/clap#2807)Deriving of ArgEnum
for generating Arg::possible_values
(requires derive
feature flag)
Disable built-in help/version behavior with AppSettings::NoAutoHelp
and AppSettings::NoAutoVersion
Change an existing arg with new builder method mut_arg
(particularly helpful for --help
and --version
)
Provide extra context in long help messages (--help
) with before_long_help
and after_long_help
(clap-rs/clap#1903)
Detect missing help descriptions via debug asserts by enabling AppSettings::HelpExpected
Aliases for short flags (clap-rs/clap#1896)
Validate UTF-8 values, rather than panicing during ArgMatches::value_of
thanks to AppSettings::AllowInvalidUtf8ForExternalSubcommands
and ArgSettings::AllowInvalidUtf8
ArgMatches
calls do not match the UTF-8 setting.clap::PossibleValue
to allow
Allow arguments to conflict with all others via Arg::exclusive
(clap-rs/clap#1583)
Validate arguments with a regex (required regex
feature flag)
Arg::default_missing_value
for cases like --color[=<WHEN>]
(clap-rs/clap#1587)
clap::App::color
/ clap::ColorChoice
to specify color setting for the app
Custom error reporting with App::error
App::debug_assert
test helper
Replace Arg::multiple(bool)
with Arg::multiple_values
/ Arg::multiple_occurrences
Added support for flag subcommands like pacman (clap-rs/clap#1361)
Partial parsing via AppSettings::IgnoreErrors
(clap-rs/clap#1880)
Enable cmd help
to print long help (--help
instead of -h
) with AppSettings::UseLongFormatForHelpSubcommand
(clap-rs/clap#2435)
Allow long arg abbreviations like we do with subcommands via AppSettings::InferLongArgs
(clap-rs/clap#2435)
Detect subcommands among positional arguments with AppSettings::SubcommandPrecedenceOverArg
Give completion scripts hints with Arg::value_hint
(clap-rs/clap#1793)
Allow unsetting defaults with
Arg::default_value_if
, Arg::default_value_if_os
, Arg::default_value_ifs
,
Arg::default_value_ifs_os
(clap-rs/clap#1406)
Interpret some env variable values as false
for flags, in addition to "not-present" (clap-rs/clap#2539)
n
, no
, f
, false
, off
, 0
Added arg!
macro for creating an Arg
from a compile-time usage parser
(Experimental) Busybox-like multi-call support
AppSettings::Multicall
behind unstable-multicall
feature flag(Experimental) Alias an argument to anything group of arguments
App::replace
behind unstable-replace
feature flag(Experimental) Grouping of multiple values within multiple occurrences
ArgMatches::grouped_values_of
behind unstable-grouped
feature flagFrom structopt 0.3.25
default_value_t [= <expr>]
attribute (clap-rs/clap#1694)update
APIarg_enum
attribute for integrating with ArgEnum
traitOn top of the clap 2 changes
From clap 2
App::version
, App::long_version
are setwrap_help
feature is not enabledArg::multiple
with Arg::multiple_values
and Arg::multiple_occurrences
app_from_crate!
defaults to separating multiple authors with ", "
IgnoreCase
is now unicode aware (requires unicode
feature flag)ColorChoice::Never
, even if that means we skip colors in some casesArgMatches
panics on unknown argumentsauthors
field in Cargo.toml
with app_from_crate
--help
in cmd help
with DisableHelpFlag
(clap-rs/clap#3169)--help
in cmd help help
that doesn't work (clap-rs/clap#3169)From structopt 0.3.25
SubcommandsNegateReqs
by allowing required Option<_>
s (clap-rs/clap#2255)AllowInvalidUtf8
based on parser (clap-rs/clap#751)authors
field in Cargo.toml
default_value_os
but treat it like default_value
(clap-rs/clap#3031)flatten
and subcommand
, ensure our doc comment always overrides the nested container's doc comment, whether it has only about
or about
and long_about
(clap-rs/clap#3175)On top of the clap 2 changes
clap
requires rustc 1.54.0
or greater.Published by pksunkara about 4 years ago
crate_*
macros.Published by CreepySkeleton about 4 years ago
2.x
examples. Now they point to the right place.Published by kbknapp over 4 years ago
README.md
(c8e685d7)Arg
that allows implying all of Arg::last
Arg::allow_hyphen_values
and Arg::multiple(true)
(66a78f29)wrap_help
feature is a thing (fc7ab227)Published by kbknapp over 6 years ago
Arg::last
when instantiating from a YAML file (aab77c81a5, closes #1160)Arg::possible_values
was used (872f02ae)ansi_term
on Windows since its not used (b57ee946, closes #1155)[values: foo bar baz]
array to [possible values: foo bar baz]
for consistency with the API (414707e4e97, closes #1160)--
(73993fe, closes #1161)Published by kbknapp almost 7 years ago
Changes since 2.27.0 (most recent tag before this):
The minimum required Rust is now 1.20. This was done to start using bitflags 1.0 and having >1.0 deps is a very good thing!
bitflags
to 1.0term_size
as an optional dependency (with feature wrap_help
) to fix compile bug** This release raises the minimum required version of Rust to 1.18 **
** This release also contains a very minor breaking change to fix a bug **
The only CLIs affected will be those using unrestrained multiple values and subcommands where the
subcommand name can coincide with one of the multiple values.
See the commit 0c223f54 for full details.
who's
-> whose
(53c1ffe8)Minimum version of Rust is now v1.13.0 (Stable)
who's
-> whose
(53c1ffe8)default_value_os
(d5ef8955)App::long_about
App::long_version
App::print_long_help
App::write_long_help
App::print_long_version
App::write_long_version
Arg::long_help
--("some-arg")
method for using args with hyphens inside them (bc08ef3e, closes #919)require_equals(true)
now display the equals sign in help messages, usage strings, and errors" (c8eb0384, closes #903)Published by kbknapp over 7 years ago
arg_post_processing
on multiple values anymore (ec516182)VecMap
to Vec
for matched values of Arg
s (22bf137a)App::args
which is forced to clone (8da0303b)AppSettings::SubcommandsNegateReqs
and ArgsNegateSubcommands
are used, a new more accurate double line usage string is shown (50f02300, closes #871)--
syntax and can be accessed early (6a7aea90, closes #888)default_value_os
and default_value_if[s]_os
(0f2a3782, closes #849)App::help_message
and App::version_message
which allows one to override the auto-generated help/version flag associated help (389c413, closes #889)Published by kbknapp over 7 years ago
[ARGS]
in the usage string (c2978afc, closes #769)help
subcommand (a10fc859)$ prog [optional] <required>
style CLIs where the second postional argument is required, but the first is optional (1110fdc7, closes #636)Cargo.toml
description field to fill in the App::about
method at compile time (4d9a82db, closes #778)Cargo.toml
name field to fill in the App::new
method at compile time (4d9a82db, closes #778)crate_version!
, crate_name!
, crate_description!
, and crate_authors!
into a single macro call to build a default App
instance from the Cargo.toml
fields (4d9a82db, closes #778)no_cargo
feature to disable Cargo-env-var-dependent macros for those not using cargo
to build their crates (#786) (6fdd2f9d)Arg::allow_hyphen_values
to fail parsing (26c670ca)--("some-arg-name")
syntax for defining long arg names when using clap_app!
macro (f41ec962)("some app name")
syntax for defining app names when using clap_app!
macro (9895b671, closes #759)