archiving support for releases

[chaz/yoink] / src / stlplus / 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-2009
//   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)
      throw();

    // 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
    cli_parser(cli_definitions_t, message_handler& errors)
      throw(cli_mode_error);
    // 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
    cli_parser(cli_definitions_t, const ini_manager& defaults, const std::string& ini_section, message_handler& errors)
      throw(cli_mode_error);
    // 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
    cli_parser(char* argv[], cli_definitions_t, message_handler& errors)
      throw(cli_mode_error,message_handler_id_error,message_handler_format_error);
    // 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
    cli_parser(char* argv[], cli_definitions_t, const ini_manager& defaults, const std::string& ini_section, message_handler& errors)
      throw(cli_mode_error,message_handler_id_error,message_handler_format_error);

    // 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
    cli_parser(cli_definitions, message_handler& errors)
      throw(cli_mode_error);
    // 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
    cli_parser(cli_definitions, const ini_manager& defaults, const std::string& ini_section, message_handler& errors)
      throw(cli_mode_error);
    // 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
    cli_parser(char* argv[], cli_definitions, message_handler& errors)
      throw(cli_mode_error,message_handler_id_error,message_handler_format_error);
    // 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
    cli_parser(char* argv[], cli_definitions, const ini_manager& defaults, const std::string& ini_section, message_handler& errors)
      throw(cli_mode_error,message_handler_id_error,message_handler_format_error);

    ~cli_parser(void)
      throw();

    // 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
    void add_definitions(cli_definitions_t)
      throw(cli_mode_error);
    // add a single C definition, returning the ID code for it
    unsigned add_definition(const definition_t&)
      throw(cli_mode_error,cli_argument_error);
    // add a set of C++ definitions. The definitions will be given ID codes from
    // 0 to the number of elements - 1 in the array
    void add_definitions(cli_definitions)
      throw(cli_mode_error);
    // add a single C++ definition, returning the ID code for it
    unsigned add_definition(const definition&)
      throw(cli_mode_error);

    // 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)
      throw();

    // 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.
    bool parse(char* argv[])
      throw(cli_argument_error,message_handler_id_error,message_handler_format_error);

    // test for whether the CLI parser is still valid (no errors have happened)
    // after the initialisation phase
    bool valid(void)
      throw();

    // 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
      throw();

    // the argument name
    std::string name(unsigned i) const
      throw(cli_index_error);
    // the argument ID, that is, the offset into the original definitions
    unsigned id(unsigned i) const
      throw(cli_index_error);

    // the kind (switch or value) and short-cut tests for the different kinds
    cli_kind_t kind(unsigned i) const
      throw(cli_index_error);
    bool switch_kind(unsigned i) const
      throw(cli_index_error);
    bool value_kind(unsigned i) const
      throw(cli_index_error);

    // 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
    cli_mode_t mode(unsigned i) const 
      throw(cli_index_error);
    bool single_mode(unsigned i) const
      throw(cli_index_error);
    bool multiple_mode(unsigned i) const
      throw(cli_index_error);
    bool cumulative_mode(unsigned i) const
      throw(cli_index_error);

    // get the switch's value, but only if the value is of switch kind
    bool switch_value(unsigned i) const
      throw(cli_mode_error,cli_index_error);

    // get the option's value, but only if it is of value kind
    std::string string_value(unsigned i) const
      throw(cli_mode_error,cli_index_error);

    // print the usage report - typically in response to the -help switch being on
    void usage(void) const
      throw(std::runtime_error);

  private:
    friend class cli_parser_data;
    smart_ptr_nocopy<cli_parser_data> m_data;
  };

} // end namespace stlplus

#endif