Main   Classes   Namespace members   Examples   Recipes   Rationale   Related pages

boost::program_options::cmdline Class Reference

Command line parser class. More...

#include <cmdline.hpp>

Collaboration diagram for boost::program_options::cmdline:

Collaboration graph
[legend]
List of all members.

Public Types

enum  style_t {
  allow_long = 1, allow_short = allow_long << 1, allow_dash_for_short = allow_short << 1, allow_slash_for_short = allow_dash_for_short << 1,
  long_allow_adjacent = allow_slash_for_short << 1, long_allow_next = long_allow_adjacent << 1, short_allow_adjacent = long_allow_next << 1, short_allow_next = short_allow_adjacent << 1,
  allow_sticky = short_allow_next << 1, allow_guessing = allow_sticky << 1, case_insentitive = allow_guessing << 1, allow_long_disguise = case_insentitive << 1,
  unix_style, default_style = unix_style
}
 Various possible styles of options. More...


Public Member Functions

 cmdline (const std::vector< std::string > &args, int style, bool allow_unregistered=false)
 Constructs a command line parser for (argc, argv) pair.

 cmdline (int argc, const char *const *argv, int style, bool allow_unregistered=false)
void set_additional_parser (additional_parser p)
 Set additional parser.

void add_option (const std::string &long_name, char short_name, char properties= '|', int index=0)
 Registers a new option.

void add_option (const char *long_name, char short_name, char properties= '|', int index=0)
bool at_option () const
 Tells if the current element is option.

bool at_argument () const
 Tells if the current element is argument.

const std::string & option_name () const
 Returns the option name.

int option_index () const
 Returns the index for the current option.

const std::string & raw_option_name () const
 Returns the option name as found on the command line.

const std::string & option_value () const
 Returns the first of option values.

const std::vector< std::string > & option_values () const
 Returns all option values.

const std::string & argument () const
 Returns the argument.

const std::vector< std::string > & arguments () const
 Returns all arguments read by this command line parser.

const std::string & last () const
 Returns the token that was current by the time 'operator++' was invoked the last time.


Private Types

enum  properties_t { , allow_parameter, require_parameter, allow_parameters, require_parameters }
enum  
enum  
enum  
enum  

Private Member Functions

properties_t translate_property (char p)
 Converts parameter property character into enum value.

void clear_error ()
 Clears all error state.


Detailed Description

Command line parser class.

Main requirements were:

First all options are registered. After that, elements of command line are extracted using operator++.

For each element, user can find

Sometimes the registered option name is not equal to the encountered one, for example, because name abbreviation is supported. Therefore two option names can be obtained:

There are lot of style options, which can be used to tune the command line parsing. In addition, it's possible to install additional parser which will process custom option styles.

Todo:
mininal match length for guessing?


Member Enumeration Documentation

enum boost::program_options::cmdline::style_t
 

Various possible styles of options.

There are "long" options, which start with "--" and "short", which start with either "-" or "/". Both kinds can be allowed or disallowed, see allow_long and allow_short. The allowed character for short option is also configurable.

Option's value can be specified in the same token as value ("--foo=bar"), or in the next token.

It's possible to introduce long option by the same character as long option, see allow_long_disguise.

Finally, guessing (specifying only prefix of option) and case insensitive processing are supported.

Enumeration values:
allow_long  Allow "--long_name" style.
allow_short  Alow "-<single character" style.
allow_dash_for_short  Allow "-" in short options.
allow_slash_for_short  Allow "/" in short options.
long_allow_adjacent  Allow option parameter in the same token for long option, like in.

                --foo=10
                
long_allow_next  Allow option parameter in the same token for long options.
short_allow_adjacent  Allow option parameter in the same token for short options.
short_allow_next  Allow option parameter in the next token for short options.
allow_sticky  Allow to merge several short options together, so that "-s -k" become "-sk".

All of the options but last should accept no parameter. For example, if "-s" accept a parameter, then "k" will be taken as parameter, not another short option. Dos-style short options cannot be sticky.

allow_guessing  Allow abbreviated spellings for long options, if they unambiguously identify long option.

No long option name should be prefix of other long option name is guessing is in effect.

case_insentitive  Ignore the difference in case for options.

Todo:
Should this apply to long options only?
allow_long_disguise  Allow long options with single option starting character, e.g -foo=10.
unix_style  The more-or-less traditional unix style.
default_style  The default style.

enum boost::program_options::cmdline::properties_t [private]
 

Enumeration values:
allow_parameter  0 or 1 parameter
require_parameter  exactly 1 parameter
allow_parameters  0 or more parameters
require_parameters  1 or more parameters


Constructor & Destructor Documentation

boost::program_options::cmdline::cmdline const std::vector< std::string > &    args,
int    style,
bool    allow_unregistered = false
 

Constructs a command line parser for (argc, argv) pair.

Uses style options passed in 'style', which should be binary or'ed values of style_t enum. It can also be zero, in which case a "default" style will be used. If 'allow_unregistered' is true, then allows unregistered options. They will be assigned index 1 and are assumed to have optional parameter.

boost::program_options::cmdline::cmdline int    argc,
const char *const *    argv,
int    style,
bool    allow_unregistered = false
 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.


Member Function Documentation

void boost::program_options::cmdline::set_additional_parser additional_parser    p
 

Set additional parser.

This will be called for each token of command line. If first string in pair is not empty, then the token is considered matched by this parser, and the first string will be considered an option name (which can be long or short), while the second will be option's parameter (if not empty). Note that additional parser can match only one token.

void boost::program_options::cmdline::add_option const std::string &    long_name,
char    short_name,
char    properties = '|',
int    index = 0
 

Registers a new option.

Parameters:
long_name Long name to use. When ending '*', symbols up to it give an allowed prefix -- all options starting with it will be allowed. The first character may not be '-'. Empty string means no long name.
short_name Short name to use. Value of '' means no short name.
properties Tell about possible parameters '|' -- no parameter '?' -- optional parameter ':' -- required parameter '*' -- 0 or more parameters '+' -- 1 or more parameters
index A distinguishing value for the option. The index will be returned by 'next' member function. Indices need not be unqiue -- e.g. client can set all indices to 0, and use string value to recognize options.

void boost::program_options::cmdline::add_option const char *    long_name,
char    short_name,
char    properties = '|',
int    index = 0
 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool boost::program_options::cmdline::at_option   const
 

Tells if the current element is option.

bool boost::program_options::cmdline::at_argument   const
 

Tells if the current element is argument.

const string & boost::program_options::cmdline::option_name   const
 

Returns the option name.

If there's long option name associated with this option, it is returned, even if short name was used in command line. Otherwise, the short name given to 'add_option' is returned with '-' prepended. For purposes of simplicity, '-' is used even when dos-style short option was found.

int boost::program_options::cmdline::option_index   const
 

Returns the index for the current option.

const string & boost::program_options::cmdline::raw_option_name   const
 

Returns the option name as found on the command line.

Any symbols that introduce the option, or delimit its parameter will be stripped. This function allows to work with allowed prefixes, in which case 'option_name' will return the prefix specification, and full option name should be queried explicitly.

const string & boost::program_options::cmdline::option_value   const
 

Returns the first of option values.

If there's more than one option throws multiple_values. If there are no options, returns empty string.

const std::vector< std::string > & boost::program_options::cmdline::option_values   const
 

Returns all option values.

const string & boost::program_options::cmdline::argument   const
 

Returns the argument.

const vector< string > & boost::program_options::cmdline::arguments   const
 

Returns all arguments read by this command line parser.

const string & boost::program_options::cmdline::last   const
 

Returns the token that was current by the time 'operator++' was invoked the last time.

cmdline::properties_t boost::program_options::cmdline::translate_property char    p [private]
 

Converts parameter property character into enum value.

void boost::program_options::cmdline::clear_error   [private]
 

Clears all error state.

If there were an error, throws appripriate exception.


The documentation for this class was generated from the following files:
Generated on 23 May 2003 with
doxygen