[Boost-bugs] [Boost C++ Libraries] #8430: Positional arguments help output

Subject: [Boost-bugs] [Boost C++ Libraries] #8430: Positional arguments help output
From: Boost C++ Libraries (noreply_at_[hidden])
Date: 2013-04-11 18:42:59

#8430: Positional arguments help output
--------------------------------------+-------------------------------------
 Reporter:  vanboxem.ruben@…          |       Owner:  vladimir_prus  
     Type:  Feature Requests          |      Status:  new            
Milestone:  To Be Determined          |   Component:  program_options
  Version:  Boost 1.53.0              |    Severity:  Problem        
 Keywords:                            |  
--------------------------------------+-------------------------------------
 Currently, there is no way to output positional argument descriptions.
 This is however often useful as special values of these options may have
 special results.

 I originally asked the question on
 [http://stackoverflow.com/questions/15863056/how-to-display-commandline-

 operand-description-in-help-output Stackoverflow].

 Summarizing the question linked above, I'd like for this kind of output to
 be readily available:

 {{{
 cmp: compare two files
 Usage: cmp [ -l | -s ] file1 file2
 Options:
   --help                Show this help output.
   -l                    (Lowercase ell.) Write the byte number (decimal)
 and the differing bytes (octal) for each difference.
   -s                    Write nothing for differing files; return exit
 status only.
 Operands:
   file1                 A pathname of the first file to be compared. If
 file1 is '-', the standard input shall be used.
   file2                 A pathname of the second file to be compared. If
 file2 is '-', the standard input shall be used.
 }}}

 where file1 and file2 are pure positional arguments that have behavior
 warranting a full description.

 I propose a simple and backwards-compatible change to the way
 positional_argument_description works:

 {{{
 po::positional_options_description operands("operands");
 operands.add("file1", 1, "A pathname of the first file to be compared. If
 file1 is '-', the standard input shall be used.")
 operands.add("file2", 1, "A pathname of the second file to be compared. If
 file2 is '-', the standard input shall be used.");
 }}}

 1. Add an optional string argument to the constructor and store it like
 for normal program_descriptions
 2. Add a third optional argument containing the description string of the
 positional argument
 3. Provide an operator<< overload that would allow for formatted output
 like the above.

-- 
Ticket URL: <https://svn.boost.org/trac/boost/ticket/8430>
Boost C++ Libraries <http://www.boost.org/>
Boost provides free peer-reviewed portable C++ source libraries.