source: trunk/yat/utility/CommandLine.h @ 687

#ifndef _theplu_yat_utility_commandline_
#define _theplu_yat_utility_commandline_

//$Id: CommandLine.h 687 2006-10-16 23:51:10Z jari $

/*
  Copyright (C) 2006 Peter Johansson

  This file is part of the yat library, http://lev.thep.lu.se/trac/yat

  The yat library is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License as
  published by the Free Software Foundation; either version 2 of the
  License, or (at your option) any later version.

  The yat library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  02111-1307, USA.
*/

#include "Option.h"

#include <cctype>
#include <list>
#include <map>
#include <string>
#include <utility>
#include <vector>

namespace theplu {
namespace yat {
namespace utility {

  /**
     @brief Class for parsing the command line.
     
     Provides parsing and storage of command line arguments (argc,
     argv). To use this class first add a set of valid parameters
     using the add_parameter() function. 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 as e.g. "program -vf" is
     equivalent to "program -v -f". Associated to each parameter is an
     attribute telling what type of argument is expected for the
     parameter. Several types of arguments are supported: no argument,
     string argument, int argument, double argument. The argument
     value for all found parameters are set during parsing, which
     supports both gnu-style "--support-gnu=value", POSIX-like
     "--support-posix value", as well as shorter "-s value". The
     argument of an parameter is retrived by the value() function or
     its sibblings for different types. By using the set_help()
     function help will be displayed when flag (default is '-h' and
     '--help') is found in parsing.
     
     Here is a small code example:
     @code 
#include "yat/utility/CommandLine.h" 
#include <iostream>
int main(const int argc,const char* argv[])
{
  theplu::utility::CommandLine cmd;
  cmd.set_general_description("This is just an example program");
  cmd.add_parameter('n', utility::Option::int_arg, 
                    "example of parameter taking an integer");
  cmd.add_parameter('t', "target", utility::Option::string_arg);
  cmd.add_parameter("version",utility::Option::no_arg, 
                    "output version infomation and exit");
  cmd.set_help();
  cmd.parse(argc, argv);
  if (cmd.present("version"))
    std::cout << "example 1.0" << std::endl;
  if (cmd.present("target"))
    std::cout << "using target: " << target << std::endl;
  if (cmd.present('n')){
    int n=cmd.value('n');
    for (size_t i=0; i<n; ++i)
      std::cout << "Hello World\n";
    std::cout << endl;
  }
  return 0;
}
     @endcode 
     
     @see Option
     
  **/
  class CommandLine
  {
  public:

    ///
    /// @brief deafult constructor
    ///
    CommandLine(void);

    ///
    /// @brief Destructor
    ///
    virtual ~CommandLine(void);

    ///
    /// @brief Function to add a parameter. 
    ///
    /// @param long_name string key such as "help" for --help flag
    /// @param arg telling what kind argument this option expects
    /// @param description string used in help display
    ///
    void add_parameter(const std::string& long_name,
                       Option::argument_type arg = Option::no_arg,
                       const std::string& description = std::string());

    ///
    /// @brief Function to add a parameter. 
    ///
    /// @param short_name one character key such as 'h' for -h flag
    /// @param arg telling what kind argument this option expects
    /// @param description string used in help display
    ///
    void add_parameter(const char short_name,
                       Option::argument_type arg = Option::no_arg,
                       const std::string& description = std::string());

    ///
    /// @brief Function to add a parameter. 
    ///
    /// @param short_name one character key such as 'h' for -h flag
    /// @param long_name string key such as "help" for --help flag
    /// @param arg telling what kind argument this option expects
    /// @param description string used in help display
    ///
    inline void add_parameter(const char short_name,
                              const std::string& long_name,
                              Option::argument_type arg = Option::no_arg,
                              const std::string& description = std::string())
    { add(short_name, long_name, arg, description); }

    ///
    /// @return vector of arguments not associated to a specific parameter
    ///
    const std::vector<std::string>& arguments(void) const;

    ///
    /// If more than maximal number of arguments is found during
    /// parsing an error message is displayed followed by exit.
    ///
    /// @return maximal number of arguments allowed.
    ///
    inline u_int& max_argument(void) { return max_argument_; }

    ///
    /// If less than minimal number of arguments is found during
    /// parsing an error message is displayed followed by exit.
    ///
    /// @return minimal number of arguments allowed.
    ///
    inline u_int& min_argument(void) { return min_argument_; }

    ///
    /// @brief parse the commandline
    ///
    void parse(int argc, const char* argv[]);

    ///
    /// @return true if @a parameter has been detected in parsing.
    ///
    bool present(const std::string& parameter) const;

    ///
    /// @brief allow help.
    ///
    void set_help(char shortname = 'h',
                  const std::string& longname = "help",
                  const std::string& descr = "display this help and exit");

    ///
    /// The @a description will be included in help display giving a
    /// general explanation what program is doing.
    ///
    inline void set_general_description(const std::string& description)
    { general_description_=description; }

    ///
    /// @note Using function for @a parameter not added previously
    /// will cause an error message and exit.
    ///
    /// @return argument value for @a parameter 
    ///
    std::string value(const std::string& parameter) const;

    ///
    /// If the value for @a parameter is not a valid double an error
    /// message will be displayed followed by an exit.
    ///
    /// @note Using function for @a parameter not added previously
    /// will cause an error message and exit.
    ///
    /// @return argument value for @a parameter 
    ///
    double value_double(const std::string& parameter) const;

    ///
    /// If the value for @a parameter is not a valid double an error
    /// message will be displayed followed by an exit.
    ///
    /// @note Using function for @a parameter not added previously
    /// will cause an error message and exit.
    ///
    /// @return argument value for @a parameter 
    ///
    int value_int(const std::string& parameter) const;

    ///
    /// Function to display the help message.
    ///
    void usage(void) const;

    private:
    Option* add(char short_name,
                const std::string& long_name,
                Option::argument_type arg,
                const std::string& describtion);

    inline bool is_long_option(const std::string& str)
    { return (str.size()>3 && str[0]=='-' && str[1]=='-'); }
    
    inline bool is_short_option(const std::string& str)
    { return (str.size()==2 && str[0]=='-' && isalpha(str[1])); }

    void print_try_help(void) const;
    std::string split(std::string&, char) const;
    bool update(const std::string& key, const std::string& value);


    typedef std::map<std::string, Option*> key2option;

    std::string app_name_;
    const Option* help_option_;
    std::string general_description_;
    u_int max_argument_;
    u_int min_argument_;
    key2option param_;
    std::list<Option*> options_;
    std::vector<std::string> arguments_;
  };


}}} // end of namespace utility, yat, and theplu

#endif