Boost Program Options 'arg' text could be editiable.

[robertmassaioli@…]

I have a minor feature request and that is that when I write out a program option that has an argument it comes out, for example, like this:

  -m [ --log-file ] arg (=<none>)         set log file.

But that 'arg' does not look nice to me; I would rather that it read:

  -m [ --log-file ] <filename> (=<none>)         set log file.

And I would like to be able to set that somehow in the po::value setup. I also checked to see if you could do this already and it seems as though you cannot in the boost::program_options source code itself starting on line 67 of value_semantic.cpp there is the following lines:

BOOST_PROGRAM_OPTIONS_DECL std::string arg("arg");

std::string
untyped_value::name() const
{
    return arg;
}

So since 'arg' seems to be set in stone I do not think that it is possible to do this yet. I would really like to know if you think this is a good idea or not. Thanks.

[Vladimir Prus]

It does not seem to me that having the help output say that the value of "log-file" option is "<filename>" actually adds too much to user's understanding of the interface. This is precisely the reason why 'arg' is hardcoded, and I'm not planning on changing that.

[Jacobo de Vera <devel@…>]

Could you please reconsider? Having a named "arg" helps writing better help messages, making it easier to refer to the argument by name. Lots of well known programs take advantage of this in their help messages (ls, vim, emacs, gcc, to name a few). This is an example from gcc:

-B <directory>           Add <directory> to the compiler's search paths

The mention of a <directory> together with the B option makes it much easier to refer back to the option itself during its description, while keeping full semantics.

Perhaps support for this could be added as a new public member of boost::program_options::typed_value, so that the string to be output can be passed when new options are being specified:

 typed_value * metavar(const std::string &);

I'm using metavar only because that's the name I've seen for it in Python's optparse module, but it could very well be argname or whatever.

Thank you.

[Robert Massaioli]

I cannot vote for a post but I agree with what Jacobo said in terms of making it clearer and easier to understand in the help messages. I have learned to live with this but I still believe that this would be handy if we could change it from "arg".

[lukasz.dobrogowski@…]

I'm also voting for this. It would largely help with migration from existing commandline parsing systems in projects to boost::program_options with as little changes to syntax and usability as possible.

Example from Wesnoth: fragment of --help before PO: --preprocess, -p <file/folder> <target directory> (short description)

fragment of --help after using PO: -p [ --preprocess ] arg (long description, arg has to be explained in it and it isn't immediately visible that the option takes two tokens)

It's probably most useful for multitoken commands with custom validators, where it would really help usability to be able to explain needed arguments with string such as "<myarg1> <myarg2>"...

[Vladimir Prus]

I'd like to clarify that while I personally will not be working on this (that's the reason for the current 'wontfix' resolution), there appears to be popular demand, and therefore I will accept a patch to implement this feature, if said patch is OK technically.

[mathstuf@…]

Patch to add metavar method to typed_value

[mathstuf@…]

I attached a patch to add the metavar method as well as updating the name method to make use of it.

I haven't updated the documentation other than the comment in the code because I haven't found where to update it. I see the HTML under doc/html/program_options, but it seems like there'd be a more canonical place to change it.

[Leo Goodstadt <boost@…>]

I would like to add my support to this feature, having long patched my version of program_options to support this.

The text of "arg" is called "metavar" in the python optparse module, and opt_name in GNU genparse. I am very used to "metavar" from python but it is very obscure for non-python users.

"arg" is either the name of the argument/value for the option, or a placeholder for the argument/value for the option. In use, it is commonly the *type* of the argument.

So we have four choices: 1) metavar (from python) 2) argument_name | arg_name | option_value_name | value_name 3) argument_placeholder_name | arg_placeholder | value_placeholder 4) argument_type | arg_type

My preference is for something from (2).

[anonymous]

+1. This would be very useful for my project.

[Vladimir Prus]

I would prefer 'argument_name'. Does anybody want to argue for a different name, before I commit this patch?

[robertmassaioli@…]

No it looks good to me too and I also prefer 'argument_name' because it is says exactly what it means and maintains the 'arg' naming that has been used so far. Thank you very much for including this change and thank you mathstuf for writing it. I will be incorporating it in my code immediately. (Also a one line addition to the documentation is probably required but we know this already).

[Vladimir Prus]

(In [77931]) Allow to specify how option's value is named in help message.

Fixes #4781.

[anonymous]

I have decided to go with 'value_name', since essentially all of the code is using 'option' and 'value' terminology. The use of 'arg' as default help output can be though as bad idea -- which is not worth fixing, probably.

[Vladimir Prus]

(In [77932]) Merge: Allow to specify how option's value is named in help message.

Fixes #4781.

[TLBettens@…]

Warning introduced in release 1_50_0

Function set_option_name in class error_with_no_option_name was introduced into file .../boost_1_50_0/boost/program_options/errors.hpp causing Visual C++ version 10, perhaps others, to emit the following warning message when compiled with warning level 4 (/W4) enabled:

1>c:\boostbuilding\boost_1_50_0\boost\program_options\errors.hpp(253): warning C4100: 'option_name' : unreferenced formal parameter

Unused arguments should remain unnamed, and the workaround is something like this:

252:        /** Does NOT set option name, because no option name makes sense */
253:        virtual void set_option_name(const std::string& /* option_name */){}

[Vladimir Prus]

Thanks for the report. However, this is already fixed, on trunk and release branch, and should be fixed in 1.51 when it is released.

[pbf@…]

I'm encountering a problem, whereby I have a shared library that statically links to program_options, and an application that also statically links to it, but dynamically links to the shared library. When the program terminates, it tries to double delete the string "arg", causing potential heap corruption.

While I'm aware that this usage of boost violates the one definition rule, and is generally dangerous, I need to do it anyway..

I've managed to resolve the issue by patching my version of program_options with the following changes:

value_semantic.cpp

85:    BOOST_PROGRAM_OPTIONS_DECL char* arg = "arg";

value_semantic.hpp

13:    extern BOOST_PROGRAM_OPTIONS_DECL char* arg;
19:        const std::string var = (m_value_name.empty() ? arg : m_value_name);

I'd like to suggest this as a patch for the next release, since I'm sure I'm not the only one who's encountered this problem. (In fact, someone already did, last year in the boost Users forum)