yat  0.20.3pre
Public Member Functions | Friends | Related Functions | List of all members
theplu::yat::utility::CommandLine Class Reference

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:

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
strtext 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  
)
related

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:

Generated on Sat Feb 18 2023 03:31:45 for yat by  doxygen 1.8.14