Class for parsing the command line. More...

#include <yat/utility/CommandLine.h>

Public Member Functions
	CommandLine (std::string str="Available options are:")
	default constructor
virtual	~CommandLine (void)
	Destructor.
void	add (Option &)
	Function to add an option.
void	allow_free_args (size_t n)
	Allow at most n free arguments.
const std::vector< std::string > &	free_args (void) const
	Arguments not associated with an Option.
void	parse (int argc, char *argv[])
	parse the commandline
bool	parsed (void) const
	has the commandline been parsed already
std::string	program_name (void) const
void	sort (void)
	Sort Options how they will appear in (help) output.
template<class Compare >
void	sort (Compare compare)
std::string	try_help (void) const
Friends
std::ostream &	operator<< (std::ostream &os, const CommandLine &cl)
Related Functions
(Note that these are not member functions.)
std::ostream &	operator<< (std::ostream &, const CommandLine &)
	CommandLine output operator.

Detailed Description

Class for parsing the command line.

Provides parsing and storage of command line arguments. The class
is typically used by hooking a number of Option objects to
CommandLine, and then call the parse() function. Here is a short
example how the class may be used:

     CommandLine cmd;
     OptionHelp help(cmd);
     OptionFile in(cmd, "i,in", 
                   "Read input from file (rather than standard input)",
                   false, true, "r");
     OptionFile out(cmd, "o,out", "Place the output to file", false, false, "w");
     OptionSwitch target(cmd, "T,target", "treat DEST as a normal file", true);
     OptionSwitch verbose(cmd, "v,verbose", "explain what is being done");
     OptionSwitch version(cmd, "version", "output version and exit");
     std::stringstream copyright;
     copyright << "example 1.0\n"
               << "Copyright (C) 2007 Peter Johansson\n\n"
               << "This is free software see the source for copying "
               << "conditions. There is NO\nwarranty; not even for "
               << "MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n";
     try {
       cmd.parse(argc, argv);
     }
     catch (cmd_error& e){
       if (version.present()){
         std::cout << copyright.str();     
         return EXIT_SUCCESS;
       }
       std::cerr << e.what() << std::endl;
       return EXIT_FAILURE;
     }  
     if (version.present()){
       std::cout << copyright.str();     
       return EXIT_SUCCESS;
     }
     StreamRedirect sr_out(std::cout, out.value(), out.present());
     StreamRedirect sr_in(std::cin, in.value(), in.present());
     ...

After creation a number of Option classes are hooked up to the CommandLine object in their constructors.

Each parameter is associated to a one-character flag and/or a longer string flag. The longer flag expects to be preceded by '--' as e.g. '--help' for help. The shorter flag expects to be preceded by '-' as e.g. '-h', and can also be concatenated like "program -vf", which is equivalent to "program -v -f". or its sibblings for different types.

Constructor & Destructor Documentation

theplu::yat::utility::CommandLine::CommandLine ( std::string str = "Available options are:" )

default constructor

Parameters:

str	text preceeding the list of option in output

Member Function Documentation

void theplu::yat::utility::CommandLine::allow_free_args ( size_t n )

Allow at most n free arguments.

An free argument is an argument not associated with an Option, allowing commandlines such as

 prog foo bar

const std::vector<std::string>& theplu::yat::utility::CommandLine::free_args ( void ) const

Arguments not associated with an Option.

See also:: allow_free_args(size_t n)

void theplu::yat::utility::CommandLine::parse	(	int	argc,
		char *	argv[]
	)

parse the commandline

First the commandline is parsed to detect which options are present, then each Option parses the its relevant part of commandline (Option::parse()), and finally each Option is validated (Option::validate()).

throw cmd_error if an error is detected.

bool theplu::yat::utility::CommandLine::parsed ( void ) const

has the commandline been parsed already

Returns:: true if parse function has already been called

Since:: New in yat 0.5

std::string theplu::yat::utility::CommandLine::program_name ( void ) const

Returns:: Name of more; more specifically argv[0] is stripped so only string after the last '/' remains.

void theplu::yat::utility::CommandLine::sort ( void )

Sort Options how they will appear in (help) output.

This function will sort the Options in alphabetical order. If the Option has a long_name, it is used for the sorting; otherwise, the short_name is used.

Since:: New in yat 0.7

template<class Compare >

void theplu::yat::utility::CommandLine::sort ( Compare compare )

Like sort(void) but using compare to sort Options.

The functor Compare must be a Binary Predicate with both argument types const Option*.

Since:: New in yat 0.7

std::string theplu::yat::utility::CommandLine::try_help ( void ) const

Returns:: something like "Try <tt>\<program_name()\> --help</tt> for more information."

Friends And Related Function Documentation

std::ostream & operator<<	(	std::ostream &	,
		const CommandLine &
	)

A typical output may look like this

     Available options are:
     -h, --help      display this help and exit
     -v, --verbose   explain what is being done

The output starts with a descriptive line such as "Available options are:" (default) that can be set in constructor. Then follows the options described in the order they were added to Commandline. Each Option is described according to Option::print(void) function.

See also:: OptionHelp

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

yat/utility/CommandLine.h

Public Member Functions

Friends

Related Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation