formatter: add long_option_alignment_ratio

[radimkrcmar]

The default formatter has hardcoded ratio at which the long options are aligned. It's currently 1/3 of the column, which makes the default look awkward:

  -h,     --help              Print
          --option            Something

A ->long_option_alignment_ratio(6/30.f) allows output to look like this:

  -h, --help                  Print
      --option                Something

The 1/3 ratio is also bad if you want to print "descriptive" long options on a single line, because then you might want to increase the column width, but that means you waste more space on short options.

e.g. ->column_width(46)

  -l,          --very-descriptive-long-option  Something

vs. ->column_width(38)

  -l,       --very-descriptive-long-option
                                      Something

vs. ->column_width(38) ->long_option_alignment_ratio(6/38.f)

  -l, --very-descriptive-long-option  Something

Any absolute offset X can be set as X/column_width, so provide a ratio-based interface.

I would have prefered to give an absolute integer offset, but we still have to preserve the functionality that does 1/3 if user changed nothing, which means that ratio-based interface is simpler.

I don't have a good idea for the name, "short_option_ratio" might work as well.
The setter does not sanity check that the value is in [0;1] range.

[Copilot]

Pull Request Overview

This PR adds configurable alignment for long options in the CLI formatter by introducing a long_option_alignment_ratio parameter. The change replaces the hardcoded 1/3 ratio with a customizable float value, allowing better control over the visual alignment of short and long options in help text.

Key changes:

• Adds long_option_alignment_ratio_ member variable with default value of 1/3
• Replaces hardcoded column width calculations with ratio-based calculations
• Provides setter method for configuring the alignment ratio

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
include/CLI/FormatterFwd.hpp	Adds new member variable and setter method for long option alignment ratio
include/CLI/impl/Formatter_inl.hpp	Updates column width calculations to use the configurable ratio instead of hardcoded 1/3
tests/FormatterTest.cpp	Adds test case to verify the new alignment functionality works correctly

[Copilot]

The expression 1/3.0f uses integer division before conversion to float. Use 1.0f/3.0f to ensure proper floating-point division.

Suggested change

	float long_option_alignment_ratio_{1/3.0f};
	float long_option_alignment_ratio_{1.0f/3.0f};

[radimkrcmar]

No, the expression first promotes to float, but I can use 1.f / 3.f if that fits the coding style better.

[Copilot]

The setter method lacks input validation to ensure the ratio is within the documented [0;1] range, which could lead to unexpected formatting behavior.

[radimkrcmar]

I am aware, do we want to complicate CLI11 by checking?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (e4ee3af) to head (7df9d9c).
⚠️ Report is 113 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##              main     #1185     +/-   ##
===========================================
  Coverage   100.00%   100.00%             
===========================================
  Files           17        17             
  Lines         4546      5171    +625     
  Branches         0      1062   +1062     
===========================================
+ Hits          4546      5171    +625     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[phlptp]

Would we want to suggest different defaults with this new configuration options?

[radimkrcmar]

That changes behavior (which will annoy users), so I tried to to be as conservative as possible.

If we accepted backward incompatibility, I'd much rather redefine the option to be an integer offset, so it wouldn't matter what is the width of the left column, and short options would by default be assumed to be single letter.

That is, I'd personally prefer if the default looks like this, regardless of what user set to column_width():

  -f, --foo
      --bar

[phlptp]

I don't really want to break API compatibility at this point, but maybe when we get to a 3.0 version. Also there is some possibility of short options being longer with the allowance for non-standard option names now.