Modify

Ticket #4781 (closed Feature Requests: fixed)

Opened 3 years ago

Last modified 16 months ago

Boost Program Options 'arg' text could be editiable.

Reported by: robertmassaioli@… Owned by: vladimir_prus
Milestone: To Be Determined Component: program_options
Version: Boost 1.44.0 Severity: Problem
Keywords: arg program_options Cc:

Description

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.

Attachments

0001-Add-support-for-a-metavar-in-typed_value.patch Download (2.8 KB) - added by mathstuf@… 2 years ago.
Patch to add metavar method to typed_value

Change History

comment:1 Changed 3 years ago by vladimir_prus

  • Status changed from new to closed
  • Resolution set to 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.

comment:2 Changed 3 years ago by 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.

comment:3 Changed 3 years ago by 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".

comment:4 Changed 3 years ago by 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>"...

comment:5 Changed 3 years ago by 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.

Changed 2 years ago by mathstuf@…

Patch to add metavar method to typed_value

comment:6 Changed 2 years ago by mathstuf@…

  • Status changed from closed to reopened
  • Resolution wontfix deleted

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.

comment:7 Changed 2 years ago by 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).

comment:8 Changed 2 years ago by anonymous

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

comment:9 Changed 2 years ago by vladimir_prus

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

comment:10 Changed 2 years ago by 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).

comment:11 Changed 2 years ago by vladimir_prus

  • Status changed from reopened to closed
  • Resolution set to fixed

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

Fixes #4781.

comment:12 Changed 2 years ago by 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.

comment:13 Changed 2 years ago by vladimir_prus

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

Fixes #4781.

comment:14 Changed 20 months ago by 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 */){}

comment:15 Changed 20 months ago by 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.

comment:16 Changed 16 months ago by 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)

View

Add a comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
The resolution will be deleted. Next status will be 'reopened'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.