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

Last change on this file since 1027 was 1027, checked in by Peter Johansson, 12 years ago

updating 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 2121 2009-12-13 16:17:07Z peter $
5
6/*
7  Copyright (C) 2007, 2008, 2009 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    void add_private(std::string, Option&);
167    bool is_long_option(std::string str) const;
168    bool is_short_option(std::string str) const;
169    std::vector<std::string> split(std::string str, char del) const;
170
171    std::string description_;
172    std::vector<std::string> free_arg_;
173    size_t free_arg_max_;
174    std::vector<Option*> options_;
175    std::map<char, Option*> short_options_;
176    std::map<std::string, Option*> long_options_;
177    bool parsed_;
178    std::string program_name_;
179  };
180
181  /**
182     \brief CommandLine output operator
183
184     A typical output may look like this
185     \verbatim
186     Available options are:
187     -h, --help      display this help and exit
188     -v, --verbose   explain what is being done
189     \endverbatim
190     The output starts with a descriptive line such as "Available
191     options are:" (default) that can be set in constructor. Then follows the
192     options described in the order they were added to
193     Commandline. Each Option is described according to
194     Option::print(void) function.
195     \see OptionHelp
196
197     \relates CommandLine
198  */
199  std::ostream& operator<<(std::ostream&, const CommandLine&);
200
201}}} // end of namespace utility, yat, and theplu
202
203#endif
Note: See TracBrowser for help on using the repository browser.