-
-
Notifications
You must be signed in to change notification settings - Fork 1k
/
CHANGELOG.md
4132 lines (2360 loc) · 202 KB
/
CHANGELOG.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Change Log
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).
## 5.0.0 - 2022-11-24
### Breaking Changes
- Made `ArgPredicate` `non_exhaustive`
<!-- next-header -->
## [Unreleased] - ReleaseDate
## [4.0.29] - 2022-11-29
## [4.0.28] - 2022-11-29
### Fixes
- Fix wasm support which was broken in 4.0.27
## [4.0.27] - 2022-11-24
### Features
- Have `Arg::value_parser` accept `Vec<impl Into<PossibleValue>>`
- Implement `Display` and `FromStr` for `ColorChoice`
### Fixes
- Remove soundness issue by switching from `atty` to `is-terminal`
## [4.0.26] - 2022-11-16
### Fixes
- *(error)* Fix typos in `ContextKind::as_str`
## [4.0.25] - 2022-11-15
### Features
- *(error)* Report available subcommands when required subcommand is missing
## [4.0.24] - 2022-11-14
### Fixes
- Avoid panic when printing an argument that isn't built
## [4.0.23] - 2022-11-11
### Fixes
- Don't panic on reporting invalid-long errors when followed by invalid UTF8
- *(help)* Clarified argument to `help` subcommand
## [4.0.22] - 2022-11-07
### Fixes
- *(help)* Don't overflow into next-line-help early due to stale (pre-v4) padding calculations
## [4.0.21] - 2022-11-07
### Features
- *(derive)* `long_about` and `long_help` attributes, without a value, force using doc comment (before it wouldn't be set if there wasn't anything different than the short help)
## [4.0.20] - 2022-11-07
### Fixes
- *(derive)* Allow defaulted value parser for '()' fields
## [4.0.19] - 2022-11-04
### Features
- `ColorChoice` now implements `ValueEnum`
## [4.0.18] - 2022-10-20
### Fixes
- *(derive)* Allow `#[command(skip)]` to also work with enum variants with a value
## [4.0.17] - 2022-10-18
### Fixes
- Allow using `Arg::last(true)` with `Arg::value_hint(ValueHint::CommandWithArguments)`
## [4.0.16] - 2022-10-18
### Fixes
- `Arg::exclusive(true)` should not be exclusive with the argument's own `ArgGroup`
## [4.0.15] - 2022-10-13
### Fixes
- *(error)* Don't suggest `--` when it doesn't help
- *(error)* Be more consistent in quoting, punctuation, and indentation in errors
## [4.0.14] - 2022-10-12
### Fixes
- Only put `ArgGroup` in `ArgMatches` when explicitly specified, fixing derives handling of option-flattened fields (#4375)
## [4.0.13] - 2022-10-11
### Features
- *(derive)* Allow `()` for fields to mean "don't read" (#4371)
## [4.0.12] - 2022-10-10
### Features
- Added `TypedValueParser::try_map` for when adapting an existing `TypedValueParser` can fail
- *(error)* Create errors like clap with `Error::new`, `Error::with_cmd`, and `Error::insert`
## [4.0.11] - 2022-10-09
### Fixes
- *(help)* Fix wrapping calculations with ANSI escape codes
## [4.0.10] - 2022-10-05
### Features
- *(derive)* Support `#[arg(flatten)]` on `Option` types (#4211, #4350)
## [4.0.9] - 2022-10-03
### Fixes
- *(derive)* Process doc comments for `#[command(subcommand)]` like in clap v3
## [4.0.8] - 2022-10-01
### Fixes
- *(derive)* Remove a low-value assert preventing defaulting `Help` and `Version` actions
## [4.0.7] - 2022-09-30
### Features
- *(derive)* Populate implicit ArgGroup (#3165)
### Fixes
- *(derive)* Support `#[group(skip)]` on `Parser` derive
- *(derive)* Tell users about implicit arg groups when running into group name conflicts
- *(error)* Don't report unrelated groups in conflict or requires errors
## [4.0.6] - 2022-09-30
### Features
- *(derive)* Support `#[group(skip)]` (#4279, #4301)
## [4.0.5] - 2022-09-30
## [4.0.4] - 2022-09-29
### Fixes
- *(error)* Specialize the self-conflict error to look like clap v3
## [4.0.3] - 2022-09-29
### Fixes
- *(error)* Quote literals consistently
- *(error)* Stylize escape (`--`) suggestions
- *(error)* Format help flag as a literal
## [4.0.2] - 2022-09-28
### Fixes
- *(parser)* `SetFalse` should conflict with itself like `SetTrue` and `Set`
- *(parser)* Allow one-off overrides
## [4.0.1] - 2022-09-28
### Fixes
- *(derive)* Ensure `#[clap(...)]` attribute still works
## [4.0.0] - 2022-09-28
### Highlights
**`Arg::num_args(range)`**
Clap has had several ways for controlling how many values will be captured without always being clear on how they interacted, including
- `Arg::multiple_values(true)`
- `Arg::number_of_values(4)`
- `Arg::min_values(2)`
- `Arg::max_values(20)`
- `Arg::takes_value(true)`
These have now all been collapsed into `Arg::num_args` which accepts both
single values and ranges of values. `num_args` controls how many raw arguments
on the command line will be captured as values per occurrence and independent
of value delimiters.
See [Issue 2688](https://github.com/clap-rs/clap/issues/2688) for more background.
**Polishing Help**
Clap strives to give a polished CLI experience out of the box with little
ceremony. With some feedback that has accumulated over time, we took this
release as an opportunity to re-evaluate our `--help` output to make sure it is
meeting that goal.
In doing this evaluation, we wanted to keep in mind:
- Whether other CLIs had ideas that make sense to apply
- Providing an experience that fits within the rest of applications and works across all shells
Before:
```
git
A fictional versioning CLI
USAGE:
git <SUBCOMMAND>
OPTIONS:
-h, --help Print help information
SUBCOMMANDS:
add adds things
clone Clones repos
help Print this message or the help of the given subcommand(s)
push pushes things
stash
```
After:
```
A fictional versioning CLI
Usage: git <COMMAND>
Commands:
clone Clones repos
push pushes things
add adds things
stash
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help information
```
- name/version header was removed because we couldn't justify the space it occupied when
- Usage already includes the name
- `--version` is available for showing the same thing (if the program has a version set)
- Usage was dropped to one line to save space
- Focus is put on the subcommands
- Headings are now Title case
- The more general term "command" is used rather than being explicit about being "subcommands"
- The output is more dense with the expectation that it won't affect legibility but will allow more content
- We've moved to a more neutral palette for highlighting elements (not highlighted above)
In talking to users, we found some that liked clap's `man`-like experience.
When deviating from this, we are making the assumption that those are more
power users and that the majority of users wouldn't look as favorably on being
consistent with `man`.
See [Issue 4132](https://github.com/clap-rs/clap/issues/4132) for more background.
**More Dynamicism**
Clap's API has focused on `&str` for performance but this can make
dealing with owned data difficult, like `#[arg(default_value_t)]` generating a
String from the default value.
Additionally, to avoid `ArgMatches` from borrowing (and for some features we
decided to forgo), clap took the `&str` argument IDs and hashed them. This
prevented us from providing a usable API for iterating over existing arguments.
Now clap has switched to a string newtype that gives us the flexibility to
decide whether to use `&'static str`, `Cow<'static, str>` for fast dynamic behavior, or
`Box<str>` for dynamic behavior with small binary size.
As an extension of that work, you can now call `ArgMatches::ids` to iterate
over the arguments and groups that were found when parsing. The newtype `Id`
was used to prevent some classes of bugs and to make it easier to understand
when opaque Ids are used vs user-visible strings.
**Clearing Out Deprecations**
Instead of doing all development on clap 4.0.0, we implemented a lot of new features during clap 3's development, deprecating the old API while introducing the new API, including:
- Replacing the implicit behavior for args when parsing them with `ArgAction`
- Replacing various one-off forms of value validation with the `ValueParser` API
- Allowing derives to automatically do the right thing for `PathBuf` (allowing invalid UTF-8)
- Replacing `AppSettings` and `ArgSettings` enums with getters/setters
- Clarifying terms and making them more consistent
### Migrating
Steps:
0. [Upgrade to v3](https://github.com/clap-rs/clap/blob/v3-master/CHANGELOG.md#migrating) if you haven't already
1. Add CLI tests (including example below), `-h` and `--help` output at a minimum (recommendation: [trycmd](https://docs.rs/trycmd/) for snapshot testing)
2. *If using Builder API*: Explicitly set the `arg.action(ArgAction::...)` on each argument (`StoreValue` for options and `IncOccurrences` for flags)
3. Run `cargo check --features clap/deprecated` and resolve all deprecation warnings
4. Upgrade to v4
5. Update feature flags
- *If `default-features = false`*, run `cargo add clap -F help,usage,error-context`
- Run `cargo add clap -F wrap_help` unless you want to hard code line wraps
6. Resolve compiler errors
7. Resolve behavior changes (see "subtle changes" under BREAKING CHANGES)
8. *At your leisure:* resolve new deprecation notices
Example test (derive):
```rust
#[derive(clap::Parser)]
struct Cli {
...
}
#[test]
fn verify_cli() {
use clap::CommandFactory;
Cli::command().debug_assert()
}
```
Example test (builder):
```rust
fn cli() -> clap::Command {
...
}
#[test]
fn verify_cli() {
cli().debug_assert();
}
```
Note: the idiomatic / recommended way of specifying different types of args in the Builder API has changed:
Before
```rust
.arg(Arg::new("flag").long("flag")) # --flag
.arg(Arg::new("option").long("option").takes_value(true)) # --option <option>
```
After:
```rust
.arg(Arg::new("flag").long("flag").action(ArgAction::SetTrue)) # --flag
.arg(Arg::new("option").long("option")) # --option <option>
```
In particular, `num_args` (the replacement for `takes_value`) will default appropriately
from the `ArgAction` and generally only needs to be set explicitly for the
other `num_args` use cases.
### Breaking Changes
Subtle changes (i.e. compiler won't catch):
- `arg!` now sets one of (#3795):
- `ArgAction::SetTrue`, requiring `ArgMatches::get_flag` instead of `ArgMatches::is_present`
- `ArgAction::Count`, requiring `ArgMatches::get_count` instead of `ArgMatches::occurrences_of`
- `ArgAction::Set`, requiring `ArgMatches::get_one` instead of `ArgMatches::value_of`
- `ArgAction::Append`, requiring `ArgMatches::get_many` instead of `ArgMatches::values_of`
- `ArgAction::Set`, `ArgAction::SetTrue`, and `Arg::Action::SetFalse` now
conflict by default to be like `ArgAction::StoreValue` and
`ArgAction::IncOccurrences`, requiring `cmd.args_override_self(true)` to override instead (#4261)
- By default, an `Arg`s default action is `ArgAction::Set`, rather than `ArgAction::IncOccurrence` to reduce confusing magic through consistency (#2687, #4032, see also #3977)
- `mut_arg` can no longer be used to customize help and version arguments, instead disable them (`Command::disable_help_flag`, `Command::disable_version_flag`) and provide your own (#4056)
- Removed lifetimes from `Command`, `Arg`, `ArgGroup`, and `PossibleValue`, assuming `'static`. `string` feature flag will enable support for `String`s (#1041, #2150, #4223)
- `arg!(--flag <value>)` is now optional, instead of required. Add `.required(true)` at the end to restore the original behavior (#4206)
- Added default feature flags, `help`, `usage` and `error-context`, requiring adding them back in if `default-features = false` (#4236)
- *(parser)* Always fill in `""` argument for external subcommands to make it easier to distinguish them from built-in commands (#3263)
- *(parser)* Short flags now have higher precedence than hyphen values with `Arg::allow_hyphen_values`, to be consistent with `Command::allow_hyphen_values` (#4187)
- *(parser)* `Arg::value_terminator` must be its own argument on the CLI rather than being in a delimited list (#4025)
- *(help)* Line wrapping of help is now behind the existing `wrap_help` feature flag, either enable it or hard code your wraps (#4258)
- *(help)* Make `DeriveDisplayOrder` the default and removed the setting. To sort help, set `next_display_order(None)` (#2808)
- *(help)* Subcommand display order respects `Command::next_display_order` instead of `DeriveDisplayOrder` and using its own initial display order value (#2808)
- *(help)* Subcommands are now listed before arguments. To get the old behavior, see `Command::help_template` (#4132)
- *(help)* Help headings are now title cased, making any user-provided help headings inconsistent. To get the old behavior, see `Command::help_template`, `Arg::help_heading`, and `Command::subcommand_help_heading` (#4132)
- *(help)* "Command" is used as the section heading for subcommands and `COMMAND` for the value name. To get the old behavior, see `Command::subcommand_help_heading` and `Arg::subcommand_value_name` (#4132, #4155)
- *(help)* Whitespace in help output is now trimmed to ensure consistency regardless of how well a template matches the users needs. (#4132, #4156)
- *(help)* name/version/author are removed by default from help output. To get the old behavior, see `Command::help_template`. (#4132, #4160)
- *(help)* Indentation for second-line usage changed. (#4132, #4188)
- *(env)* Parse `--help` and `--version` like any `ArgAction::SetTrue` flag (#3776)
- *(derive)* Leave `Arg::id` as `verbatim` casing, requiring updating of string references to other args like in `conflicts_with` or `requires` (#3282)
- *(derive)* Doc comments for `ValueEnum` variants will now show up in `--help` (#3312)
- *(derive)* When deriving `Args`, and `ArgGroup` is created using the type's name, reserving it for future use (#2621, #4209)
- *(derive)* `next_help_heading` can now leak out of a `#[clap(flatten)]`, like all other command settings (#4222)
Easier to catch changes:
- Looking up a group in `ArgMatches` now returns the arg `Id`s, rather than the values to reduce overhead and offer more flexibility. (#4072)
- Changed `Arg::number_of_values` (average-across-occurrences) to `Arg::num_args` (per-occurrence) (raw CLI args, not parsed values) (#2688, #4023)
- `num_args(0)` no longer implies `takes_value(true).multiple_values(true)` (#4023)
- `num_args(1)` no longer implies `multiple_values(true)` (#4023)
- Does not check default or env values, only what the user explicitly passes in (#4025)
- No longer terminates on delimited values (#4025)
- Replace `Arg::min_values` (across all occurrences) with `Arg::num_args(N..)` (per occurrence) to reduce confusion over different value count APIs (#4023)
- Replace `Arg::max_values` (across all occurrences) with `Arg::num_args(1..=M)` (per occurrence) to reduce confusion over different value count APIs (#4023)
- Replace `Arg::multiple_values(true)` with `Arg::num_args(1..)` and `Arg::multiple_values(false)` with `Arg::num_args(0)` to reduce confusion over different value count APIs (#4023)
- Replace `Arg::takes_value(true)` with `Arg::num_args(1)` and `Arg::takes_value(false)` with `Arg::num_args(0)` to reduce confusion over different value count APIs
- Remove `Arg::require_value_delimiter`, either users could use `Arg::value_delimiter` or implement a custom parser with `TypedValueParser` as it was mostly to make `multiple_values(true)` act like `multiple_values(false)` and isn't needed anymore (#4026)
- `Arg::new("help")` and `Arg::new("version")` no longer implicitly disable the
built-in flags and be copied to all subcommands, instead disable
the built-in flags (`Command::disable_help_flag`,
`Command::disable_version_flag`) and mark the custom flags as `global(true)`. (#4056)
- `Arg::short('h')` no longer implicitly disables the short flag for help,
instead disable
the built-in flags (`Command::disable_help_flag`,
`Command::disable_version_flag`) provide your own `Arg::new("help").long("help").action(ArgAction::Help).global(true)`. (#4056)
- `ArgAction::SetTrue` and `ArgAction::SetFalse` now prioritize `Arg::default_missing_value` over their standard behavior (#4000)
- Changed `Arg::requires_ifs` and `Arg::default_value*_ifs*` to taking an `ArgPredicate`, removing ambiguity with `None` when accepting owned and borrowed types (#4084)
- Removed `PartialEq` and `Eq` from `Command` so we could change external subcommands to use a `ValueParser` (#3990)
- Various `Arg`, `Command`, and `ArgGroup` calls were switched from accepting `&[]` to `[]` via `IntoIterator` to be more flexible (#4072)
- `Arg::short_aliases` and other builder functions that took `&[]` need the `&` dropped (#4081)
- `ErrorKind` and `Result` moved into the `error` module
- `ErrorKind::EmptyValue` replaced with `ErrorKind::InvalidValue` to remove an unnecessary special case (#3676, #3968)
- `ErrorKind::UnrecognizedSubcommand` replaced with `ErrorKind::InvalidSubcommand` to remove an unnecessary special case (#3676)
- Changed the default type of `allow_external_subcommands` from `String` to `OsString` as that is less likely to cause bugs in user applications (#3990)
- *(help)* `Command::render_usage` now returns a `StyledStr` (#4248)
- *(derive)* Changed the default for arguments from `parse` to `value_parser`, removing `parse` support (#3827, #3981)
- `#[clap(value_parser)]` and `#[clap(action)]` are now redundant
- *(derive)* `subcommand_required(true).arg_required_else_help(true)` is set instead of `SubcommandRequiredElseHelp` to give more meaningful errors when subcommands are missing and to reduce redundancy (#3280)
- *(derive)* Remove `arg_enum` attribute in favor of `value_enum` to match the new name (we didn't have support in v3 to mark it deprecated) (#4127)
- *(parser)* Assert when the CLI looksup an unknown args when external subcommand support is enabled to help catch bugs (#3703)
- *(assert)* Sometimes `Arg::default_missing_value` didn't require `num_args(0..=N)`, now it does (#4023)
- *(assert)* Leading dashes in `Arg::long` are no longer allowed (#3691)
- *(assert)* Disallow more `value_names` than `num_args` (#2695)
- *(assert)* Always enforce that version is specified when the `ArgAction::Version` is used
- *(assert)* Add missing `#[track_caller]`s to make it easier to debug asserts
- *(assert)* Ensure `overrides_with` IDs are valid
- *(assert)* Ensure no self-`overrides_with` now that Actions replace it
- *(assert)* Ensure subcommand names are not duplicated
- *(assert)* Assert on `mut_arg` receiving an invalid arg ID or `mut_subcommand` receiving an invalid command name
### Compatibility
MSRV is now 1.60.0
Deprecated
- `Arg::use_value_delimiter` in favor of `Arg::value_delimiter` to avoid having multiple ways of doing the same thing
- `Arg::requires_all` in favor of `Arg::requires_ifs` now that it takes an `ArgPredicate` to avoid having multiple ways of doing the same thing
- `Arg::number_of_values` in favor of `Arg::num_args` to clarify semantic differences
- `default_value_os`, `default_values_os`, `default_value_if_os`, and `default_value_ifs_os` as the non `_os` variants now accept either a `str` or an `OsStr` (#4141)
- `Arg::env_os` in favor of `Arg::env`
- `Command::dont_collapse_args_in_usage` is now the default (#4151)
- `Command::trailing_var_arg` in favor of `Arg::trailing_var_arg` to make it clearer which arg it is meant to apply to (#4187)
- `Command::allow_hyphen_values` in favor of `Arg::allow_hyphen_values` to make it clearer which arg it is meant to apply to (#4187)
- `Command::allow_negative_numbers` in favor of `Arg::allow_negative_numbers` to make it clearer which arg it is meant to apply to (#4187)
- *(help)* Deprecated `Command::write_help` and `Command::write_long_help` in favor of `Command::render_help` and `Command::render_long_help` (#4248)
- *(derive)* `structopt` and `clap` attributes in favor of the more specific `command`, `arg`, and `value` to open the door for [more features](https://github.com/clap-rs/clap/issues/1807) and [clarify relationship to the builder](https://github.com/clap-rs/clap/discussions/4090) (#1807, #4180)
- *(derive)* `#[clap(value_parser)]` and `#[clap(action)]` defaulted attributes (its the default) (#3976)
Behavior Changes
- *(help)* With `wrap_help` feature, if the terminal size cannot be determined, `LINES` and `COLUMNS` variables are used (#4186)
### Features
- `Arg::num_args` now accepts ranges, allowing setting both the minimum and maximum number of values per occurrence (#2688, #4023)
- Allow non-bool `value_parser`s for `ArgAction::SetTrue` / `ArgAction::SetFalse` (#4092)
- Add `From<&OsStr>`, `From<OsString>`, `From<&str>`, and `From<String>` to `value_parser!` (#4257)
- Allow resetting most builder methods
- Can now pass runtime generated data to `Command`, `Arg`, `ArgGroup`, `PossibleValue`, etc without managing lifetimes with the `string` feature flag (#2150, #4223)
- New default `error-context`, `help` and `usage` feature flags that can be turned off for smaller binaries (#4236)
- Added `StyledStr::ansi()` to `Display` with ANSI escape codes (#4248)
- *(error)* `Error::apply` for changing the formatter for dropping binary size (#4111)
- *(error)* `Error::render`for formatting the error into a `StyledStr`
- *(help)* Show `PossibleValue::help` in long help (`--help`) (#3312)
- *(help)* New `{tab}` variable for `Command::help_template` (#4161)
- *(help)* `Command::render_help` and `Command::render_long_help` for formatting the error into a `StyledStr` (#3873, #4248)
- *(help)* `Command::render_usage` now returns a `StyledStr` (#4248)
### Fixes
- Verify `required` is not used with conditional required settings (#3660)
- Replaced `cmd.allow_invalid_for_utf8_external_subcommands` with `cmd.external_subcommand_value_parser` (#3733)
- `Arg::default_missing_value` now applies per occurrence rather than if a value is missing across all occurrences (#3998)
- `arg!(--long [value])` to accept `0..=1` per occurrence rather than across all occurrences, making it safe to use with `ArgAction::Append` (#4001)
- Allow `OsStr`s for `Arg::{required_if_eq,required_if_eq_any,required_if_eq_all}` (#4084)
- *(help)* With `wrap_help` feature, if the terminal size cannot be determined, `LINES` and `COLUMNS` variables are used (#4186)
- *(help)* Use `Command::display_name` in the help title rather than `Command::bin_name`
- *(help)* Show when a flag is `ArgAction::Count` by adding an `...` (#4003)
- *(help)* Use a more neutral palette for coloring (#4132, #4117)
- *(help)* Don't rely on ALL CAPS for help headers (#4132, #4123)
- *(help)* List subcommands first, focusing the emphasis on them (#4132, #4125)
- *(help)* Do not include global args in `cmd help help` (#4131)
- *(help)* Use `[positional]` in list when relevant (#4144)
- *(help)* Show all `[positional]` in usage (#4151)
- *(help)* Polish up subcommands by referring to them as commands (#4132, #4155)
- *(help)* Trim extra whitespace to avoid artifacts from different uses of templates (#4132, #4156)
- *(help)* Hint to the user the difference between `-h` / `--help` when applicable (#4132, #4159)
- *(help)* Shorten help by eliding name/version/author (#4132, #4160)
- *(help)* When short help is long enough to activate `next_line_help`, don't add blank lines (#4132, #4190)
- *(help)* Make help output more dense (reducing horizontal whitespace) (#4132, #4192)
- *(help)* Separate subcommand flags with "," like option flags (#4232, #4235)
- *(help)* Quote the suggested help flag (#4220)
- *(version)* Use `Command::display_name` rather than `Command::bin_name` (#3966)
- *(parser)* Always fill in `""` argument for external subcommands (#3263)
- *(parser)* Short flags now have higher precedence than hyphen values with `Arg::allow_hyphen_values`, like `Command::allow_hyphen_values` (#4187)
- *(parser)* Prefer `InvalidSubcommand` over `UnknownArgument` in more cases (#4219)
- *(derive)* Detect escaped external subcommands that look like built-in subcommands (#3703)
- *(derive)* Leave `Arg::id` as `verbatim` casing (#3282)
- *(derive)* Default to `#[clap(value_parser, action)]` instead of `#[clap(parse)]` (#3827)
## [3.2.18] - 2022-08-29
### Fixes
- *(help)* `Command::print_help` now respects `Command::colored_help`
- *(derive)* Improved error messages
## [3.2.17] - 2022-08-12
### Fixes
- *(derive)* Expose `#[clap(id = ...)]` attribute to match Arg's latest API
## [3.2.16] - 2022-07-30
### Fixes
- Ensure required arguments appear in errors when they are also members of a group (#4004)
## [3.2.15] - 2022-07-25
### Features
- *(derive)* New `default_values_t` and `default_values_os_t` attributes
## [3.2.14] - 2022-07-21
### Fixes
- A `multiple_values` positional followed by another positional now works with multiple flags
## [3.2.13] - 2022-07-19
### Documentation
- Pulled in tutorials, cookbook, and derive reference into rustdoc
## [3.2.12] - 2022-07-14
### Fixes
- Allow an arg to declare a conflict with a group
## [3.2.11] - 2022-07-13
### Features
- Added `Arg::get_all_short_aliaes` and `Arg::get_all_aliases`
## [3.2.10] - 2022-07-12
### Fixes
- Loosen lifetime on `Command::mut_subcommand`
## [3.2.8] - 2022-06-30
### Features
- Added `Command::mut_subcommand` to mirror `Command::mut_arg`
## [3.2.7] - 2022-06-28
### Fixes
- Global arguments should override env-sourced arguments
## [3.2.6] - 2022-06-21
### Fixes
- Don't panic when parsing `--=`
## [3.2.5] - 2022-06-15
### Fixes
- *(derive)* Fix regression with `#[clap(default_value_os_t ...)]` introduced in v3.2.3
## [3.2.4] - 2022-06-14
### Fixes
- *(derive)* Provide more clearer deprecation messages for `#[clap(parse)]` attribute (#3832)
## [3.2.3] - 2022-06-14
### Fixes
- Moved deprecations to be behind the `deprecated` Cargo.toml feature (#3830)
- For now, it is disabled by default though we are considering enabling it by
default as we release the next major version to help draw attention to the
deprecation migration path
## [3.2.2] - 2022-06-14
### Fixes
- *(derive)* Improve the highlighted code for deprecation warnings
**gated behind `unstable-v4`**
- *(derive)* Default to `#[clap(value_parser, action)]` instead of `#[clap(parse)]` (#3827)
## [3.2.1] - 2022-06-13
## [3.2.0] - 2022-06-13
### Compatibility
MSRV is now 1.56.0 (#3732)
Behavior
- Defaults no longer satisfy `required` and its variants (#3793)
- When misusing `ArgMatches::value_of` and friends, debug asserts were turned into panics
Moving (old location deprecated)
- `clap::{PossibleValue, ValueHint}` to `clap::builder::{PossibleValue, ValueHint}`
- `clap::{Indices, OsValues, ValueSource, Values}` to `clap::parser::{Indices, OsValues, ValueSource, Values}`
- `clap::ArgEnum` to `clap::ValueEnum` (#3799)
Replaced
- `Arg::allow_invalid_utf8` with `Arg::value_parser(value_parser!(PathBuf))` (#3753)
- `Arg::validator` / `Arg::validator_os` with `Arg::value_parser` (#3753)
- `Arg::validator_regex` with users providing their own `builder::TypedValueParser` (#3756)
- `Arg::forbid_empty_values` with `builder::NonEmptyStringValueParser` / `builder::PathBufValueParser` (#3753)
- `Arg::possible_values` with `Arg::value_parser([...])`, `builder::PossibleValuesParser`, or `builder::EnumValueParser` (#3753)
- `Arg::max_occurrences` with `arg.action(ArgAction::Count).value_parser(value_parser!(u8).range(..N))` for flags (#3797)
- `Arg::multiple_occurrences` with `ArgAction::Append` or `ArgAction::Count` though positionals will need `Arg::multiple_values` (#3772, #3797)
- `Command::args_override_self` with `ArgAction::Set` (#2627, #3797)
- `AppSettings::NoAutoVersion` with `ArgAction` or `Command::disable_version_flag` (#3800)
- `AppSettings::NoHelpVersion` with `ArgAction` or `Command::disable_help_flag` / `Command::disable_help_subcommand` (#3800)
- `ArgMatches::{value_of, value_of_os, value_of_os_lossy, value_of_t}` with `ArgMatches::{get_one,remove_one}` (#3753)
- `ArgMatches::{values_of, values_of_os, values_of_os_lossy, values_of_t}` with `ArgMatches::{get_many,remove_many}` (#3753)
- `ArgMatches::is_valid_arg` with `ArgMatches::{try_get_one,try_get_many}` (#3753)
- `ArgMatches::occurrences_of` with `ArgMatches::value_source` or `ArgAction::Count` (#3797)
- `ArgMatches::is_present` with `ArgMatches::contains_id` or `ArgAction::SetTrue` (#3797)
- `ArgAction::StoreValue` with `ArgAction::Set` or `ArgAction::Append` (#3797)
- `ArgAction::IncOccurrences` with `ArgAction::SetTrue` or `ArgAction::Count` (#3797)
- *(derive)* `#[clap(parse(...))]` replaced with: (#3589, #3794)
- For default parsers (no `parse` attribute), deprecation warnings can be
silenced by opting into the new behavior by adding either `#[clap(action)]`
or `#[clap(value_parser)]` (ie requesting the default behavior for these
attributes). Alternatively, the `unstable-v4` feature changes the default
away from `parse` to `action`/`value_parser`.
- For `#[clap(parse(from_flag))]` replaced with `#[clap(action = ArgAction::SetTrue)]` (#3794)
- For `#[clap(parse(from_occurrences))]` replaced with `#[clap(action = ArgAction::Count)]` though the field's type must be `u8` (#3794)
- For `#[clap(parse(from_os_str)]` for `PathBuf`, replace it with
`#[clap(value_parser)]` (as mentioned earlier this will call
`value_parser!(PathBuf)` which will auto-select the right `ValueParser`
automatically).
- For `#[clap(parse(try_from_str = ...)]`, replace it with `#[clap(value_parser = ...)]`
- For most other cases, a type implementing `TypedValueParser` will be needed and specify it with `#[clap(value_parser = ...)]`
### Features
- Parsed, typed arguments via `Arg::value_parser` / `ArgMatches::{get_one,get_many}` (#2683, #3732)
- Several built-in `TypedValueParser`s available with an API open for expansion
- `value_parser!(T)` macro for selecting a parser for a given type (#3732) and open to expansion via the `ValueParserFactory` trait (#3755)
- `[&str]` is implicitly a value parser for possible values
- All `ArgMatches` getters do not assume required arguments (#2505)
- Add `ArgMatches::remove_*` variants to transfer ownership
- Add `ArgMatches::try_*` variants to avoid panics for developer errors (#3621)
- Add a `get_raw` to access the underlying `OsStr`s
- `PathBuf` value parsers imply `ValueHint::AnyPath` for completions (#3732)
- Explicit control over parsing via `Arg::action` (#3774)
- `ArgAction::StoreValue`: existing `takes_value(true)` behavior
- `ArgAction::IncOccurrences`: existing `takes_value(false)` behavior
- `ArgAction::Help`: existing `--help` behavior
- `ArgAction::Version`: existing `--version` behavior
- `ArgAction::Set`: Overwrite existing values (like `Arg::multiple_occurrences` mixed with `Command::args_override_self`) (#3777)
- `ArgAction::Append`: like `Arg::multiple_occurrences` (#3777)
- `ArgAction::SetTrue`: Treat `--flag` as `--flag=true` (#3775)
- Implies `Arg::default_value("false")` (#3786)
- Parses `Arg::env` via `Arg::value_parser`
- `ArgAction::SetFalse`: Treat `--flag` as `--flag=false` (#3775)
- Implies `Arg::default_value("true")` (#3786)
- Parses `Arg::env` via `Arg::value_parser`
- `ArgAction::Count`: Treat `--flag --flag --flag` as `--flag=1 --flag=2 --flag=3` (#3775)
- Implies `Arg::default_value("0")` (#3786)
- Parses `Arg::env` via `Arg::value_parser`
- *(derive)* Opt-in to new `Arg::value_parser` / `Arg::action` with either `#[clap(value_parser)]` (#3589, #3742) / `#[clap(action)]` attributes (#3794)
- Default `ValueParser` is determined by `value_parser!` (#3199, #3496)
- Default `ArgAction` is determine by a hard-coded lookup on the type (#3794)
- `Command::multicall` is now stable for busybox-like programs and REPLs (#2861, #3684)
- `ArgMatches::{try_,}contains_id` for checking if there are values for an argument that mirrors the new `get_{one,many}` API
### Fixes
- Don't correct argument id in `default_value_ifs_os`(#3815)
*parser*
- Set `ArgMatches::value_source` and `ArgMatches::occurrences_of` for external subcommands (#3732)
- Use value delimiter for `Arg::default_missing_values` (#3761, #3765)
- Split`Arg::default_value` / `Arg::env` on value delimiters independent of whether `--` was used (#3765)
- Allow applying defaults to flags (#3294, 3775)
- Defaults no longer satisfy `required` and its variants (#3793)
## [3.1.18] - 2022-05-10
### Fixes
- Fix deprecated `arg_enum!` for users migrating to clap3 (#3717)
- Verify all `required_unless_present_all` arguments exist
- Verify group members exist before processing group members (#3711)
- *(help)* Use `...` when not enough `value_names` are supplied
**gated behind `unstable-v4`**
- Verify `required` is not used with conditional required settings (#3660)
- Disallow more `value_names` than `number_of_values` (#2695)
- *(parser)* Assert on unknown args when using external subcommands (#3703)
- *(parser)* Always fill in `""` argument for external subcommands (#3263)
- *(derive)* Detect escaped external subcommands that look like built-in subcommands (#3703)
- *(derive)* Leave `Arg::id` as `verbatim` casing (#3282)
## [3.1.17] - 2022-05-06
### Fixes
- Allow value names for `arg!` macro to have dashes when quoted, like longs
## [3.1.16] - 2022-05-06
### Fixes
- *(parser)* `Arg::exclusive` overrides `Arg::required`, like other conflicts
- *(error)* Don't duplicate arguments in usage
- *(error)* Don't show hidden arguments in conflict error usage
- *(help)* New `help_template` variable `{name}` to fix problems with `{bin}`
- *(help)* Don't wrap URLs
**gated behind `unstable-v4`**
- Leading dashes in `Arg::long` are no longer allowed
- *(help)* Use `Command::display_name` in the help title rather than `Command::bin_name`
## [3.1.15] - 2022-05-02
### Fixes
- *(error)* Render actual usage for unrecognized subcommands
- *(multicall)* Improve bad command error
- *(multicall)* Always require a multicall command
- *(multicall)* Disallow arguments on multicall parent command
- *(multicall)* More consistent with rest of clap errors
## [3.1.14] - 2022-05-01
### Fixes
- Panic when calling `Command::build` with a required positional argument nested several layers in subcommands
## [3.1.13] - 2022-04-30
### Fixes
- Help subcommand and `Command::write_help` now report required arguments in usage in more circumstances
- Unknown subcommand for help subcommand flag now reports an error with more context
- More details reported when using `debug` feature
- Allow disabling `color` feature with `debug` feature enabled
## [3.1.12] - 2022-04-22
### Fixes
- Regression in 3.1.11 where the (output) streams were crossed
## [3.1.11] - 2022-04-22
### Fixes
- Implied conflicts override `Arg::required`, making the behavior consistent with how we calculate conflicts for error reporting
- Members of a mutually exclusive `ArgGroup` override `Arg::required`, making the behavior consistent with how we calculate conflicts for error reporting
- `Arg::overrides_with` always override `Arg::required`, not just when the parser processes an override
## [3.1.10] - 2022-04-19
### Features
- Expose `Command::build` for custom help generation or other command introspection needs
## [3.1.9] - 2022-04-15
### Fixes
- Pin the `clap_derive` version so a compatible version is always used with `clap`
## [3.1.8] - 2022-04-01
### Fixes
- Add `Debug` impls to more types
## [3.1.7] - 2022-03-31
### Fixes
- *(derive)* Abort, rather than ignore, when deriving `ArgEnum` with non-unit unskipped variants
## [3.1.6] - 2022-03-07
### Fixes
- Don't panic when validating delimited defaults (#3541)
- Make it clearer that `cargo` feature is needed
- Documentation improvements
## [3.1.5] - 2022-03-02
### Fixes
- Dependency upgrade
## [3.1.4] - 2022-03-02
### Features
- *(help)* Show `PossibleValue::help` in long help (`--help`) **(gated behind `unstable-v4`)** (#3312)
## [3.1.3] - 2022-02-28
### Fixes
- Don't panic when validating delimited defaults (#3514)
## [3.1.2] - 2022-02-23
### Fixes
- *(derive)* Allow other attribute with a subcommand that has subcommands
### Documentation
- *(examples)* List example topics
- *(derive)* Clarify syntax and relation to builder API
## [3.1.1] - 2022-02-21
### Fixes
- Track caller for `ArgMatches` assertions so the user more easily sees where they need to fix the call
## [3.1.0] - 2022-02-16
### Compatibility
Changes in behavior of note that are not guaranteed to be compatible across releases:
- *(help)* `help` subcommand shows long help like `--help`, rather than short help (`-h`), deprecated `clap::AppSettings::UseLongFormatForHelpSubcommand` (#3440)
- *(help)* Pacman-style subcommands are now ordered the same as usage errors (#3470)
- *(help)* Pacman-style subcommands use standard alternate syntax in usage (#3470)
### Deprecations
- `clap::Command` is now preferred over `clap::App` (#3089 in #3472)
- `clap::command!` is now preferred over `clap::app_from_crate` (#3089 in #3474)
- `clap::CommandFactory::command` is now preferred over `clap::IntoApp::into_app` (#3089 in #3473)
- *(help)* `help` subcommand shows long help like `--help`, rather than short help (`-h`), deprecated `clap::AppSettings::UseLongFormatForHelpSubcommand` (#3440)
- *(error)* Deprecate `clap::AppSettings::WaitOnError`, leaving it to the user to implement
- *(validation)* `clap::Command::subcommand_required(true).arg_required_else_help(true)` is now preferred over `clap::AppSettings::SubcommandRequiredElseHelp` (#3280)
- *(builder)* `clap::AppSettings` are nearly all deprecated and replaced with builder methods and getters (#2717)
- *(builder)* `clap::ArgSettings` is deprecated and replaced with builder methods and getters (#2717)
- *(builder)* `clap::Arg::id` and `clap::ArgGroup::id` are now preferred over `clap::Arg::name` and `clap::ArgGroup::name` (#3335)
- *(help)* `clap::Command::next_help_heading` is now preferred over `clap::Command::help_heading` (#1807, #1553)
- *(error)* `clap::error::ErrorKind` is now preferred over `clap::ErrorKind` (#3395)
- *(error)* `clap::Error::kind()` is now preferred over `clap::Error::kind`
- *(error)* `clap::Error::context()` is now preferred over `clap::Error::info` (#2628)
Note: All items deprecated in 3.0.0 are now hidden in the documentation. (#3458)
### Features
- *(matches)* Add `clap::ArgMatches::value_source` to determine what insert the value (#1345)
- *(help)* Override derived display order with `clap::Command::next_display_order` (#1807)
- *(error)* Show possible values when an argument doesn't have a value (#3320)
- *(error)* New `clap::Error::context` API to open the door for fully-custom error messages (#2628)
- *(error)* `clap::error::ErrorKind` now implements `Display`
### Fixes
- *(builder)* Some functions were renamed for consistency and fixing spelling issues
- *(builder)* Allow `clap::Command::color` to override previous calls (#3449)
- *(parse)* Propagate globals with multiple subcommands (#3428)
- *(validation)* Give `ArgRequiredElseHelp` precedence over `SubcommandRequired` (#3456)
- *(validation)* Default values no longer count as "present" for conflicts, requires, `clap::Command::arg_required_else_help`, etc (#3076, #1264)
- *(assert)* Report invalid defaults (#3202)
- *(help)* Clarify how to handle `-h` conflicts (#3403)
- *(help)* Make it easier to debug the addition of help flags (#3425)
- *(help)* Pacman-style subcommands are now separated with spaces (#3470)
- *(help)* Pacman-style subcommands are now ordered the same as usage errors (#3470)
- *(help)* Pacman-style subcommands use standard alternate syntax in usage (#3470)
- *(error)* Be consistent in showing of required attributes between errors / usage (#3390)
- *(error)* Show user's order of possible values, like in `--help` (#1549)
- *(error)* Allow customizing error type in `clap::error::Result` (#3395)
### Performance
- *(error)* Reduced stack size of `clap::Error` (#3395)
### Documentation
- *(builder)* Correct data take accepted for `clap::Arg::validator`
- *(derive)* Clarify `parse` attribute
- *(tutorial)* Demonstrate custom parsing
- *(example)* Consistently list out required feature flags (#3448)
## [3.0.14] - 2022-02-01
### Features
- Added `ArgMatches::args_present()` to check if any args are present
- Added `Error::kind()` as we work to deprecate direct member access for `Error`
- Added `App::get_version`
- Added `App::get_long_version`
- Added `App::get_author`
- Added `App::get_subcommand_help_heading`
- Added `App::get_subcommand_value_name`
- Added `App::get_after_help`
- Added `App::get_after_long_help`
### Performance
- Misc binary size reductions
## [3.0.13] - 2022-01-26
### Fixes
- Show optional flag values wrapped in `[]`
## [3.0.12] - 2022-01-24
### Features
- *(derive)* Support for `default_value_os_t`
## [3.0.11] - 2022-01-24
### Fixes
- Ensure conflicts work when they target a group with a default value
## [3.0.10] - 2022-01-18
### Fixes
- Resolve `panic!` from v3.0.8 when using `global_setting(PropagateVersion)`.
## [3.0.9] - 2022-01-17
### Features
- Added `App::find_subcommand_mut`
## [3.0.8] - 2022-01-17
### Fixes
- Respected `DisableColoredHelp` on `cmd help help`
- Provide a little more context when completing arguments for `cmd help`
- Provide more context for some asserts
- Small documentation improvements
## [3.0.7] - 2022-01-12
### Fixes
- Shift more asserts from parsing to `App` building (ie will now run in `App::debug_assert`)
**derive**
- Documentation fixes
## [3.0.6] - 2022-01-10
### Fixes
**derive**
- Don't assume user does `use clap::ArgEnum` (#3277)
- Documentation fixes
## [3.0.5] - 2022-01-05
### Fixes