2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-12-24 03:23:09 +00:00
Commit graph

179 commits

Author SHA1 Message Date
Kevin K
fc3e0f5afd feat(Settings): adds new setting to stop delimiting values with -- or TrailingVarArg
One can now use `AppSettings::DontDelimitTrailingValues` to stop clap's default behavior of
delimiting values, even when `--` or `TrailingVarArg` is used. This is useful when passing other
flags and commands through to another program.

Closes 
2016-06-07 23:49:05 -04:00
Kevin K
7db45f78d8 chore: removes extra debug statements 2016-06-07 23:49:05 -04:00
Kevin K
706a7c11b0 fix(Settings): fixes bug where new color settings couldn't be converted from strs 2016-06-07 23:49:05 -04:00
Kevin K
ec86f2dada imp(Usage Strings): improves the default usage string when only a single positional arg is present
Instead of blindly printing `[ARGS]` when only a single positional arg is present, it will now
print `[NAME]` (or `[NAME]...` for multiple values allowed)

Closes 
2016-06-04 11:55:47 -04:00
Kevin K
e23418351a feat(Settings): one can now set an AppSetting which is propogated down through child subcommands
Closes 
2016-06-04 11:55:47 -04:00
Kevin K
cd44080650 fix: fixes bug where args are printed out of order with templates 2016-06-04 11:55:47 -04:00
Kevin K
8f630c6a07 fix: fixes bug where one can't override version or help flags
Closes 
2016-06-04 11:55:47 -04:00
Kevin K
330e5edf04 fix: fixes issue where before_help wasn't printed 2016-06-04 11:55:47 -04:00
Kevin K
054f8cb433 imp: removes extra newline from help output 2016-06-04 11:55:47 -04:00
Kevin K
c5b24c0eb0 tests: removes extra newline from version output tests 2016-06-04 11:28:24 -04:00
Kevin K
a7401dc6a1 imp: allows printing version to any io::Write object 2016-06-04 11:28:24 -04:00
Kevin K
cda27469cd imp: removes extra newline when printing version 2016-06-04 11:28:24 -04:00
Kevin K
65c2350aa3 feat: colors dont get sent to pipes by default
Color are now only used when outputting to a termainal/TTY. There are three new settings as well
which can be used to control color output, they are:

 * `AppSettings::ColorAuto`: The default, and will only output color when outputting to a terminal or TTY
 * `AppSettings::ColorAlways`: Outputs color no matter where the output is going
 * `AppSettings::ColorNever`: Never colors output

This now allows one to use things like command line options, or environmental variables to turn
colored output on/off.

Closes 
2016-06-04 11:28:03 -04:00
Kevin K
3312893dda docs: inter-links all types and pages
All doc pages should now be inter-linked between other doc pages and
Rust documentation.

Closes 
2016-05-15 14:23:37 -04:00
Hendrik Sollich
ac42f6cf0d Fix: SubCommand::aliases lifetime errors 2016-05-11 21:08:25 +02:00
Hendrik Sollich
6ba910e89b test: adds failing doc test 2016-05-11 20:16:56 +02:00
Kevin K
41a482cf5d imp(SubCommand Aliases): adds feature to yaml configs too 2016-05-10 17:15:06 -04:00
Kevin K
66b4dea65c feat(SubCommands): adds support for subcommand aliases
Allows adding a subcommand alias, which function as "hidden" subcommands that automatically
dispatch as if this subcommand was used. This is more efficient, and easier than creating
multiple hidden subcommands as one only needs to check for the existing of this command,
and not all vairants.

Example:

```
let m = App::new("myprog")
            .subcommand(SubCommand::with_name("test")
                .alias("do-stuff"))
            .get_matches_from(vec!["myprog", "do-stuff"]);
assert_eq!(m.subcommand_name(), Some("test"));
```

Example using multiple aliases:

```
let m = App::new("myprog")
            .subcommand(SubCommand::with_name("test")
                .aliases(&["do-stuff", "do-tests", "tests"]))
            .get_matches_from(vec!["myprog", "do-tests"]);
assert_eq!(m.subcommand_name(), Some("test"));
```

Closes 
2016-05-10 15:21:19 -04:00
Kevin K
3ca0947c16 fix(Usage Strings): now properly dedups args that are also in groups
For example, if an arg is part of a required group, it will only appear
in the group usage string, and not in both the group as well as the arg
by itself.

Imagine a group containing two args, `arg1` and `--arg2`

OLD:
    `myprog <arg1> <arg1|--arg2>`

NEW:
    `myprog <arg1|--arg2>`

Closes 
2016-05-09 19:14:11 -04:00
Kevin K
f574fb8a7c fix(Usage Strings): removes duplicate groups from usage strings 2016-05-09 19:14:11 -04:00
Kevin K
852e58156c tests: removes old python tests and replaces with rust tests
Closes 
2016-05-09 19:14:11 -04:00
Kevin K
fef11154fb imp(Groups): formats positional args in groups in a better way 2016-05-08 21:33:27 -04:00
Kevin K
2efd81ebbc chore: clippy update and run 2016-05-06 17:59:52 -04:00
Kevin K
ffde90f2ba style: rustfmt run 2016-05-06 17:52:23 -04:00
Kevin K
5b7fe8e416 imp(Help): default help subcommand string has been shortened
Closes 
2016-05-05 21:49:51 -04:00
Kevin K
5b0120088a fix(Required Args): fixes issue where missing required args are sometimes duplicatd in error messages
Closes 
2016-05-03 16:31:55 -04:00
Kevin K
d8e4dbc961 feat(Help): adds support for displaying info before help message
Can now use the `App::before_help` method to add additional information
that will be displayed prior to the help message. Common uses are
copyright, or license information.
2016-05-03 16:31:55 -04:00
Kevin K
6987f37e71 feat(Required): adds allowing args that are required unless certain args are present
Adds three new methods of `Arg` which allow for specifying three new
types of rules.

* `Arg::required_unless`

Allows saying a particular arg is only required if a specific other arg
*isn't* present.

* `Arg::required_unless_all`

Allows saying a particular arg is only required so long as *all* the
following args aren't present

* `Arg::required_unless_one`

Allows saying a particular arg is required unless at least one of the
following args is present.
2016-05-03 16:31:54 -04:00
Kevin K
4fe133d9ce chore: removes unused imports 2016-05-02 18:04:10 -04:00
Kevin K
770397bcb2 feat(HELP): implements optional colored help messages
To enable, ensure `clap` is compiled with `color` cargo feature.

Then in code use `AppSettings::ColoredHelp`

Closes 
2016-04-18 00:05:43 -07:00
Homu
fdbd12e830 Auto merge of - hgrecco:template, r=kbknapp
A new Help Engine with templating capabilities

This set of commits brings a new Help System to CLAP.

Major changes are:
- The help format is (almost) completely defined in `help.rs` instead of being scattered across multiple files.
- The HELP object contains a writer and its methods accept AnyArgs, not the other way around.
- A template option allows the user to change completely the organization of the autogenerated help.
2016-04-18 08:12:39 +09:00
Hernan Grecco
627ae38dc0 refactor(HELP): Removed code for old help system and tests that helped with the transitions 2016-04-13 07:21:21 -03:00
Hernan Grecco
8d23806bd6 fix(HELP): Adjust Help to semantic changes introduced in 6933b84 2016-04-13 07:06:23 -03:00
Hernan Grecco
81e121edd6 feat(HELP): Add a Templated Help system.
The strategy is to copy the template from the the reader to wrapped stream
until a tag is found. Depending on its value, the appropriate content is copied
to the wrapped stream.
The copy from template is then resumed, repeating this sequence until reading
the complete template.

Tags arg given inside curly brackets:
Valid tags are:
    * `{bin}`         - Binary name.
    * `{version}`     - Version number.
    * `{author}`      - Author information.
    * `{usage}`       - Automatically generated or given usage string.
    * `{all-args}`    - Help for all arguments (options, flags, positionals arguments,
                        and subcommands) including titles.
    * `{unified}`     - Unified help for options and flags.
    * `{flags}`       - Help for flags.
    * `{options}`     - Help for options.
    * `{positionals}` - Help for positionals arguments.
    * `{subcommands}` - Help for subcommands.
    * `{after-help}`  - Help for flags.
2016-04-13 07:06:23 -03:00
Hernan Grecco
04b5b074d1 refactor(HELP): A new Help Engine
The largest organizational change is that methods used to generate the help are
implemented by the Help object and not the App, FlagBuilder, Parser, etc.

The new code is based heavily on the old one with a few minor modifications
aimed to reduce code duplication and coupling between the Help and the rest
of the code.

The new code turn things around: instead of having a HelpWriter that holds an
AnyArg object and a method that is called with a writer as argument,
there is a Help Object that holds a writer and a method that is called with a
writer as an argument.

There are still things to do such as moving `create_usage` outside the Parser.

The peformance has been affected, probably by the use of Trait Objects. This
was done as a way to reduce code duplication (i.e. in the unified help code).
This performance hit should not affect the usability as generating and printing
the help is dominated by user interaction and IO.

The old code to generate the help is still functional and is the active one.
The new code has been tested against the old one by generating help strings
for most of the examples in the repo.
2016-04-13 07:06:23 -03:00
Hernan Grecco
a91d378ba0 imp(parser.rs): Provide a way to create a usage string without the USAGE: title 2016-04-13 07:06:22 -03:00
Hernan Grecco
65b3f66753 imp(srs/args): Added longest_filter to AnyArg trait
This function allows providing an extra filter to remove elements when finding
the longest element.
2016-04-13 07:06:22 -03:00
Hernan Grecco
d51945f8b8 imp(parser.rs): Make Parser's create_usage public allowing to have function outside the parser to generate the help 2016-04-13 07:06:22 -03:00
Hernan Grecco
9b23e7ee40 imp(parser.rs): Expose Parser's flags, opts and positionals argument as iterators
Writing the help requires read only access to Parser's flags, opts
and positionals. This commit provides 3 functions returning iterators
over those collections (`iter_*`) allowing to have function outside
the parser to generate the help.
2016-04-13 07:06:22 -03:00
Roman A. Taycher
38fb59abf4 feat(Authors Macro): adds a crate_authors macro
Adds a crate_authors! macro that fetches
crate authors from a (recently added)
cargo enviromental variable populated
from the Cargo file. Like the
crate_version macro.

Closes 
2016-04-11 16:17:44 -07:00
panicbit
3019a685ee Fix off-by-one-error in ArgGroup printing 2016-04-10 02:46:51 +02:00
Kevin K
885d166f04 fix(Empty Values): fixes bug where empty values weren't stored
Passing empty values, such as `--feature ""` now stores the empty string
correctly as a value (assuming empty values are allowed as per the arg
configuration)

Closes 
2016-03-29 22:25:13 -04:00
Kevin K
205b07bf2e fix(Help Subcommand): fixes issue where help and version flags weren't properly displayed
Closes 
2016-03-28 11:26:56 -04:00
Kevin K
6933b8491c fix(Usage Strings): fixes small bug where -- would appear needlessly in usage strings
Closes 
2016-03-27 14:22:51 -04:00
Kevin K
144e7e29d6 chore: clippy run 2016-03-22 21:16:53 -04:00
Kevin K
813d75d06f feat(Help Message): wraps and aligns the help message of subcommands
Subcommand's help strings are now automatically wrapped and aligned just
like other arguments.

Closes 
2016-03-16 10:17:00 -04:00
Kevin K
2c12757bbd feat(Help Subcommand): adds support passing additional subcommands to help subcommand
The `help` subcommand can now accept other subcommands as arguments to
display their help message. This is similar to how many other CLIs
already perform. For example:

```
$ myprog help mysubcmd
```

Would print the help message for `mysubcmd`. But even more, the `help`
subcommand accepts nested subcommands as well, i.e. a grandchild
subcommand such as

```
$ myprog help child grandchild
```

Would print the help message of `grandchild` where `grandchild` is a
subcommand of `child` and `child` is a subcommand of `myprog`.

Closes 
2016-03-14 22:41:47 -04:00
Kevin K
675c39f8ba tests: moves app settings tests to the proper place 2016-03-13 22:07:28 -04:00
Kevin K
e428bb6d84 tests: moves some \t tabs to four spaces for consistency 2016-03-13 22:07:28 -04:00
Kevin K
e36af02666 feat(Help Message): can auto wrap and aligning help text to term width
By default `clap` now automatically wraps and aligns help strings to the
term width. i.e.

```
    -o, --option <opt>    some really long help
text that should be auto aligned but isn't righ
t now
```

Now looks like this:

```
    -o, --option <opt>    some really long help
                          text that should be
                          auto aligned but isn't
                          right now
```

The wrapping also respects words, and wraps at spaces so as to not cut
words in the middle.

This requires the `libc` dep which is enabled (by default) with the
`wrap_help` cargo feature flag.

Closes 
2016-03-13 22:07:28 -04:00