MOAB: Mesh Oriented datABase  (version 5.2.1)
CLArgs Class Reference

Parse command-line arguments. More...

#include <CLArgs.hpp>

+ Collaboration diagram for CLArgs:

Classes

class  ArgIBase
 Base class for callback interface (type-independent functions) More...
class  ArgListTemplate
 Trivial implementation for type-specific classes. More...
class  ArgTemplate
 Trivial implementation for type-specific classes. More...
class  ArgTemplateI
 Interface for type-specific callback classes. More...
class  DoubleListRangeArg
 Double list argument constrained to a range of valid values. More...
class  DoubleRange
class  DoubleRangeArg
 Double argument constrained to a range of valid values. More...
class  IntListRangeArg
 Integer list argument constrained to a range of valid values. More...
class  IntRange
class  IntRangeArg
 Integer argument constrained to a range of valid values. More...
class  KeyWordArg
 String arugment that is limited to a list of acceptable keywords. More...

Public Types

typedef ArgTemplateI< std::string > StringArgI
 Callback API for a string argument.
typedef ArgTemplateI< int > IntArgI
 Callback API for an integer argument.
typedef ArgTemplateI< long > LongArgI
 Callback API for a long integer argument.
typedef ArgTemplateI< double > DoubleArgI
 Callback API for a double-precision floating-point argument.
typedef ArgTemplateI< bool > ToggleArgI
 Callback API for a Boolean or toggle argument.
typedef ArgTemplateI
< std::vector< int > > 
IntListArgI
 Callback API for an integer list argument.
typedef ArgTemplateI
< std::vector< double > > 
DoubleListArgI
 Callback API for a double list argument.
typedef ArgTemplate< std::string > StringArg
 Trivial callback implementation for a string argument.
typedef ArgTemplate< int > IntArg
 Trivial callback implementation for an integer argument.
typedef ArgTemplate< long > LongArg
 Trivial callback implementation for a long integer argument.
typedef ArgTemplate< double > DoubleArg
 Trivial callback implementation for a ouble-precision floating-point argument.
typedef ArgTemplate< bool > ToggleArg
 Trivial callback implementation for a Boolean or toggle argument.
typedef ArgListTemplate< int > IntListArg
 Trivial callback implementation for an integer list argument.
typedef ArgListTemplate< double > DoubleListArg
 Trivial callback implementation for a double list argument.

Public Member Functions

 CLArgs (const char *progname, const char *brief_desc, const char *desc)
 Define basic program.
 ~CLArgs ()
bool is_flag_available (char fl) const
 Check if flag is undefined.
bool str_flag (char fl, const char *name, const char *desc, StringArgI *callback)
 Register a flag that requires a string argument.
bool int_flag (char fl, const char *name, const char *desc, IntArgI *callback)
 Register a flag that requires an integer argument.
bool long_flag (char fl, const char *name, const char *desc, LongArgI *callback)
 Register a flag that requires an integer argument.
bool double_flag (char fl, const char *name, const char *desc, DoubleArgI *callback)
 Register a flag that requires a real umber argument.
bool toggle_flag (char on_flag, char off_flag, const char *desc, ToggleArgI *callback)
 Register a pair of flags that accept no arguments and have opposing affects.
bool toggle_flag (char fl, const char *desc, ToggleArgI *callback)
 Register a flag with no value.
bool id_list_flag (char fl, const char *desc, IntListArgI *callback)
 Register a flag that accepts a list of positive integer arguments.
bool int_list_flag (char fl, const char *desc, IntListArgI *callback)
 Register a flag that requires a comma-separated list of integer values.
bool double_list_flag (char fl, const char *desc, DoubleListArgI *callback)
 Register a flag that requires a comma-separated list of double values.
bool limit_list_flag (char fl, int num_values, const char *const *value_names)
 Set a limit on the number of values accepted for a list-type flag. May be called multiple times for a flag.
void add_required_arg (const char *name)
 Specify that an argument without a flag is expected.
void add_optional_arg (const char *name)
bool parse_options (int argc, char *argv[], std::vector< std::string > &args_out, std::ostream &error_stream)
 Parse argument list.
void print_help (std::ostream &stream) const
 Write help.
void print_man_page (std::ostream &stream) const
 Write UNIX man page.
void print_usage (std::ostream &stream) const
 prinint usage (brief help)

Private Attributes

CLArgImplimpl

Detailed Description

Parse command-line arguments.

This class provides a mechanism for parsing and to some extend validating command-line arguments. Use of this class can be divided into three steps:

1) Call *_flag and arg methods to define acceptable command line arguments

2) Call parse_options to parse the command line arguments according to acceptable flags defined in step 1.

3) Check the values in registerd callback class instances.

The '-h' flag is reserved for reqesting a description of the allowable arguments (help). If it is encountered inside parse_options, the help will be printed and the program will be terminated w/out returning from parse_options.

The '-M' flag is similar to '-h', except that the help is written in UNIX 'man page' format.

Definition at line 64 of file CLArgs.hpp.


Member Typedef Documentation

typedef ArgTemplate< double > CLArgs::DoubleArg

Trivial callback implementation for a ouble-precision floating-point argument.

Definition at line 202 of file CLArgs.hpp.

typedef ArgTemplateI< double > CLArgs::DoubleArgI

Callback API for a double-precision floating-point argument.

Definition at line 187 of file CLArgs.hpp.

Trivial callback implementation for a double list argument.

Definition at line 208 of file CLArgs.hpp.

typedef ArgTemplateI< std::vector< double > > CLArgs::DoubleListArgI

Callback API for a double list argument.

Definition at line 193 of file CLArgs.hpp.

typedef ArgTemplate< int > CLArgs::IntArg

Trivial callback implementation for an integer argument.

Definition at line 198 of file CLArgs.hpp.

typedef ArgTemplateI< int > CLArgs::IntArgI

Callback API for an integer argument.

Definition at line 183 of file CLArgs.hpp.

Trivial callback implementation for an integer list argument.

Definition at line 206 of file CLArgs.hpp.

typedef ArgTemplateI< std::vector< int > > CLArgs::IntListArgI

Callback API for an integer list argument.

Definition at line 191 of file CLArgs.hpp.

typedef ArgTemplate< long > CLArgs::LongArg

Trivial callback implementation for a long integer argument.

Definition at line 200 of file CLArgs.hpp.

typedef ArgTemplateI< long > CLArgs::LongArgI

Callback API for a long integer argument.

Definition at line 185 of file CLArgs.hpp.

typedef ArgTemplate< std::string > CLArgs::StringArg

Trivial callback implementation for a string argument.

Definition at line 196 of file CLArgs.hpp.

typedef ArgTemplateI< std::string > CLArgs::StringArgI

Callback API for a string argument.

Definition at line 181 of file CLArgs.hpp.

typedef ArgTemplate< bool > CLArgs::ToggleArg

Trivial callback implementation for a Boolean or toggle argument.

Definition at line 204 of file CLArgs.hpp.

Callback API for a Boolean or toggle argument.

Definition at line 189 of file CLArgs.hpp.


Constructor & Destructor Documentation

CLArgs::CLArgs ( const char *  progname,
const char *  brief_desc,
const char *  desc 
)

Define basic program.

Parameters:
prognameThe program name
brief_descA brief description of the purpose of the program.
descProgram description for documentation.

Definition at line 238 of file CLArgs.cpp.

References impl.

{
    impl = new CLArgImpl( progname, brief, desc );
}

Definition at line 243 of file CLArgs.cpp.

References impl.

{
    delete impl;
}

Member Function Documentation

void CLArgs::add_optional_arg ( const char *  name)

Definition at line 322 of file CLArgs.cpp.

References CLArgImpl::add_opt_arg(), and impl.

Referenced by main().

void CLArgs::add_required_arg ( const char *  name)

Specify that an argument without a flag is expected.

Arguments are parsed in the order they are added, with the exception that all optional args are parsed after all required args.

Parameters:
name'name' of argument to display in help (e.g. "output_file");

Definition at line 317 of file CLArgs.cpp.

References CLArgImpl::add_req_arg(), and impl.

Referenced by main().

bool CLArgs::double_flag ( char  fl,
const char *  name,
const char *  desc,
CLArgs::DoubleArgI callback 
)

Register a flag that requires a real umber argument.

Define a flag of the form "-f <double>".

Parameters:
flThe character for the flag.
nameThe name of the flag argument
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
inclusiveIf true, accept 'min' or 'max': [min,max]. If false, reject 'min' and 'max' values: (min,max).
Returns:
false if flag is already in use, true otherwise.

Definition at line 271 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

Referenced by main().

{
    if( !is_flag_available( fl ) ) return false;
    return impl->add_flag( new CLArgDouble( fl, name, desc, callback ) );
}
bool CLArgs::double_list_flag ( char  fl,
const char *  desc,
CLArgs::DoubleListArgI callback 
)

Register a flag that requires a comma-separated list of double values.

Define a flag that has an double list for its arguments. The values must be specified as a comma-separated list.

Use 'limit_list_flag' to limit the number of values accepted in the argument. If 'limit_list_flag' is never called, any number of argument values will be accepted.

Parameters:
flThe character for the flag.
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
Returns:
false if flag is already in use, true otherwise.

Definition at line 305 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

Referenced by add_domain_args(), and main().

{
    if( !is_flag_available( fl ) ) return false;
    return impl->add_flag( new CLArgDoubleList( fl, desc, callback ) );
}
bool CLArgs::id_list_flag ( char  fl,
const char *  desc,
CLArgs::IntListArgI callback 
)

Register a flag that accepts a list of positive integer arguments.

Define a flag that accepts a list of ranges of positive integer values separated by commas. A zero value is rejected. Ranges can be either a single value or pair of values separated by a dash. For example: "-f 1,4-10,2,20-25".

Use 'get_int_list' to query values of flag.

Parameters:
flThe character for the flag.
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
Returns:
false if flag is already in use, true otherwise.

Definition at line 293 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

{
    if( !is_flag_available( fl ) ) return false;
    return impl->add_flag( new CLArgIDList( fl, desc, callback ) );
}
bool CLArgs::int_flag ( char  fl,
const char *  name,
const char *  desc,
CLArgs::IntArgI callback 
)

Register a flag that requires an integer argument.

Define a flag of the form "-f <int>".

Parameters:
flThe character for the flag.
nameThe name of the flag argument
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
Returns:
false if flag is already in use, true otherwise.

Definition at line 259 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

Referenced by main().

{
    if( !is_flag_available( fl ) ) return false;
    return impl->add_flag( new CLArgInt( fl, name, desc, callback ) );
}
bool CLArgs::int_list_flag ( char  fl,
const char *  desc,
CLArgs::IntListArgI callback 
)

Register a flag that requires a comma-separated list of integer values.

Define a flag that has an integer list for its arguments. The integers must be specified as a comma-separated list.

Use 'limit_list_flag' to limit the number of values accepted in the argument. If 'limit_list_flag' is never called, any number of argument values will be accepted.

Parameters:
flThe character for the flag.
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
Returns:
false if flag is already in use, true otherwise.

Definition at line 299 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

{
    if( !is_flag_available( fl ) ) return false;
    return impl->add_flag( new CLArgIntList( fl, desc, callback ) );
}
bool CLArgs::is_flag_available ( char  fl) const

Check if flag is undefined.

Definition at line 248 of file CLArgs.cpp.

References CLArgImpl::find_flag(), HELP_FLAG, impl, and MAN_FLAG.

Referenced by double_flag(), double_list_flag(), id_list_flag(), int_flag(), int_list_flag(), long_flag(), str_flag(), and toggle_flag().

{
    return ( fl != HELP_FLAG ) && ( fl != MAN_FLAG ) && !( impl->find_flag( fl ) );
}
bool CLArgs::limit_list_flag ( char  fl,
int  num_values,
const char *const *  value_names 
)

Set a limit on the number of values accepted for a list-type flag. May be called multiple times for a flag.

Add a limit on the number of values accepted for a list-type flag. This function may be called multiple times if the flag should accept a finite set of different arugment value counts.

Parameters:
flThe flag
num_valuesThe number of values to accept
value_namesAn array of 'num_value' strings specifying the name of each value.
Returns:
false if flag is not defined as a list-type flag or this method has already been called with the same flag AND number of values. True otherwise.

Definition at line 311 of file CLArgs.cpp.

References CLArgFlag::add_set(), CLArgImpl::find_flag(), and impl.

Referenced by add_domain_args(), and main().

{
    CLArgFlag* f = impl->find_flag( fl );
    return f ? f->add_set( num_values, value_names ) : false;
}
bool CLArgs::long_flag ( char  fl,
const char *  name,
const char *  desc,
CLArgs::LongArgI callback 
)

Register a flag that requires an integer argument.

Define a flag of the form "-f <int>".

Parameters:
flThe character for the flag.
nameThe name of the flag argument
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
Returns:
false if flag is already in use, true otherwise.

Definition at line 265 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

{
    if( !is_flag_available( fl ) ) return false;
    return impl->add_flag( new CLArgLong( fl, name, desc, callback ) );
}
bool CLArgs::parse_options ( int  argc,
char *  argv[],
std::vector< std::string > &  args_out,
std::ostream &  error_stream 
)

Parse argument list.

Parameters:
argcThe argument list length passed to the main() routine. The first value is assumed to be the executable name. This this value must be at least 1.
argvThe argument list as passed to main().
args_outThe list of non-flag arguments encountered, as defined by the 'args' method. If the 'args' method has not been called, no non-flag arguments are accepted and this list will be empty.
error_streamstream to which to write error messages.
Returns:
true if all arguments were accepted. false otherwise.

Definition at line 327 of file CLArgs.cpp.

References CLArgImpl::add_parsed_arg(), CLArgImpl::find_flag(), CLArgFlag::flag(), CLArgImpl::get_args(), CLArgImpl::have_required_args(), HELP_FLAG, impl, CLArgFlag::is_toggle(), MAN_FLAG, CLArgFlag::parse(), print_help(), and print_man_page().

Referenced by main().

{
    std::vector< CLArgFlag* > pending;
    bool no_more_flags = false;
    for( int i = 1; i < argc; ++i )
    {
        if( !pending.empty() )
        {
            CLArgFlag* flag = pending.front();
            pending.erase( pending.begin() );
            if( !flag->parse( argv[i] ) )
            {
                error_stream << argv[0] << ": invalid value for flag: -" << flag->flag() << " \"" << argv[i] << '"'
                             << std::endl;
                return false;
            }
        }
        else if( !no_more_flags && argv[i][0] == '-' && argv[i][1] != '\0' )
        {
            for( int j = 1; argv[i][j]; ++j )
            {
                if( argv[i][j] == HELP_FLAG )
                {
                    print_help( std::cout );
                    exit( 0 );
                }
                else if( argv[i][j] == MAN_FLAG )
                {
                    print_man_page( std::cout );
                    exit( 0 );
                }

                CLArgFlag* flag = impl->find_flag( argv[i][j] );
                if( !flag )
                {
                    error_stream << argv[0] << ": invalid flag: -" << argv[i][j] << std::endl;
                    return false;
                }
                else if( !flag->is_toggle() )
                {
                    pending.push_back( flag );
                }
                else if( !flag->parse( NULL ) )
                {
                    error_stream << argv[0] << ": conflicting flag: -" << argv[i][j] << std::endl;
                    return false;
                }
            }
        }
        else if( !impl->add_parsed_arg( argv[i] ) )
        {
            error_stream << argv[0] << ": unexpected argument: \"" << argv[i] << '"' << std::endl;
            return false;
        }
    }

    impl->get_args( args_out );

    if( !pending.empty() )
    {
        error_stream << argv[0] << ": expected argument following flag: -" << pending.front()->flag() << std::endl;
        return false;
    }
    if( !impl->have_required_args() )
    {
        error_stream << argv[0] << ": insufficient arguments" << std::endl;
        return false;
    }

    return true;
}
void CLArgs::print_help ( std::ostream &  stream) const

Write help.

Write help text to passed stream.

Definition at line 399 of file CLArgs.cpp.

References impl, and CLArgImpl::print_help().

Referenced by parse_options().

{
    impl->print_help( stream );
}
void CLArgs::print_man_page ( std::ostream &  stream) const

Write UNIX man page.

Write man page to passed stream.

Definition at line 404 of file CLArgs.cpp.

References impl, and CLArgImpl::print_man().

Referenced by parse_options().

{
    impl->print_man( stream );
}
void CLArgs::print_usage ( std::ostream &  stream) const

prinint usage (brief help)

Definition at line 409 of file CLArgs.cpp.

References impl, and CLArgImpl::print_brief_help().

Referenced by main().

{
    impl->print_brief_help( stream );
}
bool CLArgs::str_flag ( char  fl,
const char *  name,
const char *  desc,
CLArgs::StringArgI callback 
)

Register a flag that requires a string argument.

Define a flag of the form "-f <somestring>".

Parameters:
flThe character for the flag.
nameThe name of the flag argument
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
Returns:
false if flag is already in use, true otherwise.

Definition at line 253 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

{
    if( !is_flag_available( fl ) ) return false;
    return impl->add_flag( new CLArgString( fl, name, desc, callback ) );
}
bool CLArgs::toggle_flag ( char  on_flag,
char  off_flag,
const char *  desc,
CLArgs::ToggleArgI callback 
)

Register a pair of flags that accept no arguments and have opposing affects.

Regstier a flag of the form [-f|-F], where one implies a true state and the other a false state (i.e. enable or disable some functionality.)

Parameters:
on_flagFlag corresponding to true or 'on' state.
off_flagFlag corresponding to false or 'off' state.
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
Returns:
false if flag is already in use, true otherwise.

Definition at line 277 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

Referenced by add_domain_args(), and main().

{
    if( !( is_flag_available( on_flag ) && is_flag_available( off_flag ) ) ) return false;

    CLArgToggle* t1 = new CLArgToggle( on_flag, desc, true, callback );
    impl->add_flag( t1 );
    impl->add_flag( new CLArgToggle( off_flag, desc, t1 ) );
    return true;
}
bool CLArgs::toggle_flag ( char  fl,
const char *  desc,
CLArgs::ToggleArgI callback 
)

Register a flag with no value.

Define a flag such that the state of the option is considered to be false unless flag is specified. If the flag is specified, the option is considered to be true.

Parameters:
flThe character for the flag.
descA description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
Returns:
false if flag is already in use, true otherwise.

Definition at line 287 of file CLArgs.cpp.

References CLArgImpl::add_flag(), impl, and is_flag_available().

{
    if( !is_flag_available( fl ) ) return false;
    return impl->add_flag( new CLArgToggle( fl, desc, true, callback ) );
}

Member Data Documentation

List of all members.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines