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>
This adds a round trip test for config file generation to the fuzzer.
(the next step after this PR will be a fuzzer that verifies that the
round trip actually matches the results.
This change ended up requiring quite a few minor changes to fix the
ambiguities between the config file generation and config file reader.
1). There was a number of potential conflicts between positional names
and regular option names that could be triggered in config files, this
required a number of additional checks on the positional naming to
ensure no conflicts.
2). flag options with disable flag override can produce output results
that are not valid by themselves, resolving this required flag input to
be able to handle an array and output the original value set of results.
3). strings with non-printable characters could cause all sorts of chaos
in the config files. This was resolved by generating a binary string
conversion format and handling multiline comments and characters, and
handling escaped characters. Note; I think a better solution is to move
to fully supporting string formatting and escaping along with the binary
strings from TOML now that TOML 1.0 is finalized. That will not be this
PR though, maybe the next one.
4). Lot of ambiguities and edge cases in the string splitter, this was
reworked
5). handling of comments was not done well, especially comment characters in the
name of the option which is allowed.
6). non printable characters in the option naming. This would be weird
in practice but it also cause some big holes in the config file
generation, so the restricted character set for option naming was
expanded. (don't allow spaces or control characters).
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
* fix: show newline before footer only if footer is set and not empty
* feat: added usage message replacement feature
* fix: tests corrected for new help message formatting
* 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 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>
Refactor some of the configuration file handling code. Make it easier to get the actual file that was processed, and allow extras in the config file to be ignored (default now), captured or errored.
fix std::error reference and formatting
add test for required but no default and fix a shadow warning on 'required' from gcc 4.8
Test correctness of config write-read loop
fix config generation for flag definitions
make the config output conform with toml
continue work on the config file interpretation and construction
get all the ini tests working again with the cleaned up features.
update formatting
rename IniTest to ConfigFileTest to better reflect actual tests and add a few more test of the configTOML
disambiguate enable/disable by default to an enumeration, and to make room for a configurable option to allow subcommands to be triggered by a config file.
add a ConfigBase class to generally reflect a broader class of configuration files formats of similar nature to INI files
add configurable to app and allow it to trigger subcommands
add test of ini formatting
add section support to the config files so sections can be opened and closed and the callbacks triggered as appropriate.
add handling of option groups to the config file output
add subcommand and option group configuration to config file output
subsubcom test on config files
fix a few sign comparison warnings and formatting
start working on the book edits for configuration and a few more tests
more test to check for subcommand close in config files
more tests for coverage
generalize section opening and closing
add more tests and some fixes for different configurations
yet more tests of different situations related to configuration files
test more paths for configuration file sections
remove some unused code and fix some codacy warnings
update readme with updates from configuration files
more book edits and README formatting
remove extra space
Apply suggestions from code review
Co-Authored-By: Henry Schreiner <HenrySchreinerIII@gmail.com>
fix some comments and documentation
fix spacing
Rename size_t -> std::size_t
Fix compiler warnings with -Wsign-conversion
Fix new warnings with -Wsign-conversion in PR
* add expanded type_size specification
* add some more checks for type_size_max
* continued work on getting type sizes more flexible
* make some more tweaks to option to split up validate and reduce sections
* git rid of exceptions on the type_size functions exceptions, allow any number to be entered for the min and max and don't make a distinction between flags and other types.
* add expected count
* add the allow extra args flag in an option
* start working in allow_extra_args
* write some stuff in the book, and continue working on the failing test cases
* fix a few more of the helpers tests
* a few more test cases running
* all tests pass, fixing calls in ini files
* get vector<pair> working and all tests passing
* change callback to use reference to remove allocation and copy operation
* add support and test for vector<vector<X>>
* change Validators_ to validators_ for consistency
* fix linux warnings and errors by reording some templates and adding some typename keywords
* add support for std::vector<X> as the cross conversion type so optional<std::vector<X>> is supported using the full template of add_option.
* a few more test cases to take care of some coverage gaps
* add missing parenthesis
* add some more tests for coverage gaps
* add test for flag like option
* add transform test for `as<X>` function and make it pass through the defaults
* add a few more tests and have vector default string interpreted correctly.
* add test for defaulted integer, and route default string for defaulted value which would otherwise be empty
* some code cleanup and comments and few more test coverage gap tests
* add more tests and fix a few bugs on the type size and different code paths
* remove path in results by fixing the clear of options so they go back to parsing state.
* get coverage back to 100%
* clang_tidy, and codacy fixes
* reorder the lexical_conversion definitions
* update some formatting
* update whitespace on book chapter
After https://github.com/CLIUtils/CLI11/pull/329 the get_options version being used in the test was the non-const.
Forced testing on non-const by using a const-ref to the app.
Also added testing to ensure the list of options of both const and non-const are the same as expected.
* 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
* add some tests with default capture on the two parameter template and some notes about it in the README.md
remove the test from visual studio 2015
vs2015 doesn't seem to properly deal with is_assignable in the cases we care about so make a standalone version that is more direct in what we are doing
add version to appveyor and add some notes to the readme
fix a few test cases to make sure code is covered and test a few other paths
remove unneeded enum streaming operator
add some diagnostic escapes around trait code to eliminate gcc Wnarrowing warnings
work specification of the template operations
remove optional add some templates for options conversions
add the two parameter template for add_option
* Fix some comments from Code review and add more description
* fix case when string_view doesn't work to append to a string.
* This PR also addressed #300
* modify lexical_cast to take const std::string &, instead of by value to allow string_view in a few cases
* First streaming version
* Using to_string instead
* Switching to new backend
* Moving to capture function for defaults
* Rename capture_default + _str
* defaultval -> default_str, added always_capture_default
* Fix style
* Adding tests and docs to readme
* Dropping macOS on Travis (supported through Azure)
* some tweaks with optional
* remove set_results function that was bypassing some of the result processing in some cases of config files.
* add positional Validator example and tests add CLI::Number validator.
* add positional Validator example and tests add CLI::Number validator.
* do some reformatting for style checks and remove auto in test lambda.
* add transform and checkedTransform tests
add Transformer and CheckedTransformer validators
* Eliminate the Validator description string, some code cleanup
add tests
Make Validators a full Object and remove friend, move to descriptions instead of overriding type name.
update validators to actually merge the type strings and use all validators in the type outputs
rework join so it works without the start variable, allow some forwarding references in the validator types, some tests for non-copyable maps, and transforms
merge the search function and enable use of member search function, make the pair adapters forwarding instead of copying
* add a few more tests and documentation
fix some gcc 4.7 issues and add a few more test cases and more parts of the README
Work on ReadMe and add Bound validator to clamp values
* updates to README.md
* Add some more in TOC of README and fix style in Option.hpp
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
* add some fields and functions for windows like options
add test cases for windows options and refactor for additional string functions
* try to fix code coverage to 100% again. add some additional documentation and a few additional test cases to verify documentation
* remove some extra brackets
* 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
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
