Format custom help message with configured column width by amirsojoodi · Pull Request #413 · jarro2783/cxxopts

amirsojoodi · 2023-12-03T21:58:09Z

Wrap the custom help message according to the column width.

This change is

jarro2783 · 2023-12-05T20:38:58Z

Can you write a unit test for this?

lazysegtree · 2025-12-27T05:20:09Z

@amirsojoodi Are you still working on this?

amirsojoodi · 2025-12-28T00:27:23Z

@lazysegtree I've forgotten about this. Give me some time, and I'll update

lazysegtree · 2025-12-29T18:40:41Z

test/options.cpp

+        "Custom message width A very very long description that \n  should "
+        "be wrapped according to the specified width for \n  help messages. "
+        "This is to ensure that lines are not very \n  long and remain "
+        "readable. Just to make sure we have \n  enough text here to trigger "
+        "the wrapping functionality \n  properly. Let's add a bit more text "
+        "to be certain!") != std::string::npos);


(0) Suggestion - Defining it like this will make the tests more readable and clear
Same for below

Suggested change

"Custom message width A very very long description that \n should "

"be wrapped according to the specified width for \n help messages. "

"This is to ensure that lines are not very \n long and remain "

"readable. Just to make sure we have \n enough text here to trigger "

"the wrapping functionality \n properly. Let's add a bit more text "

"to be certain!") != std::string::npos);

"Custom message width A very very long description that \n"

" should be wrapped according to the specified width for \n"

" help messages. This is to ensure that lines are not very \n"

" long and remain readable. Just to make sure we have \n"

" enough text here to trigger the wrapping functionality \n"

" properly. Let's add a bit more text "

"to be certain!") != std::string::npos);

I'll merge it with the formatting changes.

lazysegtree · 2025-12-30T03:08:58Z

While testing this I observed crash when there is a word that is bigger than the parameter passed to set_width.

I am gonna do a more thorough review and testing.

lazysegtree · 2025-12-30T06:56:57Z

include/cxxopts.hpp

    result += " " + toLocalString(m_custom_help);
+    result = format_custom_help(result, OPTION_DESC_GAP, m_width);


(1) @amirsojoodi This will fail in compilation for CXXOPTS_USE_UNICODE flag
For that we flag, we have using String = icu::UnicodeString;, and hence result here, will be of type icu::UnicodeString

format_custom_help only accepts std::string and wont allow icu::UnicodeString

Please fix that and ensure that we compile with that flag.

@jarro2783 We would need to fix the github CI, or we might cause regressions in the current code.
I hope we do test the compilation with CXXOPTS_USE_UNICODE in our CI

I am gonna give it a shot this weekend.

lazysegtree · 2025-12-30T07:04:56Z

include/cxxopts.hpp

+    throw_or_mimic<exceptions::invalid_option_format>("Allowed column" 
+      "width must be greater than start column width!");


(2) Typo
Missing concatanation of space in the error message
Should be

Suggested change

throw_or_mimic<exceptions::invalid_option_format>("Allowed column"

"width must be greater than start column width!");

throw_or_mimic<exceptions::invalid_option_format>("Allowed column "

"width must be greater than start column width!");

lazysegtree · 2025-12-30T07:08:41Z

include/cxxopts.hpp

+    }
+
+    // record the start of a word
+    word_size = (std::isspace(c)) ? 0 : word_size + 1;


(3) Please use bool isspace( CharT ch, const locale& loc )
Elsewhere in the library, we use locale specific checks. For example, check the usage of isalnum

lazysegtree · 2025-12-30T07:17:33Z

include/cxxopts.hpp

  return result;
 }

+String


(4) @amirsojoodi ~~the output sometimes contains extra unexpected lines that should not be appended~~

The output appends extra spaces when user gave only newlines.

options.custom_help("This is a multiline custom help\nLine2\n\nLine4");

I think, this should ideally show something like this

3 │ ····checker·This·is·a·multiline·custom·help␊ 4 │ ··Line2␊ 5 │ ␊ 6 │ ··Line4␊ 7 │ ␊

But its actually this right now

➜ ~/Workspace/Other_proj/cxxopts-amir/include git:(patch-2) ✗ [9:02:28] g++ main.cpp && ./a.out -h | bat --show-all --no-pager ───────┬─────────────────────────────────────────────────────────────────────────────────────────────── │ STDIN ───────┼─────────────────────────────────────────────────────────────────────────────────────────────── 1 │ ··Test·cxxopts␊ 2 │ ··Usage:␊ 3 │ ····checker·This·is·a·multiline·custom·help␊ 4 │ ··Line2␊ 5 │ ··␊ 6 │ ··Line4␊ 7 │ ␊ 8 │ ··-d,·--debug2·······01234567890123456789␊ 9 │ ··-i,·--integer·arg··Int·param␊ 10 │ ··-f,·--file·arg·····File·name␊ 11 │ ··-v,·--verbose······Verbose·output␊ 12 │ ··-h,·--help·········Print·usage␊ 13 │ ␊ ───────┴─────────────────────────────────────────────────────────────────────────────────────────────── ➜ ~/Workspace/Other_proj/cxxopts-amir/include git:(patch-2) ✗ [9:03:01]

This is almost unnoticeable to the user, but is a slightly unexepected behaviour in my opinion.

lazysegtree · 2025-12-30T07:21:47Z

include/cxxopts.hpp

  return result;
 }

+String


(5) If options.set_width is called with a low value like 10, and there is a word of greater length. THe program gets stuck in infinite loop.

There may be long URLs in the help, so we need to handle words of very long length

lazysegtree · 2025-12-30T07:24:28Z

test/options.cpp

  CHECK(options.help().find("test <posArg1>...<posArgN>") != std::string::npos);
 }
+
+TEST_CASE("Format custom message with selected width", "[help]")


(6) Test cases are lacking a lot of checks. Please ensure that they cover most of the issues above.

Please also include a test for throwing exceptions::invalid_option_format on setting too less width.

lazysegtree · 2025-12-30T07:26:52Z

include/cxxopts.hpp

+
+  if(allowed <= start)
+  {
+    throw_or_mimic<exceptions::invalid_option_format>("Allowed column" 


(7) With current code, the exception will only get thrown when users use -h, while the trigger was the user setting wrong value in options.set_width

The exception should be thrown at the time of set_width.

We should be throwing exceptions when users set an invalid configuration, not when they attempt to use that invalid config.
What do you think @jarro2783

# code with `options.set_width(1);` in main.cpp. # If users don't test -h, they will not know of the misconfig. ➜ ~/Workspace/Other_proj/cxxopts-amir/include git:(patch-2) ✗ [12:50:12] g++ main.cpp && ./a.out -h start Invalid option format 'Allowed columnwidth must be greater than start column width!' ➜ ~/Workspace/Other_proj/cxxopts-amir/include git:(patch-2) ✗ [12:54:39] g++ main.cpp && ./a.out start help = false (default) verbose = false (default) debug2 = false (default) ➜ ~/Workspace/Other_proj/cxxopts-amir/include git:(patch-2) ✗ [12:54:44]

I agree with that.

lazysegtree

@amirsojoodi Can you please fix comment 0-7. If some of them are not valid, and need further discussion, let me know.

lazysegtree · 2026-01-01T03:45:51Z

include/cxxopts.hpp

  if (!m_custom_help.empty())
  {
    result += " " + toLocalString(m_custom_help);
+    result = format_custom_help(result, OPTION_DESC_GAP, m_width);


(8) At this point, you are formatting the entire results that also contains Main program help -> m_help_string .

Since your function is named format_custom_help, I think that is not the intention here. You only intend to format the custom help part.

Right now even the main help is getting formatted.

cxxopts::Options options("checker", "Test cxxopts with a very very very very very long program description"); options.custom_help(" 123456789 123456789 123456789 123456789 123456789"); options.add_options() ("h,help", "Print usage") ; options.set_width(30);

➜ ~/Workspace/Other_proj/cxxopts-amir/include git:(patch-2) ✗ [9:12:01] g++ main.cpp && ./a.out -h | bat --show-all --no-pager ───────┬─────────────────────────────────────────────────────────────────────────────────────────────── │ STDIN ───────┼─────────────────────────────────────────────────────────────────────────────────────────────── 1 │ ··Test·cxxopts·with·a·very·␊ 2 │ ··very·very·very·very·long·␊ 3 │ ··program·description␊ 4 │ ··Usage:␊ 5 │ ····checker··123456789·␊ 6 │ ··123456789·123456789·␊ 7 │ ··123456789·123456789␊ 8 │ ␊ 9 │ ··-h,·--help··Print·usage␊ 10 │ ␊ ───────┴─────────────────────────────────────────────────────────────────────────────────────────────── ➜ ~/Workspace/Other_proj/cxxopts-amir/include git:(patch-2) ✗ [9:14:48]

So either you should only format the custom help part, or use the function irrespective of m_custom_help being empty or not, and name it to wrap_help or something generic.

@jarro2783 What do you think our output should be in this case

cxxopts::Options options("checker", "Test cxxopts with a very very very very very long program description"); options.custom_help(" 123456789 123456789 123456789 123456789 123456789"); options.add_options() ("h,help", "Print usage"); options.set_width(30);

(a) This

1 │ ··Test·cxxopts·with·a·very·␊ 2 │ ··very·very·very·very·long·␊ 3 │ ··program·description␊ 4 │ ··Usage:␊ 5 │ ····checker··123456789·␊ 6 │ ··123456789·123456789·␊ 7 │ ··123456789·123456789␊ 8 │ ␊ 9 │ ··-h,·--help··Print·usage␊ 10 │ ␊

(b) Or this

1 │ Test·cxxopts·with·a·very·very·very·very·very·long·program·description␊ 2 │ Usage:␊ 3 │ ··checker····123456789·123456789·␊ 4 │ ··123456789·123456789·␊ 5 │ ··123456789␊ 6 │ ␊ 7 │ ··-h,·--help··Print·usage␊ 8 │ ␊

jarro2783 · 2026-01-01T04:43:00Z

I think it would be more intuitive that all of the help gets formatted when you call set_width.

jarro2783 · 2026-01-01T05:10:15Z

If you rebase on master we will have working CI now.

amirsojoodi · 2026-01-20T05:16:05Z

Sorry for the delay in getting back to this.
Unfortunately, I cannot work on this PR anymore due to my new employment agreement, unless I have it approved by the compliance team. It will take a long time, so I have to delegate this to someone else. Sorry about that.

jarro2783 · 2026-01-23T06:43:14Z

I might be able to fix this up.

jarro2783 · 2026-02-02T20:16:58Z

I probably can't push to the original branch in the author's fork. So I'm going to have to close this PR and reopen a new one anyway. This is a bit more work than I thought to get the edge cases covered, so it's lower priority for me right now.

amirsojoodi force-pushed the patch-2 branch 2 times, most recently from a638577 to 3945f84 Compare December 29, 2025 03:56

amirsojoodi added 2 commits December 29, 2025 01:23

Format custom help message with configured column width

ae1c3ca

Add unit test for customized width for help

2f7f449

amirsojoodi force-pushed the patch-2 branch from 3945f84 to 2f7f449 Compare December 29, 2025 06:24

lazysegtree reviewed Dec 29, 2025

View reviewed changes

lazysegtree reviewed Dec 30, 2025

View reviewed changes

lazysegtree suggested changes Dec 30, 2025

View reviewed changes

lazysegtree reviewed Jan 1, 2026

View reviewed changes

This was referenced Jan 7, 2026

Add Meson buildsystem support #424

Merged

options test fails with SIGTRAP on macOS / arm64 #431

Open

Issue management #483

Open

jarro2783 added the Pending on author label Jan 19, 2026

		result += " " + toLocalString(m_custom_help);
		result = format_custom_help(result, OPTION_DESC_GAP, m_width);

		throw_or_mimic<exceptions::invalid_option_format>("Allowed column"
		"width must be greater than start column width!");

Conversation

amirsojoodi commented Dec 3, 2023 • edited by jarro2783 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jarro2783 commented Dec 5, 2023

Uh oh!

lazysegtree commented Dec 27, 2025

Uh oh!

amirsojoodi commented Dec 28, 2025

Uh oh!

lazysegtree Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lazysegtree commented Dec 30, 2025

Uh oh!

lazysegtree Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lazysegtree Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lazysegtree Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lazysegtree Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lazysegtree Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lazysegtree Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lazysegtree left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lazysegtree Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jarro2783 commented Jan 1, 2026

Uh oh!

jarro2783 commented Jan 1, 2026

Uh oh!

amirsojoodi commented Jan 20, 2026

Uh oh!

jarro2783 commented Jan 23, 2026

Uh oh!

jarro2783 commented Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

amirsojoodi commented Dec 3, 2023 •

edited by jarro2783

Loading

lazysegtree Dec 29, 2025 •

edited

Loading

lazysegtree Dec 30, 2025 •

edited

Loading

lazysegtree Dec 30, 2025 •

edited

Loading

lazysegtree Dec 30, 2025 •

edited

Loading

lazysegtree Dec 30, 2025 •

edited

Loading

lazysegtree Dec 30, 2025 •

edited

Loading

lazysegtree Dec 30, 2025 •

edited

Loading

lazysegtree left a comment •

edited

Loading

lazysegtree Jan 1, 2026 •

edited

Loading