Boost C++ Libraries: Ticket #4781: Boost Program Options 'arg' text could be editiable.

status changed; resolution set

Vladimir Prus — Sat, 08 Jan 2011 10:35:16 GMT

status new → closed
resolution → wontfix

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.

Mon, 07 Feb 2011 01:42:27 GMT

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 — Mon, 07 Feb 2011 02:08:29 GMT

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@… — Wed, 08 Jun 2011 19:34:59 GMT

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 — Wed, 08 Jun 2011 19:37:52 GMT

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.

attachment set

mathstuf@… — Fri, 04 Nov 2011 17:19:10 GMT

attachment → 0001-Add-support-for-a-metavar-in-typed_value.patch

Patch to add metavar method to typed_value

status changed; resolution deleted

mathstuf@… — Fri, 04 Nov 2011 17:21:15 GMT

status closed → reopened
resolution wontfix

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.

Mon, 14 Nov 2011 01:33:22 GMT

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.

My preference is for something from (2).

anonymous — Wed, 14 Dec 2011 12:34:56 GMT

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

Vladimir Prus — Sun, 08 Apr 2012 09:22:10 GMT

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

robertmassaioli@… — Sun, 08 Apr 2012 09:28:31 GMT

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).

status changed; resolution set

Vladimir Prus — Thu, 12 Apr 2012 08:37:40 GMT

status reopened → closed
resolution → fixed

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

Fixes #4781.

anonymous — Thu, 12 Apr 2012 09:18:55 GMT

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 — Thu, 12 Apr 2012 09:40:39 GMT

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

Fixes #4781.

TLBettens@… — Sat, 18 Aug 2012 21:49:15 GMT

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 — Sun, 19 Aug 2012 07:26:46 GMT

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@… — Thu, 13 Dec 2012 07:36:29 GMT

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)