source: trunk/lib/yat/CommandLine.h @ 1058

Last change on this file since 1058 was 1058, checked in by Peter Johansson, 11 years ago

update to latest yat

  • Property svn:eol-style set to native
File size: 5.9 KB
Line 
1#ifndef _theplu_yat_utility_commandline_
2#define _theplu_yat_utility_commandline_
3
4//$Id: CommandLine.h 2247 2010-04-22 00:54:34Z peter $
5
6/*
7  Copyright (C) 2007, 2008, 2009, 2010 Jari Häkkinen, Peter Johansson
8
9  This file is part of the yat library, http://dev.thep.lu.se/yat
10
11  The yat library is free software; you can redistribute it and/or
12  modify it under the terms of the GNU General Public License as
13  published by the Free Software Foundation; either version 3 of the
14  License, or (at your option) any later version.
15
16  The yat library is distributed in the hope that it will be useful,
17  but WITHOUT ANY WARRANTY; without even the implied warranty of
18  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19  General Public License for more details.
20
21  You should have received a copy of the GNU General Public License
22  along with yat. If not, see <http://www.gnu.org/licenses/>.
23*/
24
25#include <cctype>
26#include <map>
27#include <iosfwd>
28#include <sstream>
29#include <stdexcept>
30#include <string>
31#include <typeinfo>
32#include <utility>
33#include <vector>
34
35namespace theplu {
36namespace yat {
37namespace utility {
38
39  class Option;
40
41  /**
42     @brief Class for parsing the command line.
43     
44     Provides parsing and storage of command line arguments. The class
45     is typically used by hooking a number of Option objects to
46     CommandLine, and then call the parse() function. Here is a short
47     example how the class may be used:
48 
49     \code
50 
51     CommandLine cmd;
52     OptionHelp help(cmd);
53     OptionFile in(cmd, "i,in",
54                   "Read input from file (rather than standard input)",
55                   false, true, "r");
56     OptionFile out(cmd, "o,out", "Place the output to file", false, false, "w");
57     OptionSwitch target(cmd, "T,target", "treat DEST as a normal file", true);
58     OptionSwitch verbose(cmd, "v,verbose", "explain what is being done");
59     OptionSwitch version(cmd, "version", "output version and exit");
60     std::stringstream copyright;
61     copyright << "example 1.0\n"
62               << "Copyright (C) 2007 Peter Johansson\n\n"
63               << "This is free software see the source for copying "
64               << "conditions. There is NO\nwarranty; not even for "
65               << "MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n";
66     try {
67       cmd.parse(argc, argv);
68     }
69     catch (cmd_error& e){
70       if (version.present()){
71         std::cout << copyright.str();     
72         return EXIT_SUCCESS;
73       }
74       std::cerr << e.what() << std::endl;
75       return EXIT_FAILURE;
76     } 
77     if (version.present()){
78       std::cout << copyright.str();     
79       return EXIT_SUCCESS;
80     }
81     StreamRedirect sr_out(std::cout, out.value(), out.present());
82     StreamRedirect sr_in(std::cin, in.value(), in.present());
83     ...
84     \endcode
85
86     After creation a number of Option classes are hooked up to the
87     CommandLine object in their constructors.
88
89     Each parameter is associated to a one-character flag and/or a
90     longer string flag. The longer flag expects to be preceded by
91     '--' as e.g. '--help' for help. The shorter flag expects to be
92     preceded by '-' as e.g. '-h', and can also be concatenated like
93     "program -vf", which is equivalent to "program -v -f". or
94     its sibblings for different types.
95  */
96  class CommandLine
97  {
98  public:
99    /**
100       \brief default constructor
101
102       \param str text preceeding the list of option in output
103    */
104    CommandLine(std::string str="Available options are:");
105
106    /**
107       \brief Destructor
108    */
109    virtual ~CommandLine(void);
110
111    /**
112       \brief Function to add an option.
113    */
114    void add(Option&);
115
116    /**
117       \brief Allow at most \a n free arguments.
118
119       An free argument is an argument not associated with an Option,
120       allowing commandlines such as \code prog foo bar \endcode
121     */
122    void allow_free_args(size_t n);
123
124    /**
125       \brief Arguments not associated with an Option
126
127       \see allow_free_args(size_t n)
128    */
129    const std::vector<std::string>& free_args(void) const;
130
131    /**
132       \brief parse the commandline
133
134       First the commandline is parsed to detect which options are
135       present, then each Option parses the its relevant part of
136       commandline (Option::parse()), and finally each Option is
137       validated (Option::validate()).
138
139       throw cmd_error if an error is detected.
140    */
141    void parse(int argc, char* argv[]);
142
143    /**
144       \brief has the commandline been parsed already
145
146       \return true if parse function has already been called
147
148       \since New in yat 0.5
149    */
150    bool parsed(void) const;
151
152    /**
153       @return Name of more; more specifically argv[0] is
154       stripped so only string after the last '/' remains.
155     */
156    std::string program_name(void) const;
157
158    /**
159       \return something like "Try `<program_name()> --help` for
160       more information."
161     */
162    std::string try_help(void) const;
163
164  private:
165    friend std::ostream& operator<<(std::ostream& os, const CommandLine& cl);
166    bool is_long_option(std::string str) const;
167    bool is_short_option(std::string str) const;
168    std::vector<std::string> split(std::string str, char del) const;
169
170    std::string description_;
171    std::vector<std::string> free_arg_;
172    size_t free_arg_max_;
173    std::vector<Option*> options_;
174    std::map<char, Option*> short_options_;
175    std::map<std::string, Option*> long_options_;
176    bool parsed_;
177    std::string program_name_;
178  };
179
180  /**
181     \brief CommandLine output operator
182
183     A typical output may look like this
184     \verbatim
185     Available options are:
186     -h, --help      display this help and exit
187     -v, --verbose   explain what is being done
188     \endverbatim
189     The output starts with a descriptive line such as "Available
190     options are:" (default) that can be set in constructor. Then follows the
191     options described in the order they were added to
192     Commandline. Each Option is described according to
193     Option::print(void) function.
194     \see OptionHelp
195
196     \relates CommandLine
197  */
198  std::ostream& operator<<(std::ostream&, const CommandLine&);
199
200}}} // end of namespace utility, yat, and theplu
201
202#endif
Note: See TracBrowser for help on using the repository browser.