This has been bounced around for a couple years now
#474 and a few others have expressed desire to work with non-standard
option names. We have been somewhat resistant to that but I think it can
be done now. This PR adds a modifier `allow_non_standard_option_names()`
It is purposely long, it is purposely off by default. But what it does
is allow option names with a single `-` to act like a short option name.
With this modifier enabled no single letter short option names are
allowed to start with the same letter as a non-standard names. For
example `-s` and `-single` would not be allowed.
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
add mechanics for the fuzzer to add custom options.
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Add modifier for subcommands to restrict subcommands falling through to
parent.
This will resolve#1022
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
_This is the new PR I've mentioned to work on in PR #858_
## A better Help Formatter
_See below for images of the new help page_
Finally, after a lot of planning, understanding CLI11's codebase,
testing and coding, the new default Help Formatter is done. There are a
lot of changes to make the help page more readable and closer to UNIX
standards, see Changelog below for details. One of the highlights is
automatic paragraph formatting with correct line wrapping for App and
options/flag descriptions as well as the footer.
A goal was to provide more flexibility and better readability for the
help page while providing full compatibility with Apps using CLI11 (no
breaking changes and no changes to Apps required). Also better support
for different terminal sizes. Users can now specify three new optional
attributes: `right_column_width_`, `description_paragraph_width_` and
`footer_paragraph_width_`. See code documentation for more details. The
different columns for options/flags now scale with the set
`column_width_` value: Single dash flags occupy 33% of the set
`column_width_`, double dash flags and options (like REQUIRED) 66%.
These new attributes allow for indirectly respecting terminal geometry,
footer paragraph formatting has also been added (#355). This PR also
implements the issues #353 and #856.
The new help page formatting can also be used as an input for man page
generation, since it's oriented on the man page style (#413).
[help2man](https://www.gnu.org/software/help2man/) can be used to
generate man pages from help output (see comment down below for
example).
I thoroughly tested this code with all possible combinations of flags,
options, positionals, subcommands, validators, ...
So far everything works great.
I hope this PR looks good and meets all requirements. I'm looking
forward to the implementation of this PR into CLI11. If you have any
questions or suggestions feel free to comment.
### Fixed/implemented issues by this PR
- #353 Better options formatting
- #856 Space between options
- #355 Footer formatting
- #413 Man page generation can be achieved using help2man with the new
help formatting
- https://github.com/CLIUtils/CLI11/issues/384#issuecomment-570066436
Better help formatting can be marked as complete
### What about the failing tests?
Of course the tests expect the old help text format. This is why 6 of
the tests are failing. Since it is a bit of work to migrate the tests to
the new help format, I first wanted to push out this PR and get
confirmation before I'll update all the tests.
So please let me know if this PR gets implemented, what changes should
be made and then I'll migrate the tests to the new help format, either
in this PR or I'll make a new one.
## Changelog:
#### There are _no breaking changes_. Every App using CLI11 will work
with this new formatter with no changes required.
- Added empty lines at beginning and end of help text
- Removed double new-line between option groups for consistency. Now all
sections have the same number of new-lines
- Switched usage and description order
- Only show "Usage"-string if no App name is present. This provides
better readability
- Made categories (Options, Positionals, ...) capital
- Changed `ConfigBase::to_config` to correctly process capital
"OPTIONS"-group (only affects descriptions of the config file, not a
breaking change)
- Added a paragraph formatter function `streamOutAsParagraph` to
StringTools.hpp
- Made "description" a paragraph block with correct, word respecting
line wrapping and indentation (using the new paragraph formatter
function)
- Made the footer a paragraph block with correct, word respecting line
wrapping and indentation
- Updated documentation for `column_width_` to make it more clear
- Added new member: `right_column_width_`, added getter and setter for
`right_column_width_`
- Added new member: `description_paragraph_width_`, added getter and
setter for `description_paragraph_width_`
- Added new member: `footer_paragraph_width_`, added getter and setter
for `footer_paragraph_width_ `
- Positionals description are now formatted as paragraph with correct,
word respecting line wrapping
- Options description are now formatted as paragraph with correct, word
respecting line wrapping
- Short and long options/flags/names are now correctly formatted to
always be at the right position (also for subcommand options/flags)
- Short and long options/flags/names column widths scale linearly with
the `column_width_` attribute to better adapt to different
`column_width_` sizes
- Merged PR #860
## What's planned for the future?
- I'm thinking of better formatting the options of flags (like REQUIRED,
TEXT, INT, ...) and make them also in a seperate column. This way they
would also always be at the same position. However I decided against it
for this PR, since I wanted them to be as close as possible to the
actual flag. With my implementation it is quite easy to add this change
in the future.
- Subcommands: I'm planning on better formatting the Subcommands. With
this PR only the short and long flags/options of subcommands are better
formatted (like it is with the main flags, see images down below).
- Maybe implement a different way to display expected data type options
(TEXT, INT, ...). For example: `--file-name=<TEXT>` for long flags only
and if `disable_flag_override_` is false.
- Maybe add something like this:
https://github.com/CLIUtils/CLI11/issues/554
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Philip Top <phlptp@gmail.com>
get_subcommand when used for parsing config files, was throwing and
catching as part of control flow and expected operation, this resulting
in a performance hit in select cases. A get_subcommand_no_throw was
added to resolve this issue.
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Do not check environment variables if a subcommand has not been
triggered.
Fixes#903
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
* Allow using dot notation for subcommand arguments such as --sub1.field
* add tests for dot notation for subcommands
* style: pre-commit.ci fixes
* add test for short form arguments in dot notation
* style: pre-commit.ci fixes
* add _pre_parse_callback_ support using dot notation
* style: pre-commit.ci fixes
* update cmake tests to include 3.24
* change line endings
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
* add some coverage tests, and fix the issue with negated flags and config files
* style: pre-commit.ci fixes
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
* add a few tests related to github issues
* change how the default is displayed in the help message prev was =XXXX, this was confusing in some cases particularly with flags or with multiple option names. Now is [default=XXXX] which makes it clearer what the value represents.
* Try to fix RTTI issue
* style: pre-commit.ci fixes
* Fix subcommand callbacks being called multiple times if in an option group
* style: pre-commit.ci fixes
* remove extra group call
* change [default=XXXXD] to just [XXXXX] for the default specification
* update changelog
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
* add a test for std::map
* add some test of the relaxed naming and other checks
* add validator for aliases, group names and option groups
* add extra tests and update readme
* style: pre-commit.ci fixes
* update the book chapters
* fix codacy issue
* Apply suggestions from code review
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
* Fix excessive call to subcommand's final_callback
When parse_complete_callback_ is set there is an extra call to
run_callback() inside the App::_parse(std::vector<std::string>&) method.
This extra call also excessively calls a final_callback_ (when it is
also set) for the command and (since it is recursive) for it's
subcommands.
This commit adds extra boolean parameter for the run_callback() method
allowing to explicitly suppress calling to final_callback_. The value of
this parameter is also propagated to recursive calls to run_callback().
Fixes#572
* fix: main app should run final_callback, add tests
Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com>
* Add whitespace/comments check
* Adapt spacing in clang-format
* Fix cpplint whitespace/comments issues
* Grammar
* Do not use clang-format for comment spacing
* Fix with clang-format pre-commit hook
* work on the flags book chapter and making sure the values are initialized properly.
* Fix initialization of values used in flags or options
* update some formatting and more brace initialization
* update more formatting and fix a incorrect initializer
* more formatting and some error fixes
* more formatting
* Small formatting fix
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
* add a needs method to the app/subcommand
* add some needs subcommand tests
* add a few more subcommand tests for needs and alias
* fix shadow warnings
* add some tests of the error pathways and fix a few anomalous conditions on the Option excludes function
* add needs and alias functions in the readme
* add some tests of ignore_case and underscore with the alias operations
* add a few more test cases for needs option groups
* add callback tests with needs and add a few comments in the readme
* update formatting
* add error checks on the aliases and restrictions on valid names for subcommands and aliases
* add checks for matching subcommands and improve error return values to include the offending name
* add some tests of the alias errors
* add some more tests to check subcommand name matching during addition
* add some additional tests and remove a redundant chunk of codes
* add some more checks of subcommand name overlap in option_groups
* allow disabled subcommand to bypass name matching check
* fix signed mismatch
add test from readme about callbacks
update callback documentation,
add a subbcommand immediate_callback test
add third callback and readme update
* a few more updates to the readme on `immediate_callback`
* Apply suggestions from code review
Co-Authored-By: Henry Schreiner <HenrySchreinerIII@gmail.com>
* Allow immediate_callback on the main app to run the main app callback prior to named subcommand callbacks, and reflect this change in the a new test and docs.
* Update README.md
Co-Authored-By: Henry Schreiner <HenrySchreinerIII@gmail.com>
add some test of the remove_excludes functions
add test for Issue #256
add remove_subcommand fail test
add remove_subcommand function and add_subcommand to option_group and some tests associated with them.
rework return values from _parse_* function to return true if the value was processed false otherwise, this simplified the logic and got rid of the pulling and clearing of the missing fields from option groups.
add TriggerOff and TriggerOn helper functions and some tests for them
add shapes example of multiple callbacks in order.
allow specification of callbacks that get executed immediately on completion of parsing of subcommand
add tests for enabled/disabled by default
add _get_fallthrough_parent. To get the most appropriate parent to fallthrough to
add enabled and disabled by default functions
add positional_arity example
Add a pre_parse_callback_ for apps. The Pre parse callback takes an argument for the number of remaining arguments left to process, and will execute prior to parsing for subcommands, and after the first option parse for option_groups.
Make sure that nameless subcommands can handle subcommands and that App will treat subcommands in a group nearly the same as if they were in the in the app to begin with.
* change the move function to _move_option and add an additional test
add a validation check on min options to make sure it is even possible to succeed.
add some additional tests to cover code paths and potential errors.
add a number of additional tests and checks and fix some issues with the add function in option_groups
clean up example and help formatting
add option_groups example to play with
move create_option_group to a member function using a dummy template
add some optionGroup tests
add min and max options calls and an associated Error call
* add ranges example, add excludes to app for options and subcommands.
* add some tests on ranges, and some subcommand tests with exclusion
* add tests in optionGroups for some invalid inputs
* add required option to subcommands and option_groups
* add disabled flag
* add disable option to subcommands and some more tests
* start work on ReadMe modifications
* update the readme with descriptions of function and methods added for option_groups
* clear up gcc 4.7 warnings
* some update to the Readme and a few more warnings fixed
* Minor readme touchup
add some comments in readME about performance
move operator[] to return const Option *
Apply suggestions from code review
Co-Authored-By: phlptp <top1@llnl.gov>
update readme and add some IniTests and fix a bug from the tests
add_flag_callback
add a few tests to capture the different paths
fix incorrectly updated CMAKE file, and add some subcommand test for option finding
add disable_flag_override and work out some kinks in the find option functions
add some more tests and fix a few bugs in as<> function for options
Allow general flag types and default values, add shortcut notation for retrieving values
* Adding first draft of Sets
Use IsMember now
Using IsMember as backend for Set
Non-const validator backend
Move set tests to set
Clearer inits
* Drop shortcut
Tighten up classes a bit for MSVC
Check with GCC 4.8 too
* Simpler templates, but more of them
Dropping more type safety for older compilers
Shortcut string set
* Adding shortcut init
Making g++ 4.7 docker image happy
Fix Clang tidy issue with last commit
Adding one more shortcut, adding a couple of tests
* Dropping dual pointer versions of code
* Smarter shortcut syntax
* Adding slighly faster choices
* Cleanup to make InMember simpler
* Drop choices for now, adding some tests
* ValidationError is now always the error from a validator
* Support for other types of initializer lists, including enums
* Factor out type utilities, single version of IsMember code
* Adding a few tests for #224
* Minor cleanup for Validation Error
* Adding tests, moved deprecated tests
* Docs updates
increment the parse_ variable on unnamed subcommands.
update the readme, and add a formatter test for nameless subcommands in nondefault group with other named subcommands.
add a test of default arguments
add a formatter test
add tests for unnamed subcommands and an example of the partitioned subcommands.
change the app_p to be a shared_ptr so you can add an App later on and merge them together
add the ability to add unnamed subcommands that allow partitioning on options into multiple apps.
* add ignore_underscore test cases and options to app
* add ignore_underscore for add_sets and some more tests for the sets and subcommands
* add some documentation lines and some failing tests
* update readme with ignore_underscore option
* remove failing tests from known issue
* remove empty line for code coverage
* Adding new parse layout
* Dropping shortcurcuit from help, since it has special override
* Refactor help call
* Dropping shortcurcuit since it is not needed now that help has custom behavoir
* Dropping MaxSubcommand error (cannot occur)
