Class for parsing the command line. More...

#include <yat/utility/CommandLine.h>

Public Member Functions
	CommandLine (std::string str="Available options are:")
	default constructor More...

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. More...

const std::vector< std::string > &	free_args (void) const
	Arguments not associated with an Option. More...

void	parse (int argc, char *argv[])
	parse the commandline More...

bool	parsed (void) const
	has the commandline been parsed already More...

std::string	program_name (void) const

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

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. More...

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

◆ CommandLine()

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

◆ allow_free_args()

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

Allow at most n free arguments.

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

prog foo bar

◆ free_args()

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)

◆ parse()

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.

◆ parsed()

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

◆ program_name()

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.

◆ sort() [1/2]

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

◆ sort() [2/2]

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

◆ try_help()

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

◆ operator<<()

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