<commit_before>clap
====

[![Crates.io](https://img.shields.io/crates/v/clap.svg)](https://crates.io/crates/clap) [![Crates.io](https://img.shields.io/crates/d/clap.svg)](https://crates.io/crates/clap) [![license](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kbknapp/clap-rs/blob/master/LICENSE-MIT) [![Coverage Status](https://coveralls.io/repos/kbknapp/clap-rs/badge.svg?branch=master&service=github)](https://coveralls.io/github/kbknapp/clap-rs?branch=master) [![Join the chat at https://gitter.im/kbknapp/clap-rs](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/kbknapp/clap-rs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Linux: [![Build Status](https://travis-ci.org/kbknapp/clap-rs.svg?branch=master)](https://travis-ci.org/kbknapp/clap-rs)
Windows: [![Build status](https://ci.appveyor.com/api/projects/status/ejg8c33dn31nhv36/branch/master?svg=true)](https://ci.appveyor.com/project/kbknapp/clap-rs/branch/master)

Command Line Argument Parser for Rust

It is a simple-to-use, efficient, and full-featured library for parsing command line arguments and subcommands when writing console/terminal applications.

## [documentation](https://docs.rs/clap/)
## [website](https://clap.rs/)
## [blog](https://blog.clap.rs/)

Table of Contents
=================

* [What's New](#whats-new)
* [About](#about)
* [FAQ](#faq)
* [Features](#features)
* [Quick Example](#quick-example)
* [Try it!](#try-it)
  * [Pre-Built Test](#pre-built-test)
  * [BYOB (Build Your Own Binary)](#byob-build-your-own-binary)
* [Usage](#usage)
  * [Optional Dependencies / Features](#optional-dependencies--features)
  * [Dependencies Tree](#dependencies-tree)
  * [More Information](#more-information)
    * [Video Tutorials](#video-tutorials)
* [How to Contribute](#how-to-contribute)
  * [Testing Code](#testing-code)
  * [Linting Code](#linting-code)
  * [Debugging Code](#debugging-code)
  * [Goals](#goals)
  * [Compatibility Policy](#compatibility-policy)
    * [Minimum Version of Rust](#minimum-version-of-rust)
* [License](#license)
* [Recent Breaking Changes](#recent-breaking-changes)
  * [Deprecations](#deprecations)

Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)

## What's New

Here's the highlights for v2.26.0

*   **The minimum required version of Rust is now 1.13.0 (Stable)**
*   bumps unicode-segmentation to v1.2 
*   update textwrap to version 0.7.0 which increases the performance of writing help strings


Here's the highlights for v2.21.0 to v2.25.1

* impl Default for Values + OsValues for any lifetime. 
* use textwrap crate for wrapping help texts
* suggests to use flag after subcommand when applicable
* Bumps bitflags crate to v0.9
* fixes a bug where args that allow values to start with a hyphen couldnt contain a double hyphen -- as a value
* fixes a bug where positional argument help text is misaligned
* **App::template docs:**  adds details about the necessity to use AppSettings::UnifiedHelpMessage when using {unified} tags in the help template
* **Arg::allow_hyphen_values docs:**  updates the docs to include warnings for allow_hyphen_values and multiple(true) used together
* **clap_app! docs:**  adds using the @group specifier to the macro docs
* adds a debug assertion to ensure all args added to groups actually exist
* fixes a bug where args with last(true) and required(true) set were not being printed in the usage string
* fixes a bug that was printing the arg name, instead of value name when Arg::last(true) was used
* fixes a bug where flags were parsed as flags AND positional values when specific combinations of settings were used
* **README.md:**  fix some typos
* **Arg:**  add `default_value_os`
* **arg_matches.rs:**  Added a Default implementation for Values and OsValues iterators.
* **PowerShell Completions:**
  * fixes a bug where powershells completions cant be used if no subcommands are defined
  * massively dedups subcommand names in the generate script to make smaller scripts that are still functionally equiv
* allows specifying a short help vs a long help (i.e. varying levels of detail depending on if -h or --help was used)
* **clap_app!:**  adds support for arg names with hyphens similar to longs with hyphens
* fixes a bug that wasn't allowing help and version to be properly overridden
  * This may break code that was relying on this bug! If you add a flag with a long of `help` manually *and* rely on the help message to be printed automatically your code could break. Please see the commit link in the full CHANGELOG.md
* `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`
* **clap_app!:**  documents the `--("some-arg")` method for using args with hyphens inside them
* fixes the usage string regression when using help templates
* fixes a big regression with custom usage strings
* adds the ability to change the name of the App instance after creation
* adds ability to hide the default value of an argument from the help string
* fixes support for loading author info from yaml
* adds fish subcommand help support
* options that use `require_equals(true)` now display the equals sign in help messages, usage strings, and errors
* setting the max term width now correctly propagates down through child subcommands
* fixes the precedence of this error to prioritize over other error messages
* fixes some regression bugs resulting from old asserts in debug mode.
* adds the ability to mark a positional argument as 'last' which means it should be used with `--` syntax and can be accessed early to effectivly skip other positional args
* Some performance improvements by reducing the ammount of duplicate work, cloning, and allocations in all cases.
* Some massive performance gains when using many args (i.e. things like shell glob expansions)
* 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)
* when `AppSettings::SubcommandsNegateReqs` and `ArgsNegateSubcommands` are used, a new more accurate double line usage string is shown
* provides `default_value_os` and `default_value_if[s]_os`
* provides `App::help_message` and `App::version_message` which allows one to override the auto-generated help/version flag associated help
* adds the ability to require the equals syntax with options `--opt=val`
* doesn't print the argument sections in the help message if all args in that section are hidden
* doesn't include the various `[ARGS]` `[FLAGS]` or `[OPTIONS]` if the only ones available are hidden
* now correctly shows subcommand as required in the usage string when AppSettings::SubcommandRequiredElseHelp is used
* fixes some "memory leaks" when an error is detected and clap exits
* fixes a trait that's marked private accidentlly, but should be crate internal public
* fixes a bug that tried to propogate global args multiple times when generating multiple completion scripts
* Fixes a critical bug in the `clap_app!` macro of a missing fragment specifier when using `!property` style tags.
* Fix examples link in CONTRIBUTING.md

For full details, see [CHANGELOG.md](https://github.com/kbknapp/clap-rs/blob/master/CHANGELOG.md)

## About

`clap` is used to parse *and validate* the string of command line arguments provided by the user at runtime. You provide the list of valid possibilities, and `clap` handles the rest. This means you focus on your *applications* functionality, and less on the parsing and validating of arguments.

`clap` also provides the traditional version and help switches (or flags) 'for free' meaning automatically with no configuration. It does this by checking list of valid possibilities you supplied and adding only the ones you haven't already defined. If you are using subcommands, `clap` will also auto-generate a `help` subcommand for you in addition to the traditional flags.

Once `clap` parses the user provided string of arguments, it returns the matches along with any applicable values. If the user made an error or typo, `clap` informs them of the mistake and exits gracefully (or returns a `Result` type and allows you to perform any clean up prior to exit). Because of this, you can make reasonable assumptions in your code about the validity of the arguments.

## FAQ

For a full FAQ and more in depth details, see [the wiki page](https://github.com/kbknapp/clap-rs/wiki/FAQ)

### Comparisons

First, let me say that these comparisons are highly subjective, and not meant in a critical or harsh manner. All the argument parsing libraries out there (to include `clap`) have their own strengths and weaknesses. Sometimes it just comes down to personal taste when all other factors are equal. When in doubt, try them all and pick one that you enjoy :) There's plenty of room in the Rust community for multiple implementations!

#### How does `clap` compare to [getopts](https://github.com/rust-lang-nursery/getopts)?

`getopts` is a very basic, fairly minimalist argument parsing library. This isn't a bad thing, sometimes you don't need tons of features, you just want to parse some simple arguments, and have some help text generated for you based on valid arguments you specify. The downside to this approach is that you must manually implement most of the common features (such as checking to display help messages, usage strings, etc.). If you want a highly custom argument parser, and don't mind writing the majority of the functionality yourself, `getopts` is an excellent base.

`getopts` also doesn't allocate much, or at all. This gives it a very small performance boost. Although, as you start implementing additional features, that boost quickly disappears.

Personally, I find many, many uses of `getopts` are manually implementing features that `clap` provides by default. Using `clap` simplifies your codebase allowing you to focus on your application, and not argument parsing.

#### How does `clap` compare to [docopt.rs](https://github.com/docopt/docopt.rs)?

I first want to say I'm a big a fan of BurntSushi's work, the creator of `Docopt.rs`. I aspire to produce the quality of libraries that this man does! When it comes to comparing these two libraries they are very different. `docopt` tasks you with writing a help message, and then it parsers that message for you to determine all valid arguments and their use. Some people LOVE this approach, others do not. If you're willing to write a detailed help message, it's nice that you can stick that in your program and have `docopt` do the rest. On the downside, it's far less flexible.

`docopt` is also excellent at translating arguments into Rust types automatically. There is even a syntax extension which will do all this for you, if you're willing to use a nightly compiler (use of a stable compiler requires you to somewhat manually translate from arguments to Rust types). To use BurntSushi's words, `docopt` is also a sort of black box. You get what you get, and it's hard to tweak implementation or customize the experience for your use case.

Because `docopt` is doing a ton of work to parse your help messages and determine what you were trying to communicate as valid arguments, it's also one of the more heavy weight parsers performance-wise. For most applications this isn't a concern and this isn't to say `docopt` is slow, in fact from it. This is just something to keep in mind while comparing.

#### All else being equal, what are some reasons to use `clap`?

`clap` is as fast, and as lightweight as possible while still giving all the features you'd expect from a modern argument parser. In fact, for the amount and type of features `clap` offers it remains about as fast as `getopts`. If you use `clap` when just need some simple arguments parsed, you'll find it's a walk in the park. `clap` also makes it possible to represent extremely complex, and advanced requirements, without too much thought. `clap` aims to be intuitive, easy to use, and fully capable for wide variety use cases and needs.

## Features
<commit_msg>Fix small typo in Readme<commit_after>clap
====

[![Crates.io](https://img.shields.io/crates/v/clap.svg)](https://crates.io/crates/clap) [![Crates.io](https://img.shields.io/crates/d/clap.svg)](https://crates.io/crates/clap) [![license](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kbknapp/clap-rs/blob/master/LICENSE-MIT) [![Coverage Status](https://coveralls.io/repos/kbknapp/clap-rs/badge.svg?branch=master&service=github)](https://coveralls.io/github/kbknapp/clap-rs?branch=master) [![Join the chat at https://gitter.im/kbknapp/clap-rs](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/kbknapp/clap-rs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Linux: [![Build Status](https://travis-ci.org/kbknapp/clap-rs.svg?branch=master)](https://travis-ci.org/kbknapp/clap-rs)
Windows: [![Build status](https://ci.appveyor.com/api/projects/status/ejg8c33dn31nhv36/branch/master?svg=true)](https://ci.appveyor.com/project/kbknapp/clap-rs/branch/master)

Command Line Argument Parser for Rust

It is a simple-to-use, efficient, and full-featured library for parsing command line arguments and subcommands when writing console/terminal applications.

## [documentation](https://docs.rs/clap/)
## [website](https://clap.rs/)
## [blog](https://blog.clap.rs/)

Table of Contents
=================

* [What's New](#whats-new)
* [About](#about)
* [FAQ](#faq)
* [Features](#features)
* [Quick Example](#quick-example)
* [Try it!](#try-it)
  * [Pre-Built Test](#pre-built-test)
  * [BYOB (Build Your Own Binary)](#byob-build-your-own-binary)
* [Usage](#usage)
  * [Optional Dependencies / Features](#optional-dependencies--features)
  * [Dependencies Tree](#dependencies-tree)
  * [More Information](#more-information)
    * [Video Tutorials](#video-tutorials)
* [How to Contribute](#how-to-contribute)
  * [Testing Code](#testing-code)
  * [Linting Code](#linting-code)
  * [Debugging Code](#debugging-code)
  * [Goals](#goals)
  * [Compatibility Policy](#compatibility-policy)
    * [Minimum Version of Rust](#minimum-version-of-rust)
* [License](#license)
* [Recent Breaking Changes](#recent-breaking-changes)
  * [Deprecations](#deprecations)

Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)

## What's New

Here's the highlights for v2.26.0

*   **The minimum required version of Rust is now 1.13.0 (Stable)**
*   bumps unicode-segmentation to v1.2 
*   update textwrap to version 0.7.0 which increases the performance of writing help strings


Here's the highlights for v2.21.0 to v2.25.1

* impl Default for Values + OsValues for any lifetime. 
* use textwrap crate for wrapping help texts
* suggests to use flag after subcommand when applicable
* Bumps bitflags crate to v0.9
* fixes a bug where args that allow values to start with a hyphen couldnt contain a double hyphen -- as a value
* fixes a bug where positional argument help text is misaligned
* **App::template docs:**  adds details about the necessity to use AppSettings::UnifiedHelpMessage when using {unified} tags in the help template
* **Arg::allow_hyphen_values docs:**  updates the docs to include warnings for allow_hyphen_values and multiple(true) used together
* **clap_app! docs:**  adds using the @group specifier to the macro docs
* adds a debug assertion to ensure all args added to groups actually exist
* fixes a bug where args with last(true) and required(true) set were not being printed in the usage string
* fixes a bug that was printing the arg name, instead of value name when Arg::last(true) was used
* fixes a bug where flags were parsed as flags AND positional values when specific combinations of settings were used
* **README.md:**  fix some typos
* **Arg:**  add `default_value_os`
* **arg_matches.rs:**  Added a Default implementation for Values and OsValues iterators.
* **PowerShell Completions:**
  * fixes a bug where powershells completions cant be used if no subcommands are defined
  * massively dedups subcommand names in the generate script to make smaller scripts that are still functionally equiv
* allows specifying a short help vs a long help (i.e. varying levels of detail depending on if -h or --help was used)
* **clap_app!:**  adds support for arg names with hyphens similar to longs with hyphens
* fixes a bug that wasn't allowing help and version to be properly overridden
  * This may break code that was relying on this bug! If you add a flag with a long of `help` manually *and* rely on the help message to be printed automatically your code could break. Please see the commit link in the full CHANGELOG.md
* `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`
* **clap_app!:**  documents the `--("some-arg")` method for using args with hyphens inside them
* fixes the usage string regression when using help templates
* fixes a big regression with custom usage strings
* adds the ability to change the name of the App instance after creation
* adds ability to hide the default value of an argument from the help string
* fixes support for loading author info from yaml
* adds fish subcommand help support
* options that use `require_equals(true)` now display the equals sign in help messages, usage strings, and errors
* setting the max term width now correctly propagates down through child subcommands
* fixes the precedence of this error to prioritize over other error messages
* fixes some regression bugs resulting from old asserts in debug mode.
* adds the ability to mark a positional argument as 'last' which means it should be used with `--` syntax and can be accessed early to effectivly skip other positional args
* Some performance improvements by reducing the ammount of duplicate work, cloning, and allocations in all cases.
* Some massive performance gains when using many args (i.e. things like shell glob expansions)
* 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)
* when `AppSettings::SubcommandsNegateReqs` and `ArgsNegateSubcommands` are used, a new more accurate double line usage string is shown
* provides `default_value_os` and `default_value_if[s]_os`
* provides `App::help_message` and `App::version_message` which allows one to override the auto-generated help/version flag associated help
* adds the ability to require the equals syntax with options `--opt=val`
* doesn't print the argument sections in the help message if all args in that section are hidden
* doesn't include the various `[ARGS]` `[FLAGS]` or `[OPTIONS]` if the only ones available are hidden
* now correctly shows subcommand as required in the usage string when AppSettings::SubcommandRequiredElseHelp is used
* fixes some "memory leaks" when an error is detected and clap exits
* fixes a trait that's marked private accidentlly, but should be crate internal public
* fixes a bug that tried to propogate global args multiple times when generating multiple completion scripts
* Fixes a critical bug in the `clap_app!` macro of a missing fragment specifier when using `!property` style tags.
* Fix examples link in CONTRIBUTING.md

For full details, see [CHANGELOG.md](https://github.com/kbknapp/clap-rs/blob/master/CHANGELOG.md)

## About

`clap` is used to parse *and validate* the string of command line arguments provided by the user at runtime. You provide the list of valid possibilities, and `clap` handles the rest. This means you focus on your *applications* functionality, and less on the parsing and validating of arguments.

`clap` also provides the traditional version and help switches (or flags) 'for free' meaning automatically with no configuration. It does this by checking list of valid possibilities you supplied and adding only the ones you haven't already defined. If you are using subcommands, `clap` will also auto-generate a `help` subcommand for you in addition to the traditional flags.

Once `clap` parses the user provided string of arguments, it returns the matches along with any applicable values. If the user made an error or typo, `clap` informs them of the mistake and exits gracefully (or returns a `Result` type and allows you to perform any clean up prior to exit). Because of this, you can make reasonable assumptions in your code about the validity of the arguments.

## FAQ

For a full FAQ and more in depth details, see [the wiki page](https://github.com/kbknapp/clap-rs/wiki/FAQ)

### Comparisons

First, let me say that these comparisons are highly subjective, and not meant in a critical or harsh manner. All the argument parsing libraries out there (to include `clap`) have their own strengths and weaknesses. Sometimes it just comes down to personal taste when all other factors are equal. When in doubt, try them all and pick one that you enjoy :) There's plenty of room in the Rust community for multiple implementations!

#### How does `clap` compare to [getopts](https://github.com/rust-lang-nursery/getopts)?

`getopts` is a very basic, fairly minimalist argument parsing library. This isn't a bad thing, sometimes you don't need tons of features, you just want to parse some simple arguments, and have some help text generated for you based on valid arguments you specify. The downside to this approach is that you must manually implement most of the common features (such as checking to display help messages, usage strings, etc.). If you want a highly custom argument parser, and don't mind writing the majority of the functionality yourself, `getopts` is an excellent base.

`getopts` also doesn't allocate much, or at all. This gives it a very small performance boost. Although, as you start implementing additional features, that boost quickly disappears.

Personally, I find many, many uses of `getopts` are manually implementing features that `clap` provides by default. Using `clap` simplifies your codebase allowing you to focus on your application, and not argument parsing.

#### How does `clap` compare to [docopt.rs](https://github.com/docopt/docopt.rs)?

I first want to say I'm a big a fan of BurntSushi's work, the creator of `Docopt.rs`. I aspire to produce the quality of libraries that this man does! When it comes to comparing these two libraries they are very different. `docopt` tasks you with writing a help message, and then it parsers that message for you to determine all valid arguments and their use. Some people LOVE this approach, others do not. If you're willing to write a detailed help message, it's nice that you can stick that in your program and have `docopt` do the rest. On the downside, it's far less flexible.

`docopt` is also excellent at translating arguments into Rust types automatically. There is even a syntax extension which will do all this for you, if you're willing to use a nightly compiler (use of a stable compiler requires you to somewhat manually translate from arguments to Rust types). To use BurntSushi's words, `docopt` is also a sort of black box. You get what you get, and it's hard to tweak implementation or customize the experience for your use case.

Because `docopt` is doing a ton of work to parse your help messages and determine what you were trying to communicate as valid arguments, it's also one of the more heavy weight parsers performance-wise. For most applications this isn't a concern and this isn't to say `docopt` is slow, in fact far from it. This is just something to keep in mind while comparing.

#### All else being equal, what are some reasons to use `clap`?

`clap` is as fast, and as lightweight as possible while still giving all the features you'd expect from a modern argument parser. In fact, for the amount and type of features `clap` offers it remains about as fast as `getopts`. If you use `clap` when just need some simple arguments parsed, you'll find it's a walk in the park. `clap` also makes it possible to represent extremely complex, and advanced requirements, without too much thought. `clap` aims to be intuitive, easy to use, and fully capable for wide variety use cases and needs.

## Features

{'fraction_non_alphanumeric': 0.08503471223760424, 'fraction_numerical': 0.002629092552273754, 'mean_word_length': 4.8378896882494, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 44, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3761132', 'n_tokens_mistral': 6792, 'n_tokens_neox': 6443, 'n_words': 3211}