theplu::yat::utility::CommandLine Class Reference

Class for parsing the command line. More...

#include <yat/utility/CommandLine.h>

List of all members.

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
std::string	try_help (void) const
Friends
std::ostream &	operator<< (std::ostream &os, const CommandLine &cl)
	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);
     OptionInFile in(cmd, "i,in", 
                     "Read input from file (rather than standard input)");
     OptionOutFile out(cmd, "o,out", "Place the output to file");
     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;
     }
     ...

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

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.

std::string theplu::yat::utility::CommandLine::try_help

(

void

)

const

Returns:

something like "Try `<program_name()> --help` for more information."

---

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	os,
		const CommandLine &	cl
	)			[friend]

CommandLine output operator.

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