subsystems/cli_parser.hpp
#ifndef STLPLUS_CLI_PARSER
#define STLPLUS_CLI_PARSER
////////////////////////////////////////////////////////////////////////////////
// Author: Andy Rushton
// Copyright: (c) Southampton University 1999-2004
// (c) Andy Rushton 2004 onwards
// License: BSD License, see ../docs/license.html
// A subsystem for managing command-line parsing, including using INI files to
// control the default options.
////////////////////////////////////////////////////////////////////////////////
#include "subsystems_fixes.hpp"
#include "message_handler.hpp"
#include "ini_manager.hpp"
#include "smart_ptr.hpp"
#include <string>
#include <stdexcept>
namespace stlplus
{
////////////////////////////////////////////////////////////////////////////////
// Internals
class cli_parser_data;
////////////////////////////////////////////////////////////////////////////////
// declarations
// enum to define the basic behaviour of an argument
// - a switch is an option with no value but which can be switched on or off e.g. -help and -nohelp
// - a value is an option followed by a value e.g. -output results.txt
// (a default value can be removed by using the option as a negated switch e.g. -nooutput)
// - command-line values (i.e. any strings not preceded by '-') are treated
// internally as an option with no name and must be values
enum cli_kind_t {cli_switch_kind, cli_value_kind};
// the mode controls the behaviour if an option appears more than once in either the command-line or the ini files
// - a single mode option overrides all previous values so will only be found once in the parsed result
// - a multiple mode option can be repeated to define multiple values, but overrides values from ini files
// - a cumulative mode option is a multiple mode option which keeps ini file values as well
enum cli_mode_t {cli_single_mode, cli_multiple_mode, cli_cumulative_mode};
// There are two structures used for defining command-line parameters
// (1) a C struct which is used in a C array - this is used for declaring
// command-line parameters in a static declaration
// (2) a C++ class which is used in an STL vector - this is used for building
// command-line parameters within code
// The C struct for definitions
struct cli_definition_t
{
// the name of the option, e.g. "help"
const char* m_name;
// the kind of the option, e.g. cli_switch_kind
cli_kind_t m_kind;
// the mode e.g. cli_single_mode
cli_mode_t m_mode;
// the mnemonic for the message giving usage information for this option
const char* m_message;
// built-in default value - null if not present
const char* m_default;
};
// The C array of the C struct. The array must be terminated by END_CLI_DEFINITIONS.
typedef cli_definition_t cli_definitions_t [];
#define END_CLI_DEFINITIONS {0,stlplus::cli_switch_kind,stlplus::cli_single_mode,"",0}
// The C++ class for definitions
class cli_definition
{
public:
// constructor that allows a definition to be created in one line
cli_definition(const std::string& name, cli_kind_t kind, cli_mode_t mode,
const std::string& message, const std::string& default_value = std::string()) :
m_name(name), m_kind(kind), m_mode(mode), m_message(message), m_default(default_value) {}
// the name of the option, e.g. "help"
const std::string& name(void) const;
// the kind of the option, e.g. switch_kind
cli_kind_t kind(void) const;
// the mode e.g. single_mode
cli_mode_t mode(void) const;
// the mnemonic for the message giving usage
const std::string& message(void) const;
// built-in default value - empty string if not present
const std::string& default_value(void) const;
private:
std::string m_name;
cli_kind_t m_kind;
cli_mode_t m_mode;
std::string m_message;
std::string m_default;
};
// The C++ vector of the C++ class
typedef std::vector<cli_definition> cli_definitions;
//////////////////////////////////////////////////////////////////////////////
// exceptions that can be thrown by the CLI parser
// they are all derivatives of std::logic_error because all errors are predictable by code inspection
// a correct program will never throw an exception
// thrown if a command-line argument is accessed with the wrong mode - i.e. attempt to get the value of a switch
class cli_mode_error : public std::invalid_argument
{
public:
cli_mode_error(const std::string& arg) : std::invalid_argument(arg) {}
~cli_mode_error(void) throw() {}
};
// similar to std::out_of_range thrown for using an index out of range
class cli_index_error : public std::out_of_range
{
public:
cli_index_error(const std::string& arg) : std::out_of_range(arg) {}
~cli_index_error(void) throw() {}
};
// similar to std::invalid_argument - thrown for passing an illegal argument to a method
class cli_argument_error : public std::invalid_argument
{
public:
cli_argument_error(const std::string& arg) : std::invalid_argument(arg) {}
~cli_argument_error(void) throw() {}
};
////////////////////////////////////////////////////////////////////////////////
class cli_parser
{
public:
// Type definitions map the global type names onto convenient scoped names
typedef cli_kind_t kind_t;
typedef cli_mode_t mode_t;
typedef cli_definition_t definition_t;
typedef cli_definitions_t definitions_t;
typedef cli_definition definition;
typedef cli_definitions definitions;
////////////////////////////////////////////////////////////////////////////////
// Methods
// various constructors
// you have a choice of either creating an uninitialised CLI parser and then
// calling separate functions to set it up or of calling one of the
// composite constructors. However, you must set up the error handler in the
// constructor.
// set up the parser with its error handler
// defer everything else
cli_parser(message_handler& errors);
// constructors using the C definitions_t structure
// set up the parser with the error handler and define all the command-line options
// defer default values and parameter parsing
// exceptions: cli_mode_error
cli_parser(cli_definitions_t, message_handler& errors);
// set up the parser with the error handler and define all the command-line
// options and their default from the ini files
// defer parameter parsing
// exceptions: cli_mode_error
cli_parser(cli_definitions_t, const ini_manager& defaults, const std::string& ini_section, message_handler& errors);
// set up the parser with the error handler and define all the command-line
// options no ini files used for default values, so only built-in defaults
// supported then parse the command line
// exceptions: cli_mode_error,message_handler_id_error,message_handler_format_error
cli_parser(char* argv[], cli_definitions_t, message_handler& errors);
// set up the parser with the error handler and define all the command-line
// options and their default from the ini files then parse the command line
// exceptions: cli_mode_error,message_handler_id_error,message_handler_format_error
cli_parser(char* argv[], cli_definitions_t, const ini_manager& defaults, const std::string& ini_section, message_handler& errors);
// constructors using the C++ definitions structure
// set up the parser with the error handler and define all the command-line
// options from a C array of structs
// defer default values and parameter parsing
// exceptions: cli_mode_error
cli_parser(cli_definitions, message_handler& errors);
// set up the parser with the error handler and define all the command-line
// options and their default from the ini files
// defer parameter parsing
// exceptions: cli_mode_error
cli_parser(cli_definitions, const ini_manager& defaults, const std::string& ini_section, message_handler& errors);
// set up the parser with the error handler and define all the command-line
// options no ini files used for default values, so only built-in defaults
// supported then parse the command line
// exceptions: cli_mode_error,message_handler_id_error,message_handler_format_error
cli_parser(char* argv[], cli_definitions, message_handler& errors);
// set up the parser with the error handler and define all the command-line
// options and their default from the ini files then parse the command line
// exceptions: cli_mode_error,message_handler_id_error,message_handler_format_error
cli_parser(char* argv[], cli_definitions, const ini_manager& defaults, const std::string& ini_section, message_handler& errors);
~cli_parser(void);
// the separate functions for initialising the parser in steps. These are
// declared in the order of use. Firts, add definitions of command-line
// arguments. Then optionally load default values from ini files, then
// finally parse the command line.
// add a set of C definitions. The definitions will be given ID codes from 0
// to the number of elements - 1 in the array
// exceptions: cli_mode_error
void add_definitions(cli_definitions_t);
// add a single C definition, returning the ID code for it
// exceptions: cli_mode_error,cli_argument_error
unsigned add_definition(const definition_t&);
// add a set of C++ definitions. The definitions will be given ID codes from
// 0 to the number of elements - 1 in the array
// exceptions: cli_mode_error
void add_definitions(cli_definitions);
// add a single C++ definition, returning the ID code for it
// exceptions: cli_mode_error
unsigned add_definition(const definition&);
// All definitions have an optional built-in default value which is stored
// in the definition types above. However, these can optionally be
// overridden by a value from an ini file. If you want this functionality,
// call this function. If you don't want ini file handling, simply don't
// call it. The values will be searched for only in the named section of the
// ini file (sections are labelled by e.g. [vassemble]), so in this case you
// would specify the section name as "vassemble" (exclude the brackets).
void set_defaults(const ini_manager& defaults, const std::string& ini_section);
// the final stage of initialisation is to read the command-line and extract
// the values from it. If parse errors are found, this will report the
// errors using the error handler and return false.
// exceptions: cli_argument_error,message_handler_id_error,message_handler_format_error
bool parse(char* argv[]);
// test for whether the CLI parser is still valid (no errors have happened)
// after the initialisation phase
bool valid(void);
// iteration functions avoiding the use of iterators. Just loop through the
// arguments from 0 to size()-1 and use the index of the loop to interrogate
// the command-line for the value at that position.
// the number of values to read, indexed 0 to size()-1
unsigned size(void) const;
// the argument name
// exceptions: cli_index_error
std::string name(unsigned i) const;
// the argument ID, that is, the offset into the original definitions
// exceptions: cli_index_error
unsigned id(unsigned i) const;
// the kind (switch or value) and short-cut tests for the different kinds
// exceptions: cli_index_error
cli_kind_t kind(unsigned i) const;
// exceptions: cli_index_error
bool switch_kind(unsigned i) const;
// exceptions: cli_index_error
bool value_kind(unsigned i) const;
// the mode (single, multiple, cumulative) and short-cut tests for the
// different modes - you rarely need to know this since it mainly controls
// the parsing
// exceptions: cli_index_error
cli_mode_t mode(unsigned i) const;
// exceptions: cli_index_error
bool single_mode(unsigned i) const;
// exceptions: cli_index_error
bool multiple_mode(unsigned i) const;
// exceptions: cli_index_error
bool cumulative_mode(unsigned i) const;
// get the switch's value, but only if the value is of switch kind
// exceptions: cli_mode_error,cli_index_error
bool switch_value(unsigned i) const;
// get the option's value, but only if it is of value kind
// exceptions: cli_mode_error,cli_index_error
std::string string_value(unsigned i) const;
// print the usage report - typically in response to the -help switch being on
// exceptions: std::runtime_error
void usage(void) const;
private:
friend class cli_parser_data;
smart_ptr_nocopy<cli_parser_data> m_data;
};
} // end namespace stlplus
#endif