Custom description for built-in options

[SirNickolas]

Hello. I’ve just discovered this project, and I think it’s the best approach to CLI for a statically-typed language.

There are a few aspects in the description of the built-in options (--help, --help-syntax, and --version) that I disliked, though. Namely, they

1. start with a lowercase letter;
2. do not end with a period;
3. lack a space after commas;
4. use two periods for ellipsis instead of three. (Not using the dedicated character—U+2026—is fine since the program might be run from a terminal that doesn’t support Unicode.)

I checked the source, and it seems the messages are hard-coded instead of being taken from a parameter or a field of an object.

https://github.com/c-blake/cligen/blob/34b21db967a1a24d700e101ee1f30cc6db862d63/cligen.nim#L426-L434

Then I thought I could somehow inhibit generation of standard messages and provide my own instead, but when I tried to pass help = {"help": "Print this help message."}, it complained that main doesn’t have a parameter named help. Moreover, it is forbidden for main to have one, so I cannot even call cligenHelp manually upon encountering --help.

I’m out of ideas now. Could you help me, please?

I found this comment where you said:

I am aware that "help" and "helpsyntax" theoretically have the same problem, but both seem less likely to collide in practice and serve a more critical internal function.

Does that mean there is no way to customize them?

[c-blake]

First, thanks for searching through the GH issues/comments. That always saves time.

By way of explanation, help and helpsyntax are kind of like "keywords" for the system, and the reason the messages are short is to minimize terminal width space for programs.

Does that mean there is no way to customize them?

Correct. We can add a way to customize them. My inclination is always to do what "people would have thought to try first" which in this case is take them from the per-parameter help table.

[c-blake]

A related feature request for very picky message formatter type folks might be to have the entire printed help table also take its "order" from the help={...} table. I believe right now it takes its order from the wrapped proc signature.

[SirNickolas]

My inclination is always to do what "people would have thought to try first" which in this case is take them from the per-parameter help table.

Indeed. By the way, ClCfg.helpSyntax can be superseded by it then.

to have the entire printed help table also take its "order" from the help={...} table.

I was thinking it does just that but haven’t checked yet. Yes, it would be more intuitive to take them from the table. However, it’s less of significance because we can always reorder proc’s parameters or at least make a trampoline.

[c-blake]

Well, ClCfg.helpSyntax is really about binding syntaxHelp - the output you get from invoking with --help-syntax, but I do dual-purpose that being empty string as a signal to not include it in the printed help table at all. That said, with this new feature, I might be able to also have an empty string help (i.e. help={"help-syntax": ""} be another way to specify no row for help-syntax in the printed help table). That's how you would ordinarily "hide" a row.

[SirNickolas]

You are still not able to customize version without processing it completely on your own.

Also, if you both set clCfg.version and provide version parameter in your function, it will be documented twice. Not sure if this should be considered a bug or not.

Upd.: help and help-syntax have no type nor default value, but version has them (bool false), which is a bit inconsistent.

[c-blake]

Re: customizing version param descrip -- working on it. Almost done. Just have to get help={"version": ""} suppressing the help row.

I don't see trapping both setting of version and providing a version parameter as useful/something which should be supported. So, that doesn't seem like a bug I should fix.

I had thought because of some people processing --version on their own that they should be able to choose its type (e.g. it might take a short/long parameter for simple 1.2.3 vs gory details with maybe dates or whatever), and with that non-standardized it should be left open. So, that flexibility seemed worth the inconsistency. Also, they are kind of different as the output version is a CLauthor provided string (though I do let CLusers hack syntaxHelp). Anyway, consistency alone is not a strong argument here.

[c-blake]

It should work now. I misspoke above, not empty string ("") but rather "CLIGEN-NOHELP" (or whatever clCfg.hTabSuppress is set to) is the magic string to suppress a help row. { In my defense, I think it used to be empty string in days long past. :-) } But now that should work the same way for all 3 builtin options as well as API/user options.

BTW, another way in which --version is different is that it is not present by default. Most of my own programs do not have it at all.