1 // Copyright 2010 Google Inc. 2 // All rights reserved. 3 // 4 // Redistribution and use in source and binary forms, with or without 5 // modification, are permitted provided that the following conditions are 6 // met: 7 // 8 // * Redistributions of source code must retain the above copyright 9 // notice, this list of conditions and the following disclaimer. 10 // * Redistributions in binary form must reproduce the above copyright 11 // notice, this list of conditions and the following disclaimer in the 12 // documentation and/or other materials provided with the distribution. 13 // * Neither the name of Google Inc. nor the names of its contributors 14 // may be used to endorse or promote products derived from this software 15 // without specific prior written permission. 16 // 17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 29 /// \file utils/cmdline/options.hpp 30 /// Definitions of command-line options. 31 32 #if !defined(UTILS_CMDLINE_OPTIONS_HPP) 33 #define UTILS_CMDLINE_OPTIONS_HPP 34 35 #include <string> 36 #include <utility> 37 #include <vector> 38 39 #include "utils/fs/path.hpp" 40 41 namespace utils { 42 namespace cmdline { 43 44 45 /// Type-less base option class. 46 /// 47 /// This abstract class provides the most generic representation of options. It 48 /// allows defining options with both short and long names, with and without 49 /// arguments and with and without optional values. These are all the possible 50 /// combinations supported by the getopt_long(3) function, on which this is 51 /// built. 52 /// 53 /// The internal values (e.g. the default value) of a generic option are all 54 /// represented as strings. However, from the caller's perspective, this is 55 /// suboptimal. Hence why this class must be specialized: the subclasses 56 /// provide type-specific accessors and provide automatic validation of the 57 /// types (e.g. a string '3foo' is not passed to an integer option). 58 /// 59 /// Given that subclasses are used through templatized code, they must provide: 60 /// 61 /// <ul> 62 /// <li>A public option_type typedef that defines the type of the 63 /// option.</li> 64 /// 65 /// <li>A convert() method that takes a string and converts it to 66 /// option_type. The string can be assumed to be convertible to the 67 /// destination type. Should not raise exceptions.</li> 68 /// 69 /// <li>A validate() method that matches the implementation of convert(). 70 /// This method can throw option_argument_value_error if the string cannot 71 /// be converted appropriately. If validate() does not throw, then 72 /// convert() must execute successfully.</li> 73 /// </ul> 74 /// 75 /// TODO(jmmv): Many methods in this class are split into two parts: has_foo() 76 /// and foo(), the former to query if the foo is available and the latter to get 77 /// the foo. It'd be very nice if we'd use something similar Boost.Optional to 78 /// simplify this interface altogether. 79 class base_option { 80 /// Short name of the option; 0 to indicate that none is available. 81 char _short_name; 82 83 /// Long name of the option. 84 std::string _long_name; 85 86 /// Textual description of the purpose of the option. 87 std::string _description; 88 89 /// Descriptive name of the required argument; empty if not allowed. 90 std::string _arg_name; 91 92 /// Whether the option has a default value or not. 93 /// 94 /// \todo We should probably be using the optional class here. 95 bool _has_default_value; 96 97 /// If _has_default_value is true, the default value. 98 std::string _default_value; 99 100 public: 101 base_option(const char, const char*, const char*, const char* = NULL, 102 const char* = NULL); 103 base_option(const char*, const char*, const char* = NULL, 104 const char* = NULL); 105 virtual ~base_option(void); 106 107 bool has_short_name(void) const; 108 char short_name(void) const; 109 const std::string& long_name(void) const; 110 const std::string& description(void) const; 111 112 bool needs_arg(void) const; 113 const std::string& arg_name(void) const; 114 115 bool has_default_value(void) const; 116 const std::string& default_value(void) const; 117 118 std::string format_short_name(void) const; 119 std::string format_long_name(void) const; 120 121 virtual void validate(const std::string&) const; 122 }; 123 124 125 /// Definition of a boolean option. 126 /// 127 /// A boolean option can be specified once in the command line, at which point 128 /// is set to true. Such an option cannot carry optional arguments. 129 class bool_option : public base_option { 130 public: 131 bool_option(const char, const char*, const char*); 132 bool_option(const char*, const char*); ~bool_option(void)133 virtual ~bool_option(void) {} 134 135 /// The data type of this option. 136 typedef bool option_type; 137 }; 138 139 140 /// Definition of an integer option. 141 class int_option : public base_option { 142 public: 143 int_option(const char, const char*, const char*, const char*, 144 const char* = NULL); 145 int_option(const char*, const char*, const char*, const char* = NULL); ~int_option(void)146 virtual ~int_option(void) {} 147 148 /// The data type of this option. 149 typedef int option_type; 150 151 virtual void validate(const std::string& str) const; 152 static int convert(const std::string& str); 153 }; 154 155 156 /// Definition of a comma-separated list of strings. 157 class list_option : public base_option { 158 public: 159 list_option(const char, const char*, const char*, const char*, 160 const char* = NULL); 161 list_option(const char*, const char*, const char*, const char* = NULL); ~list_option(void)162 virtual ~list_option(void) {} 163 164 /// The data type of this option. 165 typedef std::vector< std::string > option_type; 166 167 virtual void validate(const std::string&) const; 168 static option_type convert(const std::string&); 169 }; 170 171 172 /// Definition of an option representing a path. 173 /// 174 /// The path pointed to by the option may not exist, but it must be 175 /// syntactically valid. 176 class path_option : public base_option { 177 public: 178 path_option(const char, const char*, const char*, const char*, 179 const char* = NULL); 180 path_option(const char*, const char*, const char*, const char* = NULL); ~path_option(void)181 virtual ~path_option(void) {} 182 183 /// The data type of this option. 184 typedef utils::fs::path option_type; 185 186 virtual void validate(const std::string&) const; 187 static utils::fs::path convert(const std::string&); 188 }; 189 190 191 /// Definition of a property option. 192 /// 193 /// A property option is an option whose required arguments are of the form 194 /// 'name=value'. Both components of the property are treated as free-form 195 /// non-empty strings; any other validation must happen on the caller side. 196 /// 197 /// \todo Would be nice if the delimiter was parametrizable. With the current 198 /// parser interface (convert() being a static method), the only way to do 199 /// this would be to templatize this class. 200 class property_option : public base_option { 201 public: 202 property_option(const char, const char*, const char*, const char*); 203 property_option(const char*, const char*, const char*); ~property_option(void)204 virtual ~property_option(void) {} 205 206 /// The data type of this option. 207 typedef std::pair< std::string, std::string > option_type; 208 209 virtual void validate(const std::string& str) const; 210 static option_type convert(const std::string& str); 211 }; 212 213 214 /// Definition of a free-form string option. 215 /// 216 /// This class provides no restrictions on the argument passed to the option. 217 class string_option : public base_option { 218 public: 219 string_option(const char, const char*, const char*, const char*, 220 const char* = NULL); 221 string_option(const char*, const char*, const char*, const char* = NULL); ~string_option(void)222 virtual ~string_option(void) {} 223 224 /// The data type of this option. 225 typedef std::string option_type; 226 227 virtual void validate(const std::string& str) const; 228 static std::string convert(const std::string& str); 229 }; 230 231 232 } // namespace cmdline 233 } // namespace utils 234 235 #endif // !defined(UTILS_CMDLINE_OPTIONS_HPP) 236