Beta Changelogs

[epage]

v3.0.0-beta.5 (2021-10-18)

BREAKING CHANGES

• Renamed Features
  • unicode_help to unicode to encompass more functionality
• Gated behind features
  • App::replace is now gated behind unstable-replace
• Removed derive requirement
  • clap::ArgEnum
  • clap::Args
  • clap::FromArgMatches
  • clap::IntoApp
  • clap::Subcommand
• Renamed Traits
  • clap::Clap => clap::Parser
• Renamed Methods
  • App::generate_usage => App::render_usage
• Removed Settings
  • AppSettings::DisableVersionForSubcommands is now default behaviour
  • AppSettings::ColoredHelp: we are now relying solely on the color feature flag and App::color method
  • AppSettings::StrictUtf8 is now default behaviour
  • AppSettings::AllowInvalidUtf8 in favor of ArgSettings::AllowInvalidUtf8
  • AppSettings::UnifiedHelpMessage is now default behaviour
  • AppSettings::ColorAlways in favor of App::color
  • AppSettings::ColorNever in favor of App::color
  • AppSettings::ColorAuto in favor of App::color
• Removed methods
  • App
    • App::get_flags
    • App::get_positionals_with_no_heading
    • App::get_flags_with_no_heading
    • App::get_opts_with_no_heading
    • App::stop_custom_headings in favor of App:help_heading(None)
  • Error
    • Error::with_description in favor of App::error
  • ArgEnum
    • ArgEnum::as_arg in favor of ArgEnum::to_arg_value
  • clap_generate::Generator
    • Generator::all_subcommands
    • Generator::find_subcommand_with_path
    • Generator::subcommands
    • Generator::shorts_and_visible_aliases
    • Generator::longs_and_visible_aliases
    • Generator::flags
• Removed
  • ArgEnum::VARIANTS in favor of ArgEnum::value_variants
• Deprecated
  • clap::clap_app! in favor of other builders
• Changed
  • App::get_possible_values returns Option<&[ArgValue]> now
  • RegexRef is now an enum also allowing RegexSet to be used
  • clap_generate::Generator::file_name and clap_generate::Generator::generate now take &self
  • clap_generate::generate and clap_generate::generate_to now takes Generator as first argument

Features

• Added
  • clap::ArgValue to denote information about possible values for args
  • clap::ColorChoice to specify color setting for the app
• Added Settings
  • AppSettings::AllowInvalidUtf8ForExternalSubcommands
  • AppSettings::Multicall behind unstable-multicall feature
  • ArgSettings::AllowInvalidUtf8
• Added Methods
  • ArgEnum
    • ArgEnum::value_variants
    • ArgEnum::to_arg_value
  • App
    • App::color
    • App::error
    • App::get_long_about
    • App::get_help_heading
  • Arg
    • Arg::is_positional
• Allow positionals to occur multiple times

v3.0.0-beta.4 (2021-08-14)

Minimum Required Rust

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

BREAKING CHANGES

Added unicode_help, env features.

• Gated behind env:
  • Arg
    • Arg::env
    • Arg::env_os
    • Arg::hide_env_values
  • ArgSettings
    • ArgSettings::HideEnvValues
• Removed Methods
  • Arg
    • Arg::settings in favor of Arg::setting(Setting1 | Setting2)
    • Arg::multiple in favour of Arg::multiple_values and Arg::multiple_occurrences
• Renamed Settings
  • AppSettings::DisableHelpFlags => AppSettings::DisableHelpFlag
  • AppSettings::DisableVersion => AppSettings::DisableVersionFlag
  • AppSettings::VersionlessSubcommands => AppSettings::DisableVersionForSubcommands (changed again 3.0.0-beta.5)
• Renamed Variants
  • ErrorKind
    • ErrorKind::MissingArgumentOrSubcommand => ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
• Changed
  • Allowing empty values is the default again with ArgSettings::AllowEmptyValues changing to
    ArgSettings::ForbidEmptyValues
  • AppSettings::GlobalVersion renamed to AppSettings::PropagateVersion and it is not applied
    globally anymore
  • 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 does not set ArgSettings::TakesValue anymore
  • Arg::require_delimiter does not set ArgSettings::TakesValue and ArgSettings::UseValueDelimiter
    anymore
  • Arg::require_equals does not disallow empty values anymore
  • 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
  • Arg::index, Arg::number_of_values, Arg::min_values, Arg::max_values now takes usize
  • Arg::value_delimiter now accepts char instead of &str
  • ArgMatches::is_present does not handle subcommand names anymore
  • Some env var values are considered the same as env var not being present when the arg does not have
    ArgSettings::TakesValue
  • clap_generate::generate_to now returns Result<PathBuf, io::Error>
  • @group in clap_app! now needs : instead of =>
  • app and arg objects in yaml now allow unknown keys if _has_metadata is set

Features

• Added
  • clap_generate::Shell
  • clap::Args behind derive feature
• Added Methods
  • App
    • App::license
  • Arg
    • Arg::get_long_about
    • Arg::get_env
    • Arg::get_default_values
    • Arg::hide_env
    • Arg::required_if_eq_all
    • Arg::forbid_empty_values
    • Arg::max_occurrences
  • ArgMatches
    • ArgMatches::grouped_values_of
  • Macros
    • crate_license!
  • Error
    • Error::print
• Added Settings
  • AppSettings::UseLongFormatForHelpSubcommand
  • AppSettings::IgnoreErrors
  • AppSettings::InferLongArgs
  • ArgSettings::HideEnv

Enhancements

• Better completion scripts
• Multiple bug fixes, performance improvements and error message improvements

v3.0.0-beta.2 (2020-09-18)

BREAKING CHANGES

• Removed
  • From<&yaml_rust::yaml::Hash> for ArgGroup
  • App
    • App::write_version in favor of write!(w, App::render_version)
    • App::write_long_version in favor of write!(w, App::render_long_version)
  • Error
    • Error::cause in favor of <Error as Display>::to_string
  • Macros
    • _clap_count_exprs!
• Renamed Methods
  • App
    • App::set_term_width => App::term_width
  • Arg
    • Arg::from_yaml => Arg::from
    • Arg::with_name => Arg::new
    • Arg::required_if => Arg::required_if_eq
    • Arg::required_ifs => Arg::required_if_eq_any
    • Arg::required_unless => Arg::required_unless_present
    • Arg::required_unless_one => Arg::required_unless_present_any
    • Arg::required_unless_all => Arg::required_unless_present_all
  • ArgGroup
    • ArgGroup::from_yaml => ArgGroup::from
    • ArgGroup::with_name => ArgGroup::new
• Renamed Variants
  • ErrorKind
    • ErrorKind::HelpDisplayed => ErrorKind::DisplayHelp
    • ErrorKind::VersionDisplayed => ErrorKind::DisplayVersion
• Changed
  • App::print_help & App::print_long_help now return std::io::Result
  • App::write_help & App::write_long_help now return std::io::Result
  • Error::info now is of type Vec<String> instead of Option<Vec<String>>
  • ArgMatches::subcommand now returns Option<(&str, &ArgMatches)>
  • short in #[clap()] now accepts char instead of &str

Features

• Added support for subcommands that are flags (pacman style)
• Added Indices that is returned by ArgMatches::indices_of
• Added @global_setting for app's macro builder
• Added Methods
  • Arg
    • Arg::default_missing_value
    • Arg::default_missing_value_os
    • Arg::default_missing_values
    • Arg::default_missing_values_os
    • Arg::short_alias
    • Arg::short_aliases
    • Arg::visible_short_alias
    • Arg::visible_short_aliases
    • Arg::value_hint
    • Arg::validator_regex (gated behind regex feature)
  • App
    • App::subcommand_placeholder
    • App::before_long_help
    • App::after_long_help
• TODO: List App::get_* methods

Enhancements

• help_heading defined on Arg now has higher priority than App
• Limited default text wrapping to 100 when wrap_help feature is not enabled
• Multiple bug fixes and error message improvements
• Size and Performance improvements

v3.0.0-beta.1 (2020-05-03)

Minimum Required Rust

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

BREAKING CHANGES

Added std, cargo, derive features.

• Gated behind cargo:

  • Macros
    • crate_name!
    • crate_version!
    • crate_authors!
    • crate_description!
    • app_from_crate!

• Removed

  • SubCommand in favor of App
    • SubCommand::with_name => App::new
    • SubCommand::from_yaml => App::from
  • Shell (changed again in 3.0.0-beta.4)
  • App
    • App::with_defaults
    • App::version_message in favor of App::mut_arg
    • App::version_short in favor of App::mut_arg
    • App::help_message in favor of App::mut_arg
    • App::help_short in favor of App::mut_arg
    • App::arg_from_usage in favor of App::arg
    • App::args_from_usage in favor of App::args
    • App::settings in favor of App::setting(Setting1 | Setting2)
    • App::unset_settings in favor of App::unset_setting(Setting1 | Setting2)
    • App::global_settings in favor of App::global_setting(Setting1 | Setting2)
    • App::gen_completions in favor of TODO:
    • App::gen_completions_to in favor of TODO:
  • Arg
    • Arg::empty_values in favor of TODO:
  • ArgMatches
    • ArgMatches::usage in favor of App::generate_usage
  • Macros
    • arg_enum! in favor of ArgEnum derive macro.
    • value_t! in favor of ArgMatches::value_of_t
    • value_t_or_exit! in favor of ArgMatches::value_of_t_or_exit
    • values_t! in favor of ArgMatches::values_of_t
    • values_t_or_exit! in favor of ArgMatches::values_of_t_or_exit

• Removed Settings

  • AppSettings::PropagateGlobalValuesDown
  • ArgSettings::Global in favor of Arg::global method
  • ArgSettings::Multiple in favor of ArgSettings::MultipleValues and ArgSettings::MultipleOccurrences

• Renamed Methods

  • App
    • App::from_yaml => App::from
    • App::arg_from_usage => App::arg
    • App::help => App::override_help
    • App::usage => App::override_usage
    • App::template => App::help_template
    • App::get_matches_safe => App::try_get_matches
    • App::get_matches_from_safe => App::try_get_matches_from
    • App::get_matches_from_safe_borrow => App::try_get_matches_from_mut
  • Arg
    • Arg::help => Arg::about
    • Arg::from_usage => Arg::from
    • Arg::set => Arg::setting
    • Arg::unset => Arg::unset_setting

• Renamed Settings

  • ArgSettings::CaseInsensitive => ArgSettings::IgnoreCase
  • ArgSettings::AllowLeadingHyphen => ArgSettings::AllowHyphenValues
  • ArgSettings::EmptyValues => ArgSettings::AllowEmptyValues

• Renamed Fields

  • Error::message => Error::cause

• Changed

  • App::write_help is now a mutable reference instance method (takes &mut self)
  • Arg::short now accepts char instead of &str
  • 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>

• Removed support for {n} in help text

• In usage parser, for options [name]... --option [val] results in ArgSettings::MultipleOccurrences
  but --option [val]... results in ArgSettings::MultipleValues and ArgSettings::MultipleOccurrences.
  Before both resulted in the same thing.

• App and Arg now need only one lifetime

• Allowing empty values is no longer the default (changed again in 3.0.0-beta.4)

• UseValueDelimiter is no longer the default

• App::override_usage no longer implies \t which allows multi lined usages

Features

• Added Methods
  • App
    • App::replace
    • App::get_matches_mut
    • App::mut_arg
    • App::unset_global_setting
    • App::help_heading
    • App::stop_custom_headings
  • Arg
    • Arg::exclusive
    • Arg::multiple_values
    • Arg::multiple_occurrences
    • Arg::help_heading
    • Arg::settings (changed again in 3.0.0-beta.4)
• Added Settings
  • AppSettings::HelpRequired
  • AppSettings::NoAutoHelp
  • AppSettings::NoAutoVersion
  • ArgSettings::SubcommandPrecedenceOverArg

Enhancements

• Made App::arg and App::args more generic
• Improvements to clap_app! macro to make it support more wider use cases
• Colors now work correctly on Windows Console
• Multiple bug fixes and error message improvements
• Improvements to parsing logic and help messages