1 /** 2 * @file ConversionOption.h 3 * @brief Definition of ConversionOption, the class encapsulating conversion options. 4 * @author Frank Bergmann 5 * 6 * <!-------------------------------------------------------------------------- 7 * This file is part of libSBML. Please visit http://sbml.org for more 8 * information about SBML, and the latest version of libSBML. 9 * 10 * Copyright (C) 2020 jointly by the following organizations: 11 * 1. California Institute of Technology, Pasadena, CA, USA 12 * 2. University of Heidelberg, Heidelberg, Germany 13 * 3. University College London, London, UK 14 * 15 * Copyright (C) 2019 jointly by the following organizations: 16 * 1. California Institute of Technology, Pasadena, CA, USA 17 * 2. University of Heidelberg, Heidelberg, Germany 18 * 19 * Copyright (C) 2013-2018 jointly by the following organizations: 20 * 1. California Institute of Technology, Pasadena, CA, USA 21 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 22 * 3. University of Heidelberg, Heidelberg, Germany 23 * 24 * Copyright (C) 2009-2013 jointly by the following organizations: 25 * 1. California Institute of Technology, Pasadena, CA, USA 26 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 27 * 28 * Copyright (C) 2006-2008 by the California Institute of Technology, 29 * Pasadena, CA, USA 30 * 31 * Copyright (C) 2002-2005 jointly by the following organizations: 32 * 1. California Institute of Technology, Pasadena, CA, USA 33 * 2. Japan Science and Technology Agency, Japan 34 * 35 * This library is free software; you can redistribute it and/or modify it 36 * under the terms of the GNU Lesser General Public License as published by 37 * the Free Software Foundation. A copy of the license agreement is provided 38 * in the file named "LICENSE.txt" included with this software distribution 39 * and also available online as http://sbml.org/software/libsbml/license.html 40 * ------------------------------------------------------------------------ --> 41 * 42 * @class ConversionOption 43 * @sbmlbrief{core} A single configuration setting for an SBML converter. 44 * 45 * @htmlinclude libsbml-facility-only-warning.html 46 * 47 * LibSBML provides a number of converters that can perform transformations 48 * on SBML documents. These converters allow their behaviors to be 49 * controlled by setting property values. Converter properties are 50 * communicated using objects of class ConversionProperties, and within 51 * such objects, individual options are encapsulated using ConversionOption 52 * objects. 53 * 54 * A ConversionOption @if conly structure @else object@endif@~ consists of 55 * four parts: 56 * @li A @em key, acting as the name of the option. 57 * @li A @em value of this option. 58 * @li A @em type for the value; the type code is chosen from @if clike 59 * an enumeration @else a set of integer constants@endif@~ whose names all 60 * begin with the prefix <code>CNV_TYPE_</code>. (See the separate <a 61 * class="el" href="#ConversionOptionType_t">subsection</a> below for more 62 * information.) 63 * @li A @em description consisting of a text string that describes the 64 * option in some way. 65 * 66 * There are no constraints on the values of keys or descriptions; 67 * authors of SBML converters are free to choose them as they see fit. 68 * 69 * @section ConversionOptionType_t Conversion option data types 70 * 71 * An option in ConversionOption must have a data type declared, to 72 * indicate whether it is a string value, an integer, and so forth. The 73 * possible types of values are taken from 74 * @if clike the enumeration #ConversionOptionType_t @else a set of 75 * constants whose symbol names begin with the prefix 76 * <code>CNV_TYPE_</code>@endif. The following are the possible values: 77 * 78 * <p> 79 * <center> 80 * <table width="90%" cellspacing="1" cellpadding="1" border="0" class="normal-font"> 81 * <tr style="background: lightgray" class="normal-font"> 82 * <td><strong>Enumerator</strong></td> 83 * <td><strong>Meaning</strong></td> 84 * </tr> 85 * <tr> 86 * <td><code>@sbmlconstant{CNV_TYPE_BOOL, ConversionOptionType_t}</code></td> 87 * <td>Indicates the value type is a Boolean.</td> 88 * </tr> 89 * <tr> 90 * <td><code>@sbmlconstant{CNV_TYPE_DOUBLE, ConversionOptionType_t}</code></td> 91 * <td>Indicates the value type is a double-sized float.</td> 92 * </tr> 93 * <tr> 94 * <td><code>@sbmlconstant{CNV_TYPE_INT, ConversionOptionType_t}</code></td> 95 * <td>Indicates the value type is an integer.</td> 96 * </tr> 97 * <tr> 98 * <td><code>@sbmlconstant{CNV_TYPE_SINGLE, ConversionOptionType_t}</code></td> 99 * <td>Indicates the value type is a float.</td> 100 * </tr> 101 * <tr> 102 * <td><code>@sbmlconstant{CNV_TYPE_STRING, ConversionOptionType_t}</code></td> 103 * <td>Indicates the value type is a string.</td> 104 * </tr> 105 * </table> 106 * </center> 107 * 108 * @see ConversionProperties 109 */ 110 111 /** 112 * <!-- ~ ~ ~ ~ ~ Start of common documentation strings ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ 113 * The following text is used as common documentation blocks copied multiple 114 * times elsewhere in this file. The use of @class is a hack needed because 115 * Doxygen's @copydetails command has limited functionality. Symbols 116 * beginning with "doc_" are marked as ignored in our Doxygen configuration. 117 * ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ --> 118 * 119 * @class doc_cnv_type 120 * 121 * @par 122 * The conversion @p type argument value must be one of 123 * @if clike the values defined in the enumeration 124 * #ConversionOptionType_t.@endif@if java the constants whose names begin 125 * with the characters <code>CNV_TYPE_</code> in the interface class 126 * {@link libsbmlConstants}.@endif@if python the constants whose names begin 127 * with the characters <code>CNV_TYPE_</code> in the interface class 128 * @link libsbml libsbml@endlink.@endif 129 */ 130 131 #ifndef ConversionOption_h 132 #define ConversionOption_h 133 134 135 #include <sbml/common/extern.h> 136 #include <sbml/common/sbmlfwd.h> 137 138 LIBSBML_CPP_NAMESPACE_BEGIN 139 140 /** 141 * @enum ConversionOptionType_t 142 * @brief ConversionOptionType_t is the enumeration of possible option types. 143 */ 144 typedef enum 145 { 146 CNV_TYPE_BOOL /*!< The Boolean option value type. */ 147 , CNV_TYPE_DOUBLE /*!< The double-sized float option value type. */ 148 , CNV_TYPE_INT /*!< The integer option value type. */ 149 , CNV_TYPE_SINGLE /*!< The float option value type. */ 150 , CNV_TYPE_STRING /*!< The string option value type. */ 151 } ConversionOptionType_t; 152 153 LIBSBML_CPP_NAMESPACE_END 154 155 156 #ifdef __cplusplus 157 #include <string> 158 159 LIBSBML_CPP_NAMESPACE_BEGIN 160 161 162 class LIBSBML_EXTERN ConversionOption 163 { 164 public: 165 166 /** 167 * Creates a new ConversionOption. 168 * 169 * This is the general constructor, taking arguments for all aspects of 170 * an option. Other constructors exist with different arguments. 171 * 172 * @copydetails doc_cnv_type 173 * 174 * @param key the key for this option. 175 * @param value an optional value for this option. 176 * @param type the type of this option. 177 * @param description the description for this option. 178 * 179 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 180 */ 181 ConversionOption(const std::string& key, const std::string value="", 182 ConversionOptionType_t type=CNV_TYPE_STRING, 183 const std::string description=""); 184 185 186 /** 187 * Creates a new ConversionOption specialized for string-type options. 188 * 189 * @param key the key for this option. 190 * @param value the value for this option. 191 * @param description an optional description. 192 * 193 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 194 */ 195 ConversionOption(const std::string& key, const char* value, 196 const std::string description=""); 197 198 199 /** 200 * Creates a new ConversionOption specialized for Boolean-type options. 201 * 202 * @param key the key for this option. 203 * @param value the value for this option. 204 * @param description an optional description. 205 * 206 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 207 */ 208 ConversionOption(const std::string& key, bool value, 209 const std::string description=""); 210 211 212 /** 213 * Creates a new ConversionOption specialized for double-type options. 214 * 215 * @param key the key for this option. 216 * @param value the value for this option. 217 * @param description an optional description. 218 * 219 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 220 */ 221 ConversionOption(const std::string& key, double value, 222 const std::string description=""); 223 224 225 /** 226 * Creates a new ConversionOption specialized for float-type options. 227 * 228 * @param key the key for this option. 229 * @param value the value for this option. 230 * @param description an optional description. 231 * 232 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 233 */ 234 ConversionOption(const std::string& key, float value, 235 const std::string description=""); 236 237 238 /** 239 * Creates a new ConversionOption specialized for integer-type options. 240 * 241 * @param key the key for this option. 242 * @param value the value for this option. 243 * @param description an optional description. 244 * 245 * @ifnot hasDefaultArgs @htmlinclude warn-default-args-in-docs.html @endif@~ 246 */ 247 ConversionOption(const std::string& key, int value, 248 const std::string description=""); 249 250 251 /** 252 * Copy constructor; creates a copy of an ConversionOption object. 253 * 254 * @param orig the ConversionOption object to copy. 255 */ 256 ConversionOption(const ConversionOption& orig); 257 258 259 /** 260 * Assignment operator for ConversionOption. 261 * 262 * @param rhs the object whose values are used as the basis of the 263 * assignment. 264 */ 265 ConversionOption& operator=(const ConversionOption& rhs); 266 267 268 /** 269 * Destroys this object. 270 */ 271 virtual ~ConversionOption(); 272 273 274 /** 275 * Creates and returns a deep copy of this ConversionOption object. 276 * 277 * @return the (deep) copy of this ConversionOption object. 278 */ 279 virtual ConversionOption* clone() const; 280 281 282 /** 283 * Returns the key for this option. 284 * 285 * @return the key, as a string. 286 */ 287 const std::string& getKey() const; 288 289 290 /** 291 * Sets the key for this option. 292 * 293 * @param key a string representing the key to set. 294 */ 295 void setKey(const std::string& key); 296 297 298 /** 299 * Returns the value of this option. 300 * 301 * @return the value of this option, as a string. 302 */ 303 const std::string& getValue() const; 304 305 306 /** 307 * Sets the value for this option. 308 * 309 * @param value the value to set, as a string. 310 */ 311 void setValue(const std::string& value); 312 313 314 /** 315 * Returns the description string for this option. 316 * 317 * @return the description of this option. 318 */ 319 const std::string& getDescription() const; 320 321 322 /** 323 * Sets the description text for this option. 324 * 325 * @param description the description to set for this option. 326 */ 327 void setDescription(const std::string& description); 328 329 330 /** 331 * Returns the type of this option 332 * 333 * @return the type of this option. 334 */ 335 ConversionOptionType_t getType() const; 336 337 338 /** 339 * Sets the type of this option. 340 * 341 * @copydetails doc_cnv_type 342 * 343 * @param type the type value to use. 344 */ 345 void setType(ConversionOptionType_t type); 346 347 348 /** 349 * Returns the value of this option as a Boolean. 350 * 351 * @return the value of this option. 352 */ 353 virtual bool getBoolValue() const; 354 355 356 /** 357 * Set the value of this option to a given Boolean value. 358 * 359 * Invoking this method will also set the type of the option to 360 * @sbmlconstant{CNV_TYPE_BOOL, ConversionOptionType_t}. 361 * 362 * @param value the Boolean value to set. 363 */ 364 virtual void setBoolValue(bool value); 365 366 367 /** 368 * Returns the value of this option as a @c double. 369 * 370 * @return the value of this option. 371 */ 372 virtual double getDoubleValue() const; 373 374 375 /** 376 * Set the value of this option to a given @c double value. 377 * 378 * Invoking this method will also set the type of the option to 379 * @sbmlconstant{CNV_TYPE_DOUBLE, ConversionOptionType_t}. 380 * 381 * @param value the value to set. 382 */ 383 virtual void setDoubleValue(double value); 384 385 386 /** 387 * Returns the value of this option as a @c float. 388 * 389 * @return the value of this option as a float. 390 */ 391 virtual float getFloatValue() const; 392 393 394 /** 395 * Set the value of this option to a given @c float value. 396 * 397 * Invoking this method will also set the type of the option to 398 * @sbmlconstant{CNV_TYPE_SINGLE, ConversionOptionType_t}. 399 * 400 * @param value the value to set. 401 */ 402 virtual void setFloatValue(float value); 403 404 405 /** 406 * Returns the value of this option as an @c integer. 407 * 408 * @return the value of this option, as an int. 409 */ 410 virtual int getIntValue() const; 411 412 413 /** 414 * Set the value of this option to a given @c int value. 415 * 416 * Invoking this method will also set the type of the option to 417 * @sbmlconstant{CNV_TYPE_INT, ConversionOptionType_t}. 418 * 419 * @param value the value to set. 420 */ 421 virtual void setIntValue(int value); 422 423 424 protected: 425 /** @cond doxygenLibsbmlInternal */ 426 std::string mKey; 427 std::string mValue; 428 ConversionOptionType_t mType; 429 std::string mDescription; 430 431 /** @endcond */ 432 }; 433 434 LIBSBML_CPP_NAMESPACE_END 435 436 #endif /* __cplusplus */ 437 438 #ifndef SWIG 439 440 LIBSBML_CPP_NAMESPACE_BEGIN 441 BEGIN_C_DECLS 442 443 /** 444 * Creates a new ConversionOption_t with the given key. 445 * 446 * @param key the key for this option. 447 * 448 * @memberof ConversionOption_t 449 */ 450 LIBSBML_EXTERN 451 ConversionOption_t* 452 ConversionOption_create(const char* key); 453 454 /** 455 * Destroys this ConversionOption_t. 456 * 457 * @param co ConversionOption_t structure to be freed. 458 * 459 * @memberof ConversionOption_t 460 */ 461 LIBSBML_EXTERN 462 void 463 ConversionOption_free(ConversionOption_t* co); 464 465 /** 466 * Creates and returns a deep copy of the ConversionOption_t structure. 467 * 468 * @param co the conversion option to clone. 469 * 470 * @return a (deep) copy of the ConversionOption_t structure. 471 * 472 * @memberof ConversionOption_t 473 */ 474 LIBSBML_EXTERN 475 ConversionOption_t* 476 ConversionOption_clone(const ConversionOption_t* co); 477 478 /** 479 * Creates a new ConversionOption_t with given key and type. 480 * 481 * @param key the key for this option. 482 * @param type the type of this option. 483 * 484 * @memberof ConversionOption_t 485 */ 486 LIBSBML_EXTERN 487 ConversionOption_t* 488 ConversionOption_createWithKeyAndType(const char* key, ConversionOptionType_t type); 489 490 /** 491 * Returns the key for the given option. 492 * 493 * @param co the conversion option. 494 * 495 * @return the key, as a string. 496 * 497 * @memberof ConversionOption_t 498 */ 499 LIBSBML_EXTERN 500 const char* 501 ConversionOption_getKey(const ConversionOption_t* co); 502 503 /** 504 * Returns the description for the given option. 505 * 506 * @param co the conversion option. 507 * 508 * @return the description, as a string. 509 * 510 * @memberof ConversionOption_t 511 */ 512 LIBSBML_EXTERN 513 const char* 514 ConversionOption_getDescription(const ConversionOption_t* co); 515 516 /** 517 * Returns the value for the given option. 518 * 519 * @param co the conversion option. 520 * 521 * @return the value, as a string. 522 * 523 * @memberof ConversionOption_t 524 */ 525 LIBSBML_EXTERN 526 const char* 527 ConversionOption_getValue(const ConversionOption_t* co); 528 529 /** 530 * Returns the value (as boolean) for the given option. 531 * 532 * @param co the conversion option. 533 * 534 * @return the value, @c 1 (true), or @c 0 (false). 535 * 536 * @memberof ConversionOption_t 537 */ 538 LIBSBML_EXTERN 539 int 540 ConversionOption_getBoolValue(const ConversionOption_t* co); 541 542 /** 543 * Returns the value (as integer) for the given option. 544 * 545 * @param co the conversion option. 546 * 547 * @return the value, as a integer. 548 * 549 * @memberof ConversionOption_t 550 */ 551 LIBSBML_EXTERN 552 int 553 ConversionOption_getIntValue(const ConversionOption_t* co); 554 555 /** 556 * Returns the value (as float) for the given option. 557 * 558 * @param co the conversion option. 559 * 560 * @return the value, as a float. 561 * 562 * @memberof ConversionOption_t 563 */ 564 LIBSBML_EXTERN 565 float 566 ConversionOption_getFloatValue(const ConversionOption_t* co); 567 568 /** 569 * Returns the value (as double) for the given option. 570 * 571 * @param co the conversion option. 572 * 573 * @return the value, as a double. 574 * 575 * @memberof ConversionOption_t 576 */ 577 LIBSBML_EXTERN 578 double 579 ConversionOption_getDoubleValue(const ConversionOption_t* co); 580 581 /** 582 * Returns the type for the given option. 583 * 584 * @param co the conversion option. 585 * 586 * @return the type 587 * 588 * @memberof ConversionOption_t 589 */ 590 LIBSBML_EXTERN 591 ConversionOptionType_t 592 ConversionOption_getType(const ConversionOption_t* co); 593 594 /** 595 * Sets the key for the option. 596 * 597 * @param co the conversion option. 598 * @param key a string representing the key to set. 599 * 600 * @memberof ConversionOption_t 601 */ 602 LIBSBML_EXTERN 603 void 604 ConversionOption_setKey(ConversionOption_t* co, const char* key); 605 606 /** 607 * Sets the description for the option. 608 * 609 * @param co the conversion option. 610 * @param description a string representing the description to set. 611 * 612 * @memberof ConversionOption_t 613 */ 614 LIBSBML_EXTERN 615 void 616 ConversionOption_setDescription(ConversionOption_t* co, const char* description); 617 618 /** 619 * Sets the value for the option. 620 * 621 * @param co the conversion option. 622 * @param value a string representing the value to set. 623 * 624 * @memberof ConversionOption_t 625 */ 626 LIBSBML_EXTERN 627 void 628 ConversionOption_setValue(ConversionOption_t* co, const char* value); 629 630 /** 631 * Sets the value for the option. 632 * 633 * @param co the conversion option. 634 * @param value a bool representing the value to set. 635 * 636 * @memberof ConversionOption_t 637 */ 638 LIBSBML_EXTERN 639 void 640 ConversionOption_setBoolValue(ConversionOption_t* co, int value); 641 642 /** 643 * Sets the value for the option. 644 * 645 * @param co the conversion option. 646 * @param value an integer representing the value to set. 647 * 648 * @memberof ConversionOption_t 649 */ 650 LIBSBML_EXTERN 651 void 652 ConversionOption_setIntValue(ConversionOption_t* co, int value); 653 654 /** 655 * Sets the value for the option. 656 * 657 * @param co the conversion option. 658 * @param value a float representing the value to set. 659 * 660 * @memberof ConversionOption_t 661 */ 662 LIBSBML_EXTERN 663 void 664 ConversionOption_setFloatValue(ConversionOption_t* co, float value); 665 666 /** 667 * Sets the value for the option. 668 * 669 * @param co the conversion option. 670 * @param value a double representing the value to set. 671 * 672 * @memberof ConversionOption_t 673 */ 674 LIBSBML_EXTERN 675 void 676 ConversionOption_setDoubleValue(ConversionOption_t* co, double value); 677 678 /** 679 * Sets the type for the option. 680 * 681 * @param co the conversion option. 682 * @param type the type for this option. 683 * 684 * @memberof ConversionOption_t 685 */ 686 LIBSBML_EXTERN 687 void 688 ConversionOption_setType(ConversionOption_t* co, ConversionOptionType_t type); 689 690 691 END_C_DECLS 692 LIBSBML_CPP_NAMESPACE_END 693 694 #endif /* !SWIG */ 695 #endif /* !ConversionOption */ 696 697