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>
_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>
* Added an option to change the text between definition and description
* Added test and readme
* Update Option.hpp
Fixed shadowing issue
* style: fix formatting
Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com>
* 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>
fix incorrect parenthesis
update some clang-tidy fixes mainly else after return but a few conversions from into to bool
add extra newline before footer
add an extra field to the extra Error
add a footer callback for help operations
* 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
Updates to the readme
update the readme with some documentation
add a few more tests to complete code coverage
update with count strings in flags instead an array of strings for each count
add the '!' shortcut notation. add some checks on the help output
allow the false flag syntax to support --option{false}
add a bool lexical cast to make everything consistent when converting to a bool. Moved a few functions around
make the command line behave like the INI file wrt flags, flag options are allowed to process the value so `--flag=false` actually does the expected thing.
Add functionality similar to click style argument that allow specifying a false flag that when used generates a false result on the flag.
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.
in progress: formatters
Getting closer
Working on apps
One test actually runs
All builds, added filter functions
Reverting a few behavours as needed
Repairs
All tests pass
Fixing error with adding help flag
Labels are simpler mappings, normalized setters
Adding help_all
Adding a few more tests
One more line tested
Adding one more check
Adding to readme
Simplify naming
Adding default constructors
Fixing spacing issues with subcommand all printout
Adding a couple of tests
