Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Plan for 2.0 #384

Closed
5 tasks done
henryiii opened this issue Dec 31, 2019 · 14 comments
Closed
5 tasks done

Plan for 2.0 #384

henryiii opened this issue Dec 31, 2019 · 14 comments
Milestone
v2.0

Comments

@henryiii
Copy link
Collaborator

henryiii commented Dec 31, 2019 •
edited
Loading

  • Make more parts of the library optional, at least in multiheader mode (postponed)
  • Allow the library to be precompiled to address Improve compile time #194. (still will support header only / single header mode) - postponed to 2.x.
    • New make single header tooling
  • Drop deprecated add_set templated methods
  • Drop deprecated extra true/false argument for capture default on add_option refactor!: drop defaulted from add_option #597
  • Drop add_complex (no longer required)
  • Allow compilation with exceptions turned off (might put off till 3.0)
  • Change Config file output default to TOML
@henryiii henryiii added this to the v2.0 milestone Dec 31, 2019
@sergeyklay
Copy link

Can I ask to consider #355 as well as #353.

Thank you

@phlptp
Copy link
Collaborator

phlptp commented Jan 1, 2020 •
edited
Loading

@phlptp phlptp mentioned this issue Feb 24, 2020
Merged
@henryiii henryiii pinned this issue Jan 27, 2021
@henryiii
Copy link
Collaborator Author

So that we can get something out rather than keep waiting for a large change, I'd like to postpone the pre-compile plans (which is mostly not user facing; that is, users don't have to use it) for 2.x. That way I can focus on the exception part (which will be user-facing), and get a release out sooner rather than (much) later. I have a daughter coming soon, so trying to plan out my limited time!

@henryiii
Copy link
Collaborator Author

henryiii commented Jun 15, 2021 •
edited
Loading

I might be forced to put off the exception refactoring, since that will further delay 2.0 and as I always tell other people, numbers are cheap - we could do a 3.0 if it requires a backwards incompatible change. And 2.0 would already be useful to get out the door. (plus I accidentally deleted some work I had done on it)

I'll try to get the final removals in (#597 and dropping add_complex) and currently open fixes in, and then if I can't get the error reworking in within a week or so, I'll probably just make a release. @phlptp is this fine with you, or do you have anything else that needs to go in?

// Only part of work that didn't get deleted, pasting here
#ifndef CLI11_EXCEPTIONS
#ifdef __EXCEPTIONS
#define CLI11_EXCEPTIONS 1
// GCC and Clang will define the above define
#elif __GNUC__
#define CLI11_EXCEPTIONS 0
#else
#define CLI11_EXCEPTIONS 1
#endif
#endif

@phlptp
Copy link
Collaborator

phlptp commented Jun 15, 2021 via email

@data-man
Copy link

It would be nice to add a regex validator.

@henryiii
Copy link
Collaborator Author

Release should happen fairly soon, probably end of this week. Will need to update contributors, changelog, upcoming -> new features labels.

@henryiii
Copy link
Collaborator Author

It would be nice to add a regex validator.

That would require GCC 4.9+. It's easy to add one yourself, though - and maybe it could be added as an optional include. Those are a bit easier in 2.0.

@phlptp
Copy link
Collaborator

phlptp commented Jun 28, 2021

I think a number of the validators should be split into a separate optional include. Then we would have a little more freedom for a validator library that wouldn't slow down compilation if someone didn't need them. At that point adding a regex validator shouldn't be an issue either. But lets get the 2.0 release out first.

@phlptp
Copy link
Collaborator

phlptp commented Jun 28, 2021

@henryiii are you changing the minimum compiler requirement on 2.0?

@henryiii
Copy link
Collaborator Author

No, it't still 4.8+. CentOS 7 is still an important target (and manylinux1 is 4.8 too). But I'd be okay with an optional file having a higher requirement.

@henryiii
Copy link
Collaborator Author

This is now out!

@henryiii henryiii unpinned this issue Jul 14, 2021
@kgraney
Copy link

kgraney commented Nov 21, 2022

Just to confirm here @henryiii, the exception refactoring didn't happen, right? Is it still planned?

@henryiii
Copy link
Collaborator Author

Yes, it was put off to avoid delaying 2.0 too much.

@LostInCompilation LostInCompilation mentioned this issue Mar 19, 2023
Merged
phlptp added a commit that referenced this issue Oct 7, 2024
@LostInCompilation @pre-commit-ci @phlptp
A better Help formatter (V2) (#866)
65442ad 
_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
- #384 (comment)
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:
#554

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Philip Top <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
v2.0
Development

No branches or pull requests
5 participants
@sergeyklay @data-man @kgraney @henryiii @phlptp