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
CLArgImpl *	impl

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.

typedef ArgListTemplate< double > CLArgs::DoubleListArg

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.

typedef ArgListTemplate< int > CLArgs::IntListArg

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.

typedef ArgTemplateI< bool > CLArgs::ToggleArgI

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:

progname	The program name
brief_desc	A brief description of the purpose of the program.
desc	Program description for documentation.

Definition at line 241 of file CLArgs.cpp.

References impl.

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

CLArgs::~CLArgs ( )

Definition at line 246 of file CLArgs.cpp.

References impl.

{
    delete impl;
}

Member Function Documentation

void CLArgs::add_optional_arg ( const char * name )

Definition at line 325 of file CLArgs.cpp.

References CLArgImpl::add_opt_arg(), and impl.

Referenced by main().

{
    impl->add_opt_arg( name );
}

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 320 of file CLArgs.cpp.

References CLArgImpl::add_req_arg(), and impl.

Referenced by main().

{
    impl->add_req_arg( name );
}

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:

fl	The character for the flag.
name	The name of the flag argument
desc	A description of the purpose of the flag and argument. callback Object instance to which to pass the parsed argument value.
inclusive	If 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 274 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:

fl	The character for the flag.
desc	A 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 308 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:

fl	The character for the flag.
desc	A 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 296 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:

fl	The character for the flag.
name	The name of the flag argument
desc	A 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 262 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:

fl	The character for the flag.
desc	A 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 302 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 251 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:

fl	The flag
num_values	The number of values to accept
value_names	An 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 314 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:

fl	The character for the flag.
name	The name of the flag argument
desc	A 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 268 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:

argc	The 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.
argv	The argument list as passed to main().
args_out	The 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_stream	stream to which to write error messages.

Returns:: true if all arguments were accepted. false otherwise.

Definition at line 330 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 402 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 407 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 412 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:

fl	The character for the flag.
name	The name of the flag argument
desc	A 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 256 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_flag	Flag corresponding to true or 'on' state.
off_flag	Flag corresponding to false or 'off' state.
desc	A 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 280 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:

fl	The character for the flag.
desc	A 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 290 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

CLArgImpl* CLArgs::impl [private]

Definition at line 544 of file CLArgs.hpp.

Referenced by add_optional_arg(), add_required_arg(), CLArgs(), double_flag(), double_list_flag(), id_list_flag(), int_flag(), int_list_flag(), is_flag_available(), limit_list_flag(), long_flag(), parse_options(), print_help(), print_man_page(), print_usage(), str_flag(), toggle_flag(), and ~CLArgs().

List of all members.

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation