From: http://www.radmangames.com/programming/how-to-use-boost-program_options
If it so happens that you’re writing a console application, then chances are you will (or should) want to pass it some parameters at the command line. By default C++ has only the argc and argv parameters to the main function to facilitate this and I can assure you that working with them directly is less than fun. If you have worked with any number of command line programs you would be well aware of a common form that they take and that users expect. To get this expected behavior you should use another favourite boost library of mine: Program options.
Quite simply, Boost.Program_options is the way to do industry standard command line processing in C++, if you’re trying to implement command line arguments in your application then you should be using this library. This tutorial will take you through how to get set up and productive using boost program options with a minimum of fuss.
Obtaining, compiling and linking to boost is not covered.
EDIT: Aug 16 2014
Spurred on by a comment on this post I have written a library that extends Boost.Program_options, providing support for subcommand syntax (think SVN or Mercurial) and including convenient formatting utilities for posix style help output. It's free, open source and awesome! You can check it out here.
Application Template
So you have an program that you want to be able to accept command line parameters? Then replace (or merge) the contents of your main.cpp with the code below. This code forms the foundation of the rest of the tutorial and is boiler plate that you will find yourself writing every time you create a new command line application.
Note: the rest of the examples reference the names of objects in the code below.
#include "boost/program_options.hpp"
#include <iostream>
#include <string>
namespace
{
const size_t ERROR_IN_COMMAND_LINE = 1;
const size_t SUCCESS = 0;
const size_t ERROR_UNHANDLED_EXCEPTION = 2;
} // namespace
int main(int argc, char** argv)
{
try
{
/** Define and parse the program options
*/
namespace po = boost::program_options;
po::options_description desc("Options");
desc.add_options()
("help", "Print help messages")
("add", "additional options")
("like", "this");
po::variables_map vm;
try
{
po::store(po::parse_command_line(argc, argv, desc),
vm); // can throw
/** --help option
*/
if ( vm.count("help") )
{
std::cout << "Basic Command Line Parameter App" << std::endl
<< desc << std::endl;
return SUCCESS;
}
po::notify(vm); // throws on error, so do after help in case
// there are any problems
}
catch(po::error& e)
{
std::cerr << "ERROR: " << e.what() << std::endl << std::endl;
std::cerr << desc << std::endl;
return ERROR_IN_COMMAND_LINE;
}
// application code here //
}
catch(std::exception& e)
{
std::cerr << "Unhandled Exception reached the top of main: "
<< e.what() << ", application will now exit" << std::endl;
return ERROR_UNHANDLED_EXCEPTION;
}
return SUCCESS;
} // main
Basic option configuration
desc.add_options()call in the application template.
Add the most simple of options
--option
("option", "Info message about option")
Add a shorthand for an option
--option or -o
("option,o", "Info message about option") // can use -o
Add an option with shorthand only
-o
(",o", "Info message about option") // must use -o
NOTE: To access a shorthand only value in a variables_map format the name as you would on the command line e.g. -o. See the Accessing Option Values section for more details.
Add an option that has an associated value
--option <value>
("option", po::value<arg_type>(), "Info message about option")
Specify that an option is required
po::notify(vm)will throw if the option is not specified.
("option", po::value<arg_type>()->required(), "Info message")
Specify an option that can be specified multiple times
--option <value1> --option <value2> --option <value3>
("option", po::value<std::vector<arg_type> >(), "a list of values")
Accessing option values
Have the option set directly into an existing variable
I find this to be the most convenient method to use
("option", po::value<arg_type>(&existingVariable), "info message")
Check if an option was passed in the command line
if ( vm.count("option") )
To extract the value for an option manually
vm["option"].as<arg_type>()
Retrieving shorthand only options
Access to shorthand options is done exactly the same way as described above but the "option" string has to be formatted in a particular way. If there is only a shorthand option then the name for that option is considered to be "-X" where X is the letter being used as the short hand. Another way to remember this is to specify the name as it would appear on the command line.
(",t", "Shorthand only option -t")
if ( vm.count("-t") )
{
vm["-t"].as<arg_type>()
}
Specifying Positional Options
A positional option is a value given on the command line that is not preceded by an option switch like -o or --option. An example is the following:
In this case main.cpp is the positional option, and as you can see it is not associated with any option explicitly specified. Instead of being identified by an option switch (like --option) they are identified by the lack of one. When multiple positional options are available the option the value is assigned to is designated by the order in which the values appear in the command line.
In this case 'help' is the first positional option and 'commit' is the second. The command will print help info for the commit subcommand. Now if the order were to be reversed:
The position of the options is now reversed and the command will now try to 'commit' the location 'help'. Again the order in which values are specified determines which positional option the value is assigned to.
Example code for positional options
po::positional_options_descriptionobject and specify the names of the options that you want to parse as positional. Add the following code block directly below the last option in the
desc.add_options()call:
po::positional_options_description positionalOptions;
positionalOptions.add("option_name_1", <num_occurrences>);
positionalOptions.add("option_name_2", <num_occurrences>);
The option name specified as the first parameter must correspond to the name of an option already specified in the regular options description. The second parameter specifies the number of values to be associated with the option, in the simple case you will always set this to 1. The positional order of options is implied by the order in which they are added to the description, in this case 'option_name_1' is first and 'option_name_2' is second.
po::store()call to the following:
po::store(po::command_line_parser(argc, argv).options(desc)
.positional(positionalOptions).run(),
vm);
Putting it all together
With just the information above you can create quite sophisticated command line applications, but sometimes knowing the parts does not give a good enough picture of what can be achieved. Check out below for a full example of the options implemented in a demo application. This should help to give you an idea of how things look when it’s all put together. Be aware that I have implemented some custom parsing for printing the available options in posix style which I include as part of the source package for the example application and an example of that usage output is shown immediately below. The information is parsed generically from the specified options and this prevents you from having to manually update help text when you update options (which is pretty awesome).
Best of luck, and please let me know if you have any issues.
Please note you will need version 1.50.0 of boost to compile the extended example
Usage Output
This is just a template app that should be modified and added to in order to create a useful command line application
USAGE: test_bed [-hvt] [-w ARG] [-m ARG] -n ARG add like
-- Option Descriptions --
Positional arguments:
add "additional options"
like "this"
Option Arguments:
-h [ --help ] Print help messages
-v [ --verbose ] print words with verbosity
-w [ --word ] words for the sentence, specify multiple times
-t just a temp option that does very little
-n [ --necessary ] give me anything
-m [ --manual ] extract value manually
Example Application
#include "PrettyOptionPrinter.hpp"
#include "boost/program_options.hpp"
#include "boost/filesystem.hpp"
#include <iostream>
#include <string>
namespace
{
const size_t ERROR_IN_COMMAND_LINE = 1;
const size_t SUCCESS = 0;
const size_t ERROR_UNHANDLED_EXCEPTION = 2;
} // namespace
//------------------------------------------------------------------------
int main(int argc, char** argv)
{
try
{
std::string appName = boost::filesystem::basename(argv[0]);
int add = 0;
int like = 0;
std::vector<std::string> sentence;
/** Define and parse the program options
*/
namespace po = boost::program_options;
po::options_description desc("Options");
desc.add_options()
("help,h", "Print help messages")
("verbose,v", "print words with verbosity")
("word,w", po::value<std::vector<std::string> >(&sentence),
"words for the sentence, specify multiple times")
(",t", "just a temp option that does very little")
("necessary,n", po::value<std::string>()->required(), "necessary!")
("manual,m", po::value<std::string>(), "extract value manually")
("add", po::value<int>(&add)->required(), "additional options")
("like", po::value<int>(&like)->required(), "this");
po::positional_options_description positionalOptions;
positionalOptions.add("add", 1);
positionalOptions.add("like", 1);
po::variables_map vm;
try
{
po::store(po::command_line_parser(argc, argv).options(desc)
.positional(positionalOptions).run(),
vm); // throws on error
/** --help option
*/
if ( vm.count("help") )
{
std::cout << "This is just a template app that should be modified"
<< " and added to in order to create a useful command"
<< " line application" << std::endl << std::endl;
rad::OptionPrinter::printStandardAppDesc(appName,
std::cout,
desc,
&positionalOptions);
return SUCCESS;
}
po::notify(vm); // throws on error, so do after help in case
// there are any problems
}
catch(boost::program_options::required_option& e)
{
rad::OptionPrinter::formatRequiredOptionError(e);
std::cerr << "ERROR: " << e.what() << std::endl << std::endl;
rad::OptionPrinter::printStandardAppDesc(appName,
std::cout,
desc,
&positionalOptions);
return ERROR_IN_COMMAND_LINE;
}
catch(boost::program_options::error& e)
{
std::cerr << "ERROR: " << e.what() << std::endl << std::endl;
rad::OptionPrinter::printStandardAppDesc(appName,
std::cout,
desc,
&positionalOptions);
return ERROR_IN_COMMAND_LINE;
}
// can do this without fear because it is required to be present
std::cout << "Necessary = "
<< vm["necessary"].as<std::string>() << std::endl;
if ( vm.count("verbose") )
{
std::cout << "VERBOSE PRINTING" << std::endl;
}
if (vm.count("verbose") && vm.count("t"))
{
std::cout << "heeeeyahhhhh" << std::endl;
}
std::cout << "Required Positional, add: " << add
<< " like: " << like << std::endl;
if ( sentence.size() > 0 )
{
std::cout << "The specified words: ";
std::string separator = " ";
if (vm.count("verbose"))
{
separator = "__**__";
}
for(size_t i=0; i<sentence.size(); ++i)
{
std::cout << sentence[i] << separator;
}
std::cout << std::endl;
}
if ( vm.count("manual") )
{
std::cout << "Manually extracted value: "
<< vm["manual"].as<std::string>() << std::endl;
}
}
catch(std::exception& e)
{
std::cerr << "Unhandled Exception reached the top of main: "
<< e.what() << ", application will now exit" << std::endl;
return ERROR_UNHANDLED_EXCEPTION;
}
return SUCCESS;
} // main
//------------------------------------------------------------------------