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 #include "utils/cmdline/options.hpp" 30 31 #include <stdexcept> 32 #include <vector> 33 34 #include "utils/cmdline/exceptions.hpp" 35 #include "utils/defs.hpp" 36 #include "utils/format/macros.hpp" 37 #include "utils/fs/exceptions.hpp" 38 #include "utils/sanity.hpp" 39 #include "utils/text/operations.ipp" 40 41 namespace cmdline = utils::cmdline; 42 namespace text = utils::text; 43 44 #if defined(__minix) && defined(NDEBUG) 45 #undef PRE_MSG 46 #define PRE_MSG(expr, msg) \ 47 do { \ 48 if (!(expr)) \ 49 utils::sanity_failure(utils::precondition, __FILE__, __LINE__, msg); \ 50 } while (0) 51 #endif /* defined(__minix) && defined(NDEBUG) */ 52 53 /// Constructs a generic option with both a short and a long name. 54 /// 55 /// \param short_name_ The short name for the option. 56 /// \param long_name_ The long name for the option. 57 /// \param description_ A user-friendly description for the option. 58 /// \param arg_name_ If not NULL, specifies that the option must receive an 59 /// argument and specifies the name of such argument for documentation 60 /// purposes. 61 /// \param default_value_ If not NULL, specifies that the option has a default 62 /// value for the mandatory argument. 63 cmdline::base_option::base_option(const char short_name_, 64 const char* long_name_, 65 const char* description_, 66 const char* arg_name_, 67 const char* default_value_) : 68 _short_name(short_name_), 69 _long_name(long_name_), 70 _description(description_), 71 _arg_name(arg_name_ == NULL ? "" : arg_name_), 72 _has_default_value(default_value_ != NULL), 73 _default_value(default_value_ == NULL ? "" : default_value_) 74 { 75 INV(short_name_ != '\0'); 76 } 77 78 79 /// Constructs a generic option with a long name only. 80 /// 81 /// \param long_name_ The long name for the option. 82 /// \param description_ A user-friendly description for the option. 83 /// \param arg_name_ If not NULL, specifies that the option must receive an 84 /// argument and specifies the name of such argument for documentation 85 /// purposes. 86 /// \param default_value_ If not NULL, specifies that the option has a default 87 /// value for the mandatory argument. 88 cmdline::base_option::base_option(const char* long_name_, 89 const char* description_, 90 const char* arg_name_, 91 const char* default_value_) : 92 _short_name('\0'), 93 _long_name(long_name_), 94 _description(description_), 95 _arg_name(arg_name_ == NULL ? "" : arg_name_), 96 _has_default_value(default_value_ != NULL), 97 _default_value(default_value_ == NULL ? "" : default_value_) 98 { 99 } 100 101 102 /// Destructor for the option. 103 cmdline::base_option::~base_option(void) 104 { 105 } 106 107 108 /// Checks whether the option has a short name or not. 109 /// 110 /// \return True if the option has a short name, false otherwise. 111 bool 112 cmdline::base_option::has_short_name(void) const 113 { 114 return _short_name != '\0'; 115 } 116 117 118 /// Returns the short name of the option. 119 /// 120 /// \pre has_short_name() must be true. 121 /// 122 /// \return The short name. 123 char 124 cmdline::base_option::short_name(void) const 125 { 126 PRE(has_short_name()); 127 return _short_name; 128 } 129 130 131 /// Returns the long name of the option. 132 /// 133 /// \return The long name. 134 const std::string& 135 cmdline::base_option::long_name(void) const 136 { 137 return _long_name; 138 } 139 140 141 /// Returns the description of the option. 142 /// 143 /// \return The description. 144 const std::string& 145 cmdline::base_option::description(void) const 146 { 147 return _description; 148 } 149 150 151 /// Checks whether the option needs an argument or not. 152 /// 153 /// \return True if the option needs an argument, false otherwise. 154 bool 155 cmdline::base_option::needs_arg(void) const 156 { 157 return !_arg_name.empty(); 158 } 159 160 161 /// Returns the argument name of the option for documentation purposes. 162 /// 163 /// \pre needs_arg() must be true. 164 /// 165 /// \return The argument name. 166 const std::string& 167 cmdline::base_option::arg_name(void) const 168 { 169 INV(needs_arg()); 170 return _arg_name; 171 } 172 173 174 /// Checks whether the option has a default value for its argument. 175 /// 176 /// \pre needs_arg() must be true. 177 /// 178 /// \return True if the option has a default value, false otherwise. 179 bool 180 cmdline::base_option::has_default_value(void) const 181 { 182 PRE(needs_arg()); 183 return _has_default_value; 184 } 185 186 187 /// Returns the default value for the argument to the option. 188 /// 189 /// \pre has_default_value() must be true. 190 /// 191 /// \return The default value. 192 const std::string& 193 cmdline::base_option::default_value(void) const 194 { 195 INV(has_default_value()); 196 return _default_value;; 197 } 198 199 200 /// Formats the short name of the option for documentation purposes. 201 /// 202 /// \return A string describing the option's short name. 203 std::string 204 cmdline::base_option::format_short_name(void) const 205 { 206 PRE(has_short_name()); 207 208 if (needs_arg()) { 209 return F("-%s %s") % short_name() % arg_name(); 210 } else { 211 return F("-%s") % short_name(); 212 } 213 } 214 215 216 /// Formats the long name of the option for documentation purposes. 217 /// 218 /// \return A string describing the option's long name. 219 std::string 220 cmdline::base_option::format_long_name(void) const 221 { 222 if (needs_arg()) { 223 return F("--%s=%s") % long_name() % arg_name(); 224 } else { 225 return F("--%s") % long_name(); 226 } 227 } 228 229 230 231 /// Ensures that an argument passed to the option is valid. 232 /// 233 /// This must be reimplemented by subclasses that describe options with 234 /// arguments. 235 /// 236 /// \param unused_str The argument to validate as provided by the user in the 237 /// command line. 238 /// 239 /// \throw cmdline::option_argument_value_error Subclasses must raise this 240 /// exception to indicate the cases in which str is invalid. 241 void 242 cmdline::base_option::validate(const std::string& UTILS_UNUSED_PARAM(str)) const 243 { 244 UNREACHABLE_MSG("Option does not support an argument"); 245 } 246 247 248 /// Constructs a boolean option with both a short and a long name. 249 /// 250 /// \param short_name_ The short name for the option. 251 /// \param long_name_ The long name for the option. 252 /// \param description_ A user-friendly description for the option. 253 cmdline::bool_option::bool_option(const char short_name_, 254 const char* long_name_, 255 const char* description_) : 256 base_option(short_name_, long_name_, description_) 257 { 258 } 259 260 261 /// Constructs a boolean option with a long name only. 262 /// 263 /// \param long_name_ The long name for the option. 264 /// \param description_ A user-friendly description for the option. 265 cmdline::bool_option::bool_option(const char* long_name_, 266 const char* description_) : 267 base_option(long_name_, description_) 268 { 269 } 270 271 272 /// Constructs an integer option with both a short and a long name. 273 /// 274 /// \param short_name_ The short name for the option. 275 /// \param long_name_ The long name for the option. 276 /// \param description_ A user-friendly description for the option. 277 /// \param arg_name_ The name of the mandatory argument, for documentation 278 /// purposes. 279 /// \param default_value_ If not NULL, the default value for the mandatory 280 /// argument. 281 cmdline::int_option::int_option(const char short_name_, 282 const char* long_name_, 283 const char* description_, 284 const char* arg_name_, 285 const char* default_value_) : 286 base_option(short_name_, long_name_, description_, arg_name_, 287 default_value_) 288 { 289 } 290 291 292 /// Constructs an integer option with a long name only. 293 /// 294 /// \param long_name_ The long name for the option. 295 /// \param description_ A user-friendly description for the option. 296 /// \param arg_name_ The name of the mandatory argument, for documentation 297 /// purposes. 298 /// \param default_value_ If not NULL, the default value for the mandatory 299 /// argument. 300 cmdline::int_option::int_option(const char* long_name_, 301 const char* description_, 302 const char* arg_name_, 303 const char* default_value_) : 304 base_option(long_name_, description_, arg_name_, default_value_) 305 { 306 } 307 308 309 /// Ensures that an integer argument passed to the int_option is valid. 310 /// 311 /// \param raw_value The argument representing an integer as provided by the 312 /// user. 313 /// 314 /// \throw cmdline::option_argument_value_error If the integer provided in 315 /// raw_value is invalid. 316 void 317 cmdline::int_option::validate(const std::string& raw_value) const 318 { 319 try { 320 (void)text::to_type< int >(raw_value); 321 } catch (const std::runtime_error& e) { 322 throw cmdline::option_argument_value_error( 323 F("--%s") % long_name(), raw_value, "Not a valid integer"); 324 } 325 } 326 327 328 /// Converts an integer argument to a native integer. 329 /// 330 /// \param raw_value The argument representing an integer as provided by the 331 /// user. 332 /// 333 /// \return The integer. 334 /// 335 /// \pre validate(raw_value) must be true. 336 int 337 cmdline::int_option::convert(const std::string& raw_value) 338 { 339 try { 340 return text::to_type< int >(raw_value); 341 } catch (const std::runtime_error& e) { 342 PRE_MSG(false, F("Raw value '%s' for int option not properly " 343 "validated: %s") % raw_value % e.what()); 344 } 345 } 346 347 348 /// Constructs a list option with both a short and a long name. 349 /// 350 /// \param short_name_ The short name for the option. 351 /// \param long_name_ The long name for the option. 352 /// \param description_ A user-friendly description for the option. 353 /// \param arg_name_ The name of the mandatory argument, for documentation 354 /// purposes. 355 /// \param default_value_ If not NULL, the default value for the mandatory 356 /// argument. 357 cmdline::list_option::list_option(const char short_name_, 358 const char* long_name_, 359 const char* description_, 360 const char* arg_name_, 361 const char* default_value_) : 362 base_option(short_name_, long_name_, description_, arg_name_, 363 default_value_) 364 { 365 } 366 367 368 /// Constructs a list option with a long name only. 369 /// 370 /// \param long_name_ The long name for the option. 371 /// \param description_ A user-friendly description for the option. 372 /// \param arg_name_ The name of the mandatory argument, for documentation 373 /// purposes. 374 /// \param default_value_ If not NULL, the default value for the mandatory 375 /// argument. 376 cmdline::list_option::list_option(const char* long_name_, 377 const char* description_, 378 const char* arg_name_, 379 const char* default_value_) : 380 base_option(long_name_, description_, arg_name_, default_value_) 381 { 382 } 383 384 385 /// Ensures that a lisstring argument passed to the list_option is valid. 386 /// 387 /// \param unused_raw_value The argument representing a list as provided by the 388 /// user. 389 void 390 cmdline::list_option::validate( 391 const std::string& UTILS_UNUSED_PARAM(raw_value)) const 392 { 393 // Any list is potentially valid; the caller must check for semantics. 394 } 395 396 397 /// Converts a string argument to a vector. 398 /// 399 /// \param raw_value The argument representing a list as provided by the user. 400 /// 401 /// \return The list. 402 /// 403 /// \pre validate(raw_value) must be true. 404 cmdline::list_option::option_type 405 cmdline::list_option::convert(const std::string& raw_value) 406 { 407 try { 408 return text::split(raw_value, ','); 409 } catch (const std::runtime_error& e) { 410 PRE_MSG(false, F("Raw value '%s' for list option not properly " 411 "validated: %s") % raw_value % e.what()); 412 } 413 } 414 415 416 /// Constructs a path option with both a short and a long name. 417 /// 418 /// \param short_name_ The short name for the option. 419 /// \param long_name_ The long name for the option. 420 /// \param description_ A user-friendly description for the option. 421 /// \param arg_name_ The name of the mandatory argument, for documentation 422 /// purposes. 423 /// \param default_value_ If not NULL, the default value for the mandatory 424 /// argument. 425 cmdline::path_option::path_option(const char short_name_, 426 const char* long_name_, 427 const char* description_, 428 const char* arg_name_, 429 const char* default_value_) : 430 base_option(short_name_, long_name_, description_, arg_name_, 431 default_value_) 432 { 433 } 434 435 436 /// Constructs a path option with a long name only. 437 /// 438 /// \param long_name_ The long name for the option. 439 /// \param description_ A user-friendly description for the option. 440 /// \param arg_name_ The name of the mandatory argument, for documentation 441 /// purposes. 442 /// \param default_value_ If not NULL, the default value for the mandatory 443 /// argument. 444 cmdline::path_option::path_option(const char* long_name_, 445 const char* description_, 446 const char* arg_name_, 447 const char* default_value_) : 448 base_option(long_name_, description_, arg_name_, default_value_) 449 { 450 } 451 452 453 /// Ensures that a path argument passed to the path_option is valid. 454 /// 455 /// \param raw_value The argument representing a path as provided by the user. 456 /// 457 /// \throw cmdline::option_argument_value_error If the path provided in 458 /// raw_value is invalid. 459 void 460 cmdline::path_option::validate(const std::string& raw_value) const 461 { 462 try { 463 (void)utils::fs::path(raw_value); 464 } catch (const utils::fs::error& e) { 465 throw cmdline::option_argument_value_error(F("--%s") % long_name(), 466 raw_value, e.what()); 467 } 468 } 469 470 471 /// Converts a path argument to a utils::fs::path. 472 /// 473 /// \param raw_value The argument representing a path as provided by the user. 474 /// 475 /// \return The path. 476 /// 477 /// \pre validate(raw_value) must be true. 478 utils::fs::path 479 cmdline::path_option::convert(const std::string& raw_value) 480 { 481 try { 482 return utils::fs::path(raw_value); 483 } catch (const std::runtime_error& e) { 484 PRE_MSG(false, F("Raw value '%s' for path option not properly " 485 "validated: %s") % raw_value % e.what()); 486 } 487 } 488 489 490 /// Constructs a property option with both a short and a long name. 491 /// 492 /// \param short_name_ The short name for the option. 493 /// \param long_name_ The long name for the option. 494 /// \param description_ A user-friendly description for the option. 495 /// \param arg_name_ The name of the mandatory argument, for documentation 496 /// purposes. Must include the '=' delimiter. 497 cmdline::property_option::property_option(const char short_name_, 498 const char* long_name_, 499 const char* description_, 500 const char* arg_name_) : 501 base_option(short_name_, long_name_, description_, arg_name_) 502 { 503 PRE(arg_name().find('=') != std::string::npos); 504 } 505 506 507 /// Constructs a property option with a long name only. 508 /// 509 /// \param long_name_ The long name for the option. 510 /// \param description_ A user-friendly description for the option. 511 /// \param arg_name_ The name of the mandatory argument, for documentation 512 /// purposes. Must include the '=' delimiter. 513 cmdline::property_option::property_option(const char* long_name_, 514 const char* description_, 515 const char* arg_name_) : 516 base_option(long_name_, description_, arg_name_) 517 { 518 PRE(arg_name().find('=') != std::string::npos); 519 } 520 521 522 /// Validates the argument to a property option. 523 /// 524 /// \param raw_value The argument provided by the user. 525 void 526 cmdline::property_option::validate(const std::string& raw_value) const 527 { 528 const std::string::size_type pos = raw_value.find('='); 529 if (pos == std::string::npos) 530 throw cmdline::option_argument_value_error( 531 F("--%s") % long_name(), raw_value, 532 F("Argument does not have the form '%s'") % arg_name()); 533 534 const std::string key = raw_value.substr(0, pos); 535 if (key.empty()) 536 throw cmdline::option_argument_value_error( 537 F("--%s") % long_name(), raw_value, "Empty property name"); 538 539 const std::string value = raw_value.substr(pos + 1); 540 if (value.empty()) 541 throw cmdline::option_argument_value_error( 542 F("--%s") % long_name(), raw_value, "Empty value"); 543 } 544 545 546 /// Returns the property option in a key/value pair form. 547 /// 548 /// \param raw_value The argument provided by the user. 549 /// 550 /// \return raw_value The key/value pair representation of the property. 551 /// 552 /// \pre validate(raw_value) must be true. 553 cmdline::property_option::option_type 554 cmdline::property_option::convert(const std::string& raw_value) 555 { 556 const std::string::size_type pos = raw_value.find('='); 557 return std::make_pair(raw_value.substr(0, pos), raw_value.substr(pos + 1)); 558 } 559 560 561 /// Constructs a string option with both a short and a long name. 562 /// 563 /// \param short_name_ The short name for the option. 564 /// \param long_name_ The long name for the option. 565 /// \param description_ A user-friendly description for the option. 566 /// \param arg_name_ The name of the mandatory argument, for documentation 567 /// purposes. 568 /// \param default_value_ If not NULL, the default value for the mandatory 569 /// argument. 570 cmdline::string_option::string_option(const char short_name_, 571 const char* long_name_, 572 const char* description_, 573 const char* arg_name_, 574 const char* default_value_) : 575 base_option(short_name_, long_name_, description_, arg_name_, 576 default_value_) 577 { 578 } 579 580 581 /// Constructs a string option with a long name only. 582 /// 583 /// \param long_name_ The long name for the option. 584 /// \param description_ A user-friendly description for the option. 585 /// \param arg_name_ The name of the mandatory argument, for documentation 586 /// purposes. 587 /// \param default_value_ If not NULL, the default value for the mandatory 588 /// argument. 589 cmdline::string_option::string_option(const char* long_name_, 590 const char* description_, 591 const char* arg_name_, 592 const char* default_value_) : 593 base_option(long_name_, description_, arg_name_, default_value_) 594 { 595 } 596 597 598 /// Does nothing; all string values are valid arguments to a string_option. 599 /// 600 /// \param unused_raw_value The argument provided by the user. 601 void 602 cmdline::string_option::validate( 603 const std::string& UTILS_UNUSED_PARAM(raw_value)) const 604 { 605 // Nothing to do. 606 } 607 608 609 /// Returns the string unmodified. 610 /// 611 /// \param raw_value The argument provided by the user. 612 /// 613 /// \return raw_value 614 /// 615 /// \pre validate(raw_value) must be true. 616 std::string 617 cmdline::string_option::convert(const std::string& raw_value) 618 { 619 return raw_value; 620 } 621