- Polish empty lines and disable description printing for apps and
subcommands with empty name, empty group and with no options and
subcommands.
- Add commentDefaults() method to trigger to comment default value
options in case default_also is true, so that the result set of an
option is not pollute with default option values.
- In case dafault_also is true mark required but not yet configured
options as "<REQUIRED>" and not yet configured default options as "" in
a commented line in the config file.
---------
Co-authored-by: Volker Christian <volker.christian@fh-hagenberg.at>
Example of help modification as documentation supplement.
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Philip Top <top1@llnl.gov>
Co-authored-by: Philip Top <phlptp@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>
Hello. Thank you for this tool.
I found a few small typos in the RequiredError class.
This is an error message I received:
```
Requires at most 2 options be used and 3were given from [filename,--get-size,--get-size2]
```
This PR changes the error message to
```
Requires at most 2 options be used but 3 were given from [filename,--get-size,--get-size2]
```
Happy to make changes as needed!
## Source
```cpp
std::string filename;
bool get_size = false;
CLI::App app{"Program to read a file specified as command-line argument"};
app.add_option("filename", filename, "File to read")->required();
app.add_flag("--get-size", get_size, "Print the size of the file");
app.add_flag("--get-size2", get_size, "Print the size of the file2");
app.require_option(1, 2); // Enforce only one flag can be input
CLI11_PARSE(app, argc, argv);
```
## Further Idea
Also, another idea I had was to remove required options from this error
message. In this example, "filename" is required, so a better error
message would be
```
Requires at most 1 options be used but 2 were given from [--get-size,--get-size2]
```
I'm happy to look into this if you feel it would be valuable
Update and test with some newer compilers and cmake versions
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Based on Issue #931 and #942.
Add an example of how to do what those issues were requesting.
---------
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
update conan and azure-pipelines to fix gcc 4.8 issue
make the CLI11 target sources only for newer CMake
Change the cmake to use subdirectory and move the library generation and warnings to separate files.
* fix a few issues with config file output, namely an ability to print a default empty string, and to adjust the quote characters used when quoting strings or characters.
* fix formatting
* Update CMakeLists.txt
* Update README.md
* Add a dedicated version option to CLI11 to facilitate use of version flags, similar to help flags
* add some test for the version flag
* update errors and formatting
* clear up gcc 4.8 warnings
* add a few more tests
* fix compiler error
* fix a few comments, and change default version flag to only use "--version"
* remove `version` calls and tests
* formatting and add `std::string version()` back in.
* 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 cpplint config file
* Add cpplint to CI
* Add checks
* Add docker container tag
* Unindent container
As suggested in code review
Co-Authored-By: Henry Schreiner <HenrySchreinerIII@gmail.com>
* Fix cpplint issues
* Fix clang-format
* Include and fix modern cpplint runtime/int
* Include and fix cpplint build/include_order
* Revert "Include and fix cpplint build/include_order"
This reverts commit bddb6a2d6744c5397f387ccd03416a1ec5e29862.
* Update explanation, sort alphabetically
* Implement suggestion from code review
Co-Authored-By: Henry Schreiner <HenrySchreinerIII@gmail.com>
* Include cstdint header, prefix its symbols with std::
* Forgot std::
Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>
* Make CI fail with readability-container-size-empty flag
* Make CI fail with cppcoreguidelines-owning-memory flag
* Add all google checks, exclude specific ones
* Apply clang-tidy fixes
* Make timer constructors explicit
* Add check for unscoped namespaces
* Replace unscoped namespace by using-declaration
* Replace unscoped namespace by using-declaration
* add ability to specify deprecated or retired options.
* add retired example and tests
* update some formatting and a few more test executions
* fix formatting on retired.cpp
* add another test to fill coverage gap for existing options that are being retired.
* add example comments
* Update readme with the descriptions of the new helper functions
* fix space on readme
* Apply suggestions from code review
Co-Authored-By: Christoph Bachhuber <cbachhuber89@gmail.com>
* add some flags to the code coverage report and update some names and add more descriptions to deprecated options
* update formatting on App
* add an example where the name of the enum is printed through a stream output function, which subverted the checkTransformer conversion and prevented conversion of the enumeration.
* add missing 'typename'
* try a simpler version of the value_string using const reference for all overloads
* use auto return type to match to_string return type in value_string
* remove extra spaces
* Fixing some warnings
* Make gtest a system library
* Fixing format
* Adding better method for adding warnings
* Nicer Windows deprecated test
* JSON update and drop testing timer
* Warnings as errors everywhere
* 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)
* add a function to get the remaining arguments in a valid order for parse. and add rvalue reference overloads for parse and _parse so args is not refilled if not needed.
* check a few more tests and verify ExtrasError works on parse(rValue vector)
remove impossible to reach branches in _parse function
* add callback_passthrough example and tests
* 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.
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.
* 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
* 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 mapping
* IsMember now supports maps
* Adding example, better Val combs, and cleanup
* Reversing order of map, adding pair support
* Check/Transform suppport for Validators
* Adding enum tools from @phlptp, more tests
* 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.
