clap

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.

Highlights

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:

• Tighter feedback between the design of clap and the derives
• More universal traits. Crates exist for common CLI patterns
  (example)
  and we've re-designed the StructOpt traits so crates built on clap3 can be
  reused not just with other derives but also people using the builder API.
  People can even hand implement these so people using the builder API won't
  have the pay the cost for derives.

Custom 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)
  • Porting example
• The YAML API has been deprecated in favor the builder or derive APIs (clap-rs/clap#3087)

Migrating

From clap v2

1. Add CLI tests, -h and --help output at a minimum (recommendation: trycmd for snapshot testing)
2. Update your dependency
   1. If you use no-default-features: add the std feature
3. Resolve compiler errors
4. Resolve behavior changes
   1. Refactor your App creation to a function and add a test similar to the one below, resolving any of its assertions
   2. Look over the "subtle changes" under BREAKING CHANGES
   3. If using builder: test your application under various circumstances to see if ArgMatches asserts regarding AllowInvalidUtf8.
5. At your leisure: resolve deprecation notices

Example test:

fn app() -> clap::App<'static> {
    ...
}

#[test]
fn verify_app() {
    app().debug_assert();
}

From structopt 0.3.25

1. Add CLI tests, -h and --help output at a minimum (recommendation: trycmd for snapshot testing)
2. Update your dependency, adding the derive feature flag
   1. If you use no-default-features: add the std feature
3. Resolve compiler errors, including
   1. Update your use statements from structopt and structopt::clap to clap
4. Resolve behavior changes
   1. Add a test similar to the one below, resolving any of its assertions
   2. Look over the "subtle changes" under BREAKING CHANGES
5. At your leisure: resolve deprecation notices

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

1. Add CLI tests, -h and --help output at a minimum (recommendation: trycmd for snapshot testing)
2. Update your dependency
   1. Add in derive, env, cargo, or unicode feature flags as needed
3. Resolve compiler errors
   1. If you use yaml, clap_app!, or usage parser: revert any changes you made for clap3
   2. Change Arg::about Arg::long_about back to help and long_help and change PossibleValue::about to help (clap-rs/clap#3075)
   3. Change AppSettings::HelpRequired to AppSettings::HelpExpected
   4. Change PossibleValue::hidden to PossibleValue::hide
   5. Change App::subcommand_placeholder to App::subcommand_value_name / App::subcommand_help_heading
4. Resolve behavior changes
   1. Add the above listed test appropriate for your application and resolve any problems it reports
   2. If using derive: see the structopt breaking changes section for Vec changes
   3. If using builder: test your application under various circumstances to see if ArgMatches asserts regarding AllowInvalidUtf8.
5. At your leisure: resolve deprecation notices

BREAKING CHANGES

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
  • See clap-rs/clap#2807
• AppSettings::EnableColoredHelp is now the default behavior but can be
  opted-out with AppSettings::DisableColoredHelp
  (clap-rs/clap#2806)
• App::override_usage no longer implies a leading \t, allowing multi lined usages
• Arg::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
• Some env variable values are now considered false for flags, not just "not-present" (clap-rs/clap#2539)
• Changed ...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:

• When using no-default-features, you now have to specify the std feature (reserved for future work)
• Gated env support behind env feature flag
  • Impacts Arg::env, Arg::env_os, Arg::hide_env_values, ArgSettings::HideEnvValues
  • See clap-rs/clap#2694
• Gated crate information behind cargo feature flag
  • Impacts crate_name!, crate_version!, crate_authors!, crate_description!, app_from_crate!
• AppSettings::StrictUtf8 is now default behaviour and asserts if
  AppSettings::AllowInvalidUtf8ForExternalSubcommands and
  ArgSettings::AllowInvalidUtf8 and ArgMatches::value_of_os aren't used
  together
  • AppSettings::AllowInvalidUtf8 has been removed
  • clap-rs/clap#751
• Arg::short and Arg::value_delimiter now take a char instead of a &str
• ArgMatches panics on unknown arguments
• Removed VersionlessSubcommands, making it the default (see clap-rs/clap#2812)
• Completion generation has been split out into clap_complete.
• Removed ArgSettings::EmptyValues in favor of ArgSettings::ForbidEmptyValues
• Validator signatures have been loosed:
  • Arg::validator now takes first argument as Fn(&str) -> Result<O, E: ToString> instead of
    Fn(String) -> Result<(), String>
  • Arg::validator_os now takes first argument as Fn(&OsStr) -> Result<O, OsString> instead of
    Fn(&OsStr) -> Result<(), OsString>
• Arg::value_name now sets, rather than appends (see clap-rs/clap#2634)
• Upgrade yaml-rust from 0.3 to 0.4
• Replaced ArgGroup::from(BTreeMap) to ArgGroup::from(yaml)
• Replaced ArgMatches::usage with App::generate_usage
• Replaced Arg::settings with Arg::setting(Setting1 | Setting2)
• App and Arg now need only one lifetime
• Removed deprecated App::with_defaults, replaced with app_from_crate
• Removed deprecated AppSettings::PropagateGlobalValuesDown (now the default)
• Some 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)
• Changed App::print_help & App::print_long_help to now return std::io::Result
• Changed App::write_help & App::write_long_help to now return std::io::Result
• Changed Arg::index, Arg::number_of_values, Arg::min_values, Arg::max_values to taking usize instead of u64
• Changed Error::info to type Vec<String> instead of Option<Vec<String>>
• Changed ArgMatches::subcommand to now return Option<(&str, &ArgMatches)>
• Renamed ErrorKind::MissingArgumentOrSubcommand to ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
• Renamed ErrorKind::HelpDisplayed to ErrorKind::DisplayHelp
• Renamed ErrorKind::VersionDisplayed to ErrorKind::DisplayVersion
• Added #[non_exhaustive] to clap::{ValueHint, ErrorKind, AppSettings, ArgSettings} (clap-rs/clap#3167)

From structopt 0.3.25

• By default, the 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)
• Subcommands nested under subcommands now needs a #[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

Performance

From clap 2

• Split out non-default unicode feature flag for faster builds and smaller binaries for ASCII-only CLIs.
• Split out non-default env feature flag for faster builds and smaller binaries.

Features

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)
  • See clap-rs/clap#805
  • 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

  • Debug builds will assert when the ArgMatches calls do not match the UTF-8 setting.
  • See clap-rs/clap#751

• clap::PossibleValue to allow

  • Hiding (clap-rs/clap#2756)
  • Completion help for possible values for args (clap-rs/clap#2731)

• Allow arguments to conflict with all others via Arg::exclusive (clap-rs/clap#1583)

• Validate arguments with a regex (required regex feature flag)

  • See clap-rs/clap

• 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

  • Positionals can be either

• 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

  • See AppSettings::Multicall behind unstable-multicall feature flag
  • See clap-rs/clap#1120

• (Experimental) Alias an argument to anything group of arguments

  • See App::replace behind unstable-replace feature flag
  • See clap-rs#1603

• (Experimental) Grouping of multiple values within multiple occurrences

  • See ArgMatches::grouped_values_of behind unstable-grouped feature flag
  • See clap-rs/clap#1026

From structopt 0.3.25

• Allow defaulting with native types via new default_value_t [= <expr>] attribute (clap-rs/clap#1694)
• New update API
• New arg_enum attribute for integrating with ArgEnum trait

On top of the clap 2 changes

Fixes

From clap 2

• Correctly handle colored output on Windows
• Only generate version flags when App::version, App::long_version are set
  (see clap-rs/clap#2812)
• General completion script improvements
• Limited default help text wrapping to 100 when wrap_help feature is not enabled
• Be more specific than Arg::multiple with Arg::multiple_values and Arg::multiple_occurrences
• app_from_crate! defaults to separating multiple authors with ", "
• Ensure all examples work
• IgnoreCase is now unicode aware (requires unicode feature flag)
• Always respect ColorChoice::Never, even if that means we skip colors in some cases
• ArgMatches panics on unknown arguments
• Gracefully handle empty authors field in Cargo.toml with app_from_crate
• Do not show --help in cmd help with DisableHelpFlag (clap-rs/clap#3169)
• Do not show --help in cmd help help that doesn't work (clap-rs/clap#3169)

From structopt 0.3.25

• Support SubcommandsNegateReqs by allowing required Option<_>s (clap-rs/clap#2255)
• Infer AllowInvalidUtf8 based on parser (clap-rs/clap#751)
• Gracefully handle empty authors field in Cargo.toml
• Don't panic with default_value_os but treat it like default_value (clap-rs/clap#3031)
• When using 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

Minimum Required Rust

• As of this release, clap requires rustc 1.54.0 or greater.

Improvements

• Suppress deprecation warnings when using crate_* macros.

v2.33.2 (2020-08-5)

Documentation

• Fixed links to 2.x examples. Now they point to the right place.

v2.33.1 (2020-05-11)

Bug Fixes

• Windows: Prevent some panics when parsing invalid Unicode on Windows (922c645, closes #1905)

Documentation

• fixes versions referenced in the README (d307466a)
• README.md:
  • cuts down the number of examples to reduce confusion (6e508ee0)

Improvements

• Deps: doesnt compile ansi_term on Windows since its not used (b57ee946, closes #1155)

Minimum Required Rust

• As of this release, clap requires rustc 1.36.0 or greater.

v2.31.2 (2018-03-19)

Bug Fixes

• Fish Completions: fixes a bug that only allowed a single completion in in Fish Shell (e8774a8, closes #1212)
• AllowExternalSubcommands: fixes a bug where external subcommands would be blocked by a similarly named subcomand (suggestions were getting in the way). (a410e85)

Documentation

• Fixes some typos in the README.md (c8e685d7)

v2.31.1 (2018-03-06)

Improvements

• AllowMissingPositional: improves the ability of AllowMissingPositional to allow 'skipping' to the last positional arg with '--' (df20e6e2)

v2.31.0 (2018-03-04)

Features

• Arg Indices: adds the ability to query argument value indices (f58d0576)
• Indices: implements an Indices<Item=&usize> iterator (1e67be44)
• Raw Args adds a convenience function to Arg that allows implying all of Arg::last Arg::allow_hyphen_values and Arg::multiple(true) (66a78f29)

Documentation

• Fix some typos and markdown issues. (935ba0dd)
• Arg Indices: adds the documentation for the arg index querying methods (50bc0047)
• CONTRIBUTING.md: fix url to clippy upstream repo to point to https://github.com/rust-lang-nursery/rust-clippy instead of https://github.com/Manishearth/rust-clippy (42407d7f)
• Values: improves the docs example of the Values iterator (74075d65)
• Updates readme to hint that the wrap_help feature is a thing (fc7ab227)

Improvements

• Cargo.toml: use codegen-units = 1 in release and bench profiles (19f425ea)
• Adds WASM support (clap now compiles on WASM!) (689949e5)
• Uses the short help tool-tip for PowerShell completion scripts (ecda22ce)

v2.30.0 (2018-02-13)

Bug Fixes

• YAML: Adds a missing conversion from Arg::last when instantiating from a YAML file (aab77c81a5, closes #1160)

Improvements

• Bash Completions: instead of completing a generic option name, all bash completions fall back to file completions UNLESS Arg::possible_values was used (872f02ae)
• Deps: No longer needlessly compiles ansi_term on Windows since its not used (b57ee946, closes #1155)
• Help Message: changes the [values: foo bar baz] array to [possible values: foo bar baz] for consistency with the API (414707e4e97, closes #1160)

v2.29.3 (2018-02-05)

Improvements

• Overrides: clap now supports arguments which override with themselves (6c7a0010, closes #976)

Bug Fixes

• Requirements: fixes an issue where conflicting args would still show up as required (e06cefac, closes #1158)
• Fixes a bug which disallows proper nesting of -- (73993fe, closes #1161)

New Settings

• AllArgsOverrideSelf: adds a new convenience setting to allow all args to override themselves (4670325d)

Changes since 2.27.0 (most recent tag before this):

2.29.1 (2018-01-09)

Documentation

• fixes broken links. (56e734b8)
• updates contributors list (e1313a5a)

Performance

• further debloating by removing generics from error cases (eb8d919e)
• debloats clap by deduplicating logic and refactors (03e413d7)

Bug Fixes

• fixes the ripgrep benchmark by adding a value to a flag that expects it (d26ab2b9)
• bash completion: Change the bash completion script code generation to support hyphens. (ba7f1d18)
• completions/zsh.rs: Fix completion of long option values (46365cf8)

2.29.0 (2017-12-02)

API Additions

• Arg: adds Arg::hide_env_values(bool) which allows one to hide any current env values and display only the key in help messages (fb41d062)

2.28.0 (2017-11-28)

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!

Documentation

• changes the demo version to 2.28 to stay in sync (ce6ca492)
• Fix URL path to github hosted files (ce72aada, closes #1106)
• fix typo (002b07fc)
• README.md: updates the readme and pulls out some redundant sections (db6caf86)

Improvements

• adds '[SUBCOMMAND]' to usage strings with only AppSettings::AllowExternalSubcommands is used with no other subcommands (e78bb757, closes #1093)

API Additions

• Adds Arg::case_insensitive(bool) which allows matching Arg::possible_values without worrying about ASCII case (1fec268e, closes #1118)
• Adds the traits to be used with the clap-derive crate to be able to use Custom Derive (6f4c3412)

Bug Fixes

• Fixes a regression where --help couldn't be overridden (a283d69f, closes #1112)
• fixes a bug that allowed options to pass parsing when no value was provided (2fb75821, closes #1105)
• ignore PropagateGlobalValuesDown deprecation warning (f61ce3f5, closes #1086)

Deps

• Updates bitflags to 1.0

v2.27.1 (2017-10-24)

Bug Fixes

• Adds term_size as an optional dependency (with feature wrap_help) to fix compile bug

v2.27.0 (2017-10-24)

** 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.

Bug Fixes

• Values from global args are now propagated UP and DOWN!
• fixes a bug where using AppSettings::AllowHyphenValues would allow invalid arguments even when there is no way for them to be valid (77ed4684, closes #1066)
• when an argument requires a value and that value happens to match a subcommand name, its parsed as a value (0c223f54, closes #1031, breaks #, #)
• fixes a bug that prevented number_of_values and default_values to be used together (5eb342a9, closes #1050, #1056)
• fixes a bug that didn't allow args with default values to have conflicts (58b5b4be, closes #1071)
• fixes a panic when using global args and calling App::get_matches_from_safe_borrow multiple times (d86ec797, closes #1076)
• fixes issues and potential regressions with global args values not being propagated properly or at all (a43f9dd4, closes #1010, #1061, #978)
• fixes a bug where default values are not applied if the option supports zero values (9c248cbf, closes #1047)

Documentation

• adds addtional blurbs about using multiples with subcommands (03455b77)
• updates the docs to reflect changes to global args and that global args values can now be propagated back up the stack (ead076f0)
• add html_root_url attribute (e67a061b)
• sync README version numbers with crate version (5536361b)

Improvements

• args that have require_delimiter(true) is now reflected in help and usage strings (dce61699, closes #1052)
• if all subcommands are hidden, the subcommands section of the help message is no longer displayed (4ae7b046, closes #1046)

Breaking Changes

• when an argument requires a value and that value happens to match a subcommand name, its parsed as a value (0c223f54, closes #1031, breaks #, #)

Deprecations

• AppSettings::PropagateGlobalValuesDown: this setting is no longer required to propagate values down or up (2bb5ddce)

v2.26.1 (2017-09-14)

Bug Fixes

• fixes using require_equals(true) and min_values(0) together (10ae208f, closes #1044)
• escape special characters in zsh and fish completions (87e019fc)
• avoid panic generating default help msg if term width set to 0 due to bug in textwrap 0.7.0 (b3eadb0d)
• Change who's -> whose (53c1ffe8)
• adds a debug assertion to ensure all args added to groups actually exist (7ad123e2, closes #917)
• fixes a bug where args that allow values to start with a hyphen couldnt contain a double hyphen -- as a value (ab2f4c9e, closes #960)
• fixes a bug where positional argument help text is misaligned (54c16836)
• Help Message: fixes long_about not being usable (a8257ea0, closes #1043)
• Suggestions: output for flag after subcommand (434ea5ba)

v2.26.0 (2017-07-29)

Minimum version of Rust is now v1.13.0 (Stable)

Improvements

• bumps unicode-segmentation to v1.2 (cd7b40a2)

Performance

• update textwrap to version 0.7.0 (c2d4e637)

v2.25.1 (2017-07-21)

Improvements

• impl Default for Values + OsValues for any lifetime. (fb7d6231f1)

Documentation

• Various documentation typos and grammar fixes

v2.25.0 (2017-06-20)

Features

• use textwrap crate for wrapping help texts (b93870c1)

Improvements

• Suggestions: suggests to use flag after subcommand when applicable (2671ca72)
• Bumps bitflags crate to v0.9

Documentation

• Change who's -> whose (53c1ffe8)

Documentation

• App::template: adds details about the necessity to use AppSettings::UnifiedHelpMessage when using {unified} tags in the help template (cbea3d5a, closes #949)
• Arg::allow_hyphen_values: updates the docs to include warnings for allow_hyphen_values and multiple(true) used together (f9b0d657)
• README.md:
  • added a warning about using ~ deps (821929b5, closes #964)
• clap_app!: adds using the @group specifier to the macro docs (826048cb, closes #932)

v2.24.0 (2017-05-07)

Bug Fixes

• fixes a bug where args with last(true) and required(true) set were not being printed in the usage string (3ac533fe, closes #944)
• fixes a bug that was printing the arg name, instead of value name when Arg::last(true) was used (e1fe8ac3, closes #940)
• fixes a bug where flags were parsed as flags AND positional values when specific combinations of settings were used (20f83292, closes #946)

v2.24.0 (2017-05-05)

Documentation

• README.md: fix some typos (fa34deac)

API Additions

• Arg: add default_value_os (d5ef8955)
• arg_matches.rs: Added a Default implementation for Values and OsValues iterators. (0a4384e3)

v2.23.2 (2017-04-19)

Bug Fixes

• PowerShell Completions: fixes a bug where powershells completions cant be used if no subcommands are defined (a8bce558, closes #931)

Improvements

• bumps term_size to take advantage of better terminal dimension handling (e05100b7)
• PowerShell Completions: massively dedups subcommand names in the generate script to make smaller scripts that are still functionally equiv (85b0e1cc)

Documentation

• Fix a typo the minimum rust version required (71dabba3)

v2.23.1 (2017-04-05)

Bug Fixes

• fixes a missing newline character in the autogenerated help and version messages in some instances (5ae9007d)

v2.23.0 (2017-04-05)

API Additions

• 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

Features

• allows distinguishing between short and long version messages (-V/short or --version/long) (59272b06)
• allows distinguishing between short and long help with subcommands in the same manner as args (6b371891)
• allows specifying a short help vs a long help (i.e. varying levels of detail depending on if -h or --help was used) (ef1b24c3)
• clap_app!: adds support for arg names with hyphens similar to longs with hyphens (f7a88779, closes #869)

Bug Fixes

• fixes a bug that wasn't allowing help and version to be properly overridden (8b2ceb83, closes #922)

Documentation

• clap_app!: documents the --("some-arg") method for using args with hyphens inside them (bc08ef3e, closes #919)

v2.22.2 (2017-03-30)

Bug Fixes

• Custom Usage Strings: fixes the usage string regression when using help templates (0e4fd96d)

v2.22.1 (2017-03-24)

Bug Fixes

• usage: fixes a big regression with custom usage strings (2c41caba)

v2.22.0 (2017-03-23)

API Additions

• App::name: adds the ability to change the name of the App instance after creation (d49e8292, closes #908)
• Arg::hide_default_value: adds ability to hide the default value of an argument from the help string (89e6ea86, closes #902)

v2.21.2 (2017-03-17)

Improvements

• add fish subcommand help support (f8f68cf8)
• options that use require_equals(true) now display the equals sign in help messages, usage strings, and errors" (c8eb0384, closes #903)

Bug Fixes

• setting the max term width now correctly propagates down through child subcommands

v2.21.1 (2017-03-12)

Bug Fixes

• ArgRequiredElseHelp: fixes the precedence of this error to prioritize over other error messages (74b751ff, closes #895)
• Positionals: fixes some regression bugs resulting from old asserts in debug mode. (9a3bc98e, closes #896)

v2.21.0 (2017-03-09)

Performance

• doesn't run arg_post_processing on multiple values anymore (ec516182)
• changes internal use of VecMap to Vec for matched values of Args (22bf137a)
• vastly reduces the amount of cloning when adding non-global args minus when they're added from App::args which is forced to clone (8da0303b)
• refactor to remove unneeded vectors and allocations and checks for significant performance increases (0efa4119)

Documentation

• Fix examples link in CONTRIBUTING.md (60cf875d)

Improvements

• when AppSettings::SubcommandsNegateReqs and ArgsNegateSubcommands are used, a new more accurate double line usage string is shown (50f02300, closes #871)

API Additions

• Arg::last: adds the ability to mark a positional argument as 'last' which means it should be used with -- syntax and can be accessed early (6a7aea90, closes #888)
• provides default_value_os and default_value_if[s]_os (0f2a3782, closes #849)
• provides App::help_message and App::version_message which allows one to override the auto-generated help/version flag associated help (389c413, closes #889)

New Settings

• InferSubcommands: adds a setting to allow one to infer shortened subcommands or aliases (i.e. for subcommmand "test", "t", "te", or "tes" would be allowed assuming no other ambiguities) (11602032, closes #863)

Bug Fixes

• doesn't print the argument sections in the help message if all args in that section are hidden (ce5ee5f5)
• doesn't include the various [ARGS] [FLAGS] or [OPTIONS] if the only ones available are hidden (7b4000af, closes #882)
• now correctly shows subcommand as required in the usage string when AppSettings::SubcommandRequiredElseHelp is used (8f0884c1)
• fixes some memory leaks when an error is detected and clap exits (8c2dd287)
• fixes a trait that's marked private accidentlly, but should be crate internal public (1ae21108)
• Completions: fixes a bug that tried to propogate global args multiple times when generating multiple completion scripts (5e9b9cf4, closes #846)

Features

• Options: adds the ability to require the equals syntax with options --opt=val (f002693d, closes #833)

v2.20.3 (2017-02-03)

Documentation

• Macros: adds a warning about changing values in Cargo.toml not triggering a rebuild automatically (112aea3e, closes #838)

Bug Fixes

• fixes a println->debugln typo (279aa62e)
• fixes bash completions for commands that have an underscore in the name (7f5cfa72, closes #581)
• fixes a bug where ZSH completions would panic if the binary name had an underscore in it (891a2a00, closes #581)
• allow final word to be wrapped in wrap_help (564c5f0f, closes #828)
• fixes a bug where global args weren't included in the generated completion scripts (9a1e006e, closes #841)

v2.20.2 (2017-02-03)

Bug Fixes

• fixes a critical bug where subcommand settings were being propogated too far (74648c94, closes #832)

Improvements

• adds ArgGroup::multiple to the supported YAML fields for building ArgGroups from YAML (d8590037, closes #840)

v2.20.1 (2017-01-31)

Bug Fixes

• allow final word to be wrapped in wrap_help (564c5f0f, closes #828)
• actually show character in debug output (84d8c547)
• include final character in line lenght (aff4ba18)

Improvements

• updates libc and term_size deps for the libc version conflict (6802ac4a)

Documentation

• fix link from app_from_crate! to crate_authors! (#822) (5b29be9b)
• fix spelling of "guaranteed" (4f30a65b)

New Settings

• ArgsNegateSubcommands: disables args being allowed between subcommands (5e2af8c9, closes #793)
• DontCollapseArgsInUsage: disables the collapsing of positional args into [ARGS] in the usage string (c2978afc, closes #769)
• DisableHelpSubcommand: disables building the help subcommand (a10fc859)
• AllowMissingPositional: allows one to implement $ prog [optional] <required> style CLIs where the second postional argument is required, but the first is optional (1110fdc7, closes #636)
• PropagateGlobalValuesDown: automatically propagats global arg's values down through used subcommands (985536c8, closes #694)

API Additions

Arg

• Arg::value_terminator: adds the ability to terminate multiple values with a given string or char (be64ce0c, closes #782)
• Arg::default_value_if[s]: adds new methods for conditional default values (such as a particular value from another argument was used) (eb4010e7)
• Arg::requires_if[s]: adds the ability to conditionally require additional args (such as if a particular value was used) (198449d6)
• Arg::required_if[s]: adds the ability for an arg to be conditionally required (i.e. "arg X is only required if arg Y was used with value Z") (ee9cfddf)
• Arg::validator_os: adds ability to validate values which may contain invalid UTF-8 (47232498)

Macros

• crate_description!: Uses the Cargo.toml description field to fill in the App::about method at compile time (4d9a82db, closes #778)
• crate_name!: Uses the Cargo.toml name field to fill in the App::new method at compile time (4d9a82db, closes #778)
• app_from_crate!: Combines 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)

Features

• no_cargo: adds a no_cargo feature to disable Cargo-env-var-dependent macros for those not using cargo to build their crates (#786) (6fdd2f9d)

Bug Fixes

• Options: fixes a critical bug where options weren't forced to have a value (5a5f2b1e, closes #665)
• fixes a bug where calling the help of a subcommand wasn't ignoring required args of parent commands (d3d34a2b, closes #789)
• Help Subcommand: fixes a bug where the help subcommand couldn't be overriden (d34ec3e0, closes #787)
• Low Index Multiples: fixes a bug which caused combinations of LowIndexMultiples and Arg::allow_hyphen_values to fail parsing (26c670ca)

Improvements

• Default Values: improves the error message when default values are involved (1f33de54, closes #774)
• YAML: adds conditional requirements and conditional default values to YAML (9a4df327, closes #764)
• Support --("some-arg-name") syntax for defining long arg names when using clap_app! macro (f41ec962)
• Support ("some app name") syntax for defining app names when using clap_app! macro (9895b671, closes #759)
• Help Wrapping: long app names (with spaces), authors, and descriptions are now wrapped appropriately (ad4691b7, closes #777)

Documentation

• Conditional Default Values: fixes the failing doc tests of Arg::default_value_ifs (4ef09101)
• Conditional Requirements: adds docs for Arg::requires_ifs (7f296e29)
• README.md: fix some typos (f22c21b4)
• src/app/mod.rs: fix some typos (5c9b0d47)

v2.19.3 (2016-12-28)

Bug Fixes

• fixes a bug where calling the help of a subcommand wasn't ignoring required args of parent commands (a0ee4993, closes #789)

v2.19.2 (2016-12-08)

Bug Fixes

• ZSH Completions: escapes square brackets in ZSH completions (7e17d5a3, closes #771)

Documentation

• Examples: adds subcommand examples (0e0f3354, closes #766)
• README.md: adds guidance on when to use ~ in version pinning, and clarifies breaking change policy (591eaefc, closes #765)

v2.19.1 (2016-12-01)

Bug Fixes

• Help Messages: fixes help message alignment when specific settings are used on options (cd94b318, closes #760)

Improvements

• Bash Completion: allows bash completion to fall back to traidtional bash completion upon no matching completing function (b1b16d56))