1 /** 2 * @file SBasePlugin.h 3 * @brief Definition of SBasePlugin, the base class of extension entities 4 * plugged in SBase derived classes in the SBML Core package. 5 * @author Akiya Jouraku 6 * 7 * 8 * <!-------------------------------------------------------------------------- 9 * This file is part of libSBML. Please visit http://sbml.org for more 10 * information about SBML, and the latest version of libSBML. 11 * 12 * Copyright (C) 2020 jointly by the following organizations: 13 * 1. California Institute of Technology, Pasadena, CA, USA 14 * 2. University of Heidelberg, Heidelberg, Germany 15 * 3. University College London, London, UK 16 * 17 * Copyright (C) 2019 jointly by the following organizations: 18 * 1. California Institute of Technology, Pasadena, CA, USA 19 * 2. University of Heidelberg, Heidelberg, Germany 20 * 21 * Copyright (C) 2013-2018 jointly by the following organizations: 22 * 1. California Institute of Technology, Pasadena, CA, USA 23 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 24 * 3. University of Heidelberg, Heidelberg, Germany 25 * 26 * Copyright (C) 2009-2013 jointly by the following organizations: 27 * 1. California Institute of Technology, Pasadena, CA, USA 28 * 2. EMBL European Bioinformatics Institute (EMBL-EBI), Hinxton, UK 29 * 30 * Copyright (C) 2006-2008 by the California Institute of Technology, 31 * Pasadena, CA, USA 32 * 33 * Copyright (C) 2002-2005 jointly by the following organizations: 34 * 1. California Institute of Technology, Pasadena, CA, USA 35 * 2. Japan Science and Technology Agency, Japan 36 * 37 * This library is free software; you can redistribute it and/or modify it 38 * under the terms of the GNU Lesser General Public License as published by 39 * the Free Software Foundation. A copy of the license agreement is provided 40 * in the file named "LICENSE.txt" included with this software distribution 41 * and also available online as http://sbml.org/software/libsbml/license.html 42 * ------------------------------------------------------------------------ --> 43 * 44 * @class SBasePlugin 45 * @sbmlbrief{core} Base class for extending SBML objects in packages. 46 * 47 * @htmlinclude not-sbml-warning.html 48 * 49 * The SBasePlugin class is libSBML's base class for extensions of core SBML 50 * component objects. SBasePlugin defines basic virtual methods for 51 * reading/writing/checking additional attributes and/or subobjects; these 52 * methods should be overridden by subclasses to implement the necessary 53 * features of an extended SBML object. 54 * 55 * @if clike 56 * @section sbaseplugin-howto How to extend SBasePlugin for a package implementation 57 * @copydetails doc_extension_sbaseplugin 58 * @else 59 * @copydetails doc_basics_of_extensions 60 * @endif@~ 61 */ 62 63 #ifndef SBasePlugin_h 64 #define SBasePlugin_h 65 66 67 #include <sbml/common/sbmlfwd.h> 68 #include <sbml/SBase.h> 69 #include <sbml/SBMLTypeCodes.h> 70 #include <sbml/SBMLErrorLog.h> 71 #include <sbml/SBMLDocument.h> 72 73 #include <sbml/extension/SBMLExtension.h> 74 #include <sbml/extension/ASTBasePlugin.h> 75 76 77 #ifdef __cplusplus 78 79 LIBSBML_CPP_NAMESPACE_BEGIN 80 81 class LIBSBML_EXTERN SBasePlugin 82 { 83 public: 84 85 /** 86 * Destroy this SBasePlugin object. 87 */ 88 virtual ~SBasePlugin (); 89 90 91 /** 92 * Assignment operator for SBasePlugin. 93 * 94 * @param orig the object whose values are used as the basis of the 95 * assignment. 96 */ 97 SBasePlugin& operator=(const SBasePlugin& orig); 98 99 100 /** 101 * Returns the namespace URI of the package to which this plugin object 102 * belongs. 103 * 104 * @return the XML namespace URI of the SBML Level 3 package 105 * implemented by this libSBML package extension. 106 */ 107 const std::string& getElementNamespace() const; 108 109 110 /** 111 * Returns the XML namespace prefix of the package to which this plugin 112 * object belongs. 113 * 114 * @return the XML namespace prefix of the SBML Level 3 package 115 * implemented by this libSBML package extension. 116 */ 117 const std::string& getPrefix() const; 118 119 120 /** 121 * Returns the short-form name of the package to which this plugin 122 * object belongs. 123 * 124 * @return the short-form package name (or nickname) of the SBML package 125 * implemented by this package extension. 126 */ 127 const std::string& getPackageName() const; 128 129 130 /** 131 * Creates and returns a deep copy of this SBasePlugin object. 132 * 133 * @return the (deep) copy of this SBasePlugin object. 134 */ 135 virtual SBasePlugin* clone () const; 136 137 138 /** 139 * Return the first child object found with a given identifier. 140 * 141 * This method searches all the subobjects under this one, compares their 142 * identifiers to @p id, and returns the first one that machines. 143 * @if clike It uses SBasePlugin::getAllElements(ElementFilter* filter) to 144 * get the list of identifiers, so the order in which identifiers are 145 * searched is the order in which they appear in the results returned by 146 * that method.@endif@~ 147 * 148 * Normally, <code>SId</code> type identifier values are unique across 149 * a model in SBML. However, in some circumstances they may not be, such 150 * as if a model is invalid because of multiple objects having the same 151 * identifier. 152 * 153 * @param id string representing the identifier of the object to find. 154 * 155 * @return pointer to the first object with the given @p id. 156 */ 157 virtual SBase* getElementBySId(const std::string& id); 158 159 160 /** 161 * Return the first child object found with a given meta identifier. 162 * 163 * This method searches all the subobjects under this one, compares their 164 * meta identifiers to @p metaid, and returns the first one that machines. 165 * 166 * @param metaid string, the metaid of the object to find. 167 * 168 * @return pointer to the first object found with the given @p metaid. 169 */ 170 virtual SBase* getElementByMetaId(const std::string& metaid); 171 172 173 /** 174 * Returns all child objects of this object. 175 * 176 * This returns a List object containing all child SBase objects of this 177 * one, at any nesting depth. Optionally, callers can supply a filter 178 * that will establish the search criteria for matching objects. 179 * 180 * @param filter a pointer to an ElementFilter, which causes the function 181 * to return only elements that match a particular set of constraints. 182 * If NULL (the default), the function will return all child objects. 183 * 184 * @return a List of pointers to all children objects. 185 */ 186 virtual List* getAllElements(ElementFilter* filter=NULL); 187 188 189 // -------------------------------------------------------- 190 // 191 // virtual functions for reading/writing/checking elements 192 // 193 // -------------------------------------------------------- 194 195 #ifndef SWIG 196 197 /** @cond doxygenLibsbmlInternal */ 198 /** 199 * Takes the contents of the passed-in Model, makes copies of everything, 200 * and appends those copies to the appropriate places in this Model. Only 201 * called from Model::appendFrom, and is intended to be extended for 202 * packages that add new things to the Model object. 203 * 204 * @param model the Model to merge with this one. 205 * 206 */ 207 virtual int appendFrom(const Model* model); 208 /** @endcond */ 209 210 211 /** @cond doxygenLibsbmlInternal */ 212 /** 213 * Subclasses must override this method to create, store, and then 214 * return an SBML object corresponding to the next XMLToken in the 215 * XMLInputStream if they have their specific elements. 216 * 217 * @return the SBML object corresponding to next XMLToken in the 218 * XMLInputStream or @c NULL if the token was not recognized. 219 */ 220 virtual SBase* createObject (XMLInputStream& stream); 221 /** @endcond */ 222 223 224 /** @cond doxygenLibsbmlInternal */ 225 /** 226 * Subclasses should override this method to read (and store) XHTML, 227 * MathML, etc. directly from the XMLInputStream if the target elements 228 * can't be parsed by SBase::readAnnotation(XMLInputStream& stream) 229 * and/or SBase::readNotes(XMLInputStream& stream) functions. 230 * 231 * @return @c true if the subclass read from the stream, @c false otherwise. 232 */ 233 virtual bool readOtherXML (SBase* parentObject, XMLInputStream& stream); 234 /** @endcond */ 235 236 237 /** @cond doxygenLibsbmlInternal */ 238 /** 239 * Synchronizes the annotation of this SBML object. 240 * 241 * Annotation element (XMLNode* mAnnotation) is synchronized with the 242 * current CVTerm objects (List* mCVTerm). 243 * Currently, this method is called in getAnnotation, isSetAnnotation, 244 * and writeElements methods. 245 */ 246 virtual void syncAnnotation(SBase* parentObject, XMLNode *annotation); 247 /** @endcond */ 248 249 250 /** @cond doxygenLibsbmlInternal */ 251 /** 252 * Parse L2 annotation if supported 253 * 254 */ 255 virtual void parseAnnotation(SBase *parentObject, XMLNode *annotation); 256 /** @endcond */ 257 258 259 /** @cond doxygenLibsbmlInternal */ 260 /** 261 * Subclasses must override this method to write out their contained 262 * SBML objects as XML elements if they have their specific elements. 263 */ 264 virtual void writeElements (XMLOutputStream& stream) const; 265 /** @endcond */ 266 267 268 /** @cond doxygenLibsbmlInternal */ 269 /** 270 * Checks if this plugin object has all the required elements. 271 * 272 * Subclasses should override this function if they have their specific 273 * elements. 274 * 275 * @return @c true if this plugin object has all the required elements, 276 * otherwise @c false will be returned. 277 */ 278 virtual bool hasRequiredElements() const ; 279 280 /** @endcond */ 281 282 283 // ---------------------------------------------------------- 284 // 285 // virtual functions for reading/writing/checking attributes 286 // 287 // ---------------------------------------------------------- 288 289 290 /** @cond doxygenLibsbmlInternal */ 291 /** 292 * Subclasses should override this method to get the list of 293 * expected attributes if they have their specific attributes. 294 * This function is invoked from corresponding readAttributes() 295 * function. 296 */ 297 virtual void addExpectedAttributes(ExpectedAttributes& attributes); 298 /** @endcond */ 299 300 301 /** @cond doxygenLibsbmlInternal */ 302 /** 303 * Subclasses must override this method to read values from the given 304 * XMLAttributes if they have their specific attributes. 305 */ 306 virtual void readAttributes (const XMLAttributes& attributes, 307 const ExpectedAttributes& expectedAttributes); 308 /** @endcond */ 309 310 311 /** @cond doxygenLibsbmlInternal */ 312 /** 313 * Subclasses must override this method to write their XML attributes 314 * to the XMLOutputStream if they have their specific attributes. 315 */ 316 virtual void writeAttributes (XMLOutputStream& stream) const; 317 /** @endcond */ 318 319 320 /** @cond doxygenLibsbmlInternal */ 321 /* 322 * Checks if this plugin object has all the required attributes . 323 * 324 * Subclasses should override this function if if they have their specific 325 * attributes. 326 * 327 * @return @c true if this plugin object has all the required attributes, 328 * otherwise @c false will be returned. 329 */ 330 virtual bool hasRequiredAttributes() const ; 331 /** @endcond */ 332 333 334 /** @cond doxygenLibsbmlInternal */ 335 /** 336 * Subclasses should override this method to write required xmlns attributes 337 * to the XMLOutputStream (if any). 338 * The xmlns attribute will be written in the element to which the object 339 * is connected. For example, xmlns attributes written by this function will 340 * be added to Model element if this plugin object connected to the Model 341 * element. 342 */ 343 virtual void writeXMLNS (XMLOutputStream& stream) const; 344 /** @endcond */ 345 346 #endif // SWIG 347 348 349 // --------------------------------------------------------- 350 // 351 // virtual functions (internal implementation) which should 352 // be overridden by subclasses. 353 // 354 // --------------------------------------------------------- 355 356 /** @cond doxygenLibsbmlInternal */ 357 /** 358 * Sets the parent SBMLDocument of this plugin object. 359 * 360 * Subclasses which contain one or more SBase derived elements must 361 * override this function. 362 * 363 * @param d the SBMLDocument object to use. 364 * 365 * @see connectToParent() 366 * @see enablePackageInternal() 367 */ 368 virtual void setSBMLDocument (SBMLDocument* d); 369 /** @endcond */ 370 371 372 /** @cond doxygenLibsbmlInternal */ 373 /** 374 * Sets the parent SBML object of this plugin object to 375 * this object and child elements (if any). 376 * (Creates a child-parent relationship by this plugin object) 377 * 378 * This function is called when this object is created by 379 * the parent element. 380 * Subclasses must override this this function if they have one 381 * or more child elements. Also, SBasePlugin::connectToParent(@if java SBase@endif) 382 * must be called in the overridden function. 383 * 384 * @param sbase the SBase object to use. 385 * 386 * @if cpp 387 * @see setSBMLDocument() 388 * @see enablePackageInternal() 389 * @endif 390 */ 391 virtual void connectToParent (SBase *sbase); 392 /** @endcond */ 393 394 395 /** @cond doxygenLibsbmlInternal */ 396 /** 397 * Enables/Disables the given package with child elements in this plugin 398 * object (if any). 399 * (This is an internal implementation invoked from 400 * SBase::enablePackageInternal() function) 401 * 402 * Subclasses which contain one or more SBase derived elements should 403 * override this function if elements defined in them can be extended by 404 * some other package extension. 405 * 406 * @if cpp 407 * @see setSBMLDocument() 408 * @see connectToParent() 409 * @endif 410 */ 411 virtual void enablePackageInternal(const std::string& pkgURI, 412 const std::string& pkgPrefix, bool flag); 413 /** @endcond */ 414 415 416 /** @cond doxygenLibsbmlInternal */ 417 virtual bool stripPackage(const std::string& pkgPrefix, bool flag); 418 /** @endcond */ 419 420 421 // ---------------------------------------------------------- 422 423 424 /** 425 * Returns the SBMLDocument object containing this object instance. 426 * 427 * @copydetails doc_what_is_SBMLDocument 428 * 429 * This method allows the caller to obtain the SBMLDocument for the 430 * current object. 431 * 432 * @return the parent SBMLDocument object of this plugin object. 433 * 434 * @see getParentSBMLObject() 435 */ 436 SBMLDocument* getSBMLDocument (); 437 438 439 /** 440 * Returns the SBMLDocument object containing this object instance. 441 * 442 * @copydetails doc_what_is_SBMLDocument 443 * 444 * This method allows the caller to obtain the SBMLDocument for the 445 * current object. 446 * 447 * @return the parent SBMLDocument object of this plugin object. 448 * 449 * @see getParentSBMLObject() 450 */ 451 const SBMLDocument* getSBMLDocument () const; 452 453 454 /** 455 * Returns the XML namespace URI for the package to which this object belongs. 456 * 457 * @copydetails doc_what_are_xmlnamespaces 458 * 459 * This method first looks into the SBMLNamespaces object possessed by the 460 * parent SBMLDocument object of the current object. If this cannot be 461 * found, this method returns the result of getElementNamespace(). 462 * 463 * @return a string, the URI of the XML namespace to which this object belongs. 464 * 465 * @see getPackageName() 466 * @see getElementNamespace() 467 * @see getSBMLDocument() 468 */ 469 std::string getURI() const; 470 471 472 /** 473 * Returns the parent object to which this plugin object is connected. 474 * 475 * @return the parent object of this object. 476 */ 477 SBase* getParentSBMLObject (); 478 479 480 /** 481 * Returns the parent object to which this plugin object is connected. 482 * 483 * @return the parent object of this object. 484 */ 485 const SBase* getParentSBMLObject () const; 486 487 488 /** 489 * Sets the XML namespace to which this object belongs. 490 * 491 * @copydetails doc_what_are_xmlnamespaces 492 * 493 * @param uri the URI to assign to this object. 494 * 495 * @copydetails doc_returns_one_success_code 496 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 497 * 498 * @see getElementNamespace() 499 */ 500 int setElementNamespace(const std::string &uri); 501 502 503 /** 504 * Returns the SBML Level of the package extension of this plugin object. 505 * 506 * @return the SBML Level. 507 * 508 * @see getVersion() 509 */ 510 unsigned int getLevel() const; 511 512 513 /** 514 * Returns the Version within the SBML Level of the package extension of 515 * this plugin object. 516 * 517 * @return the SBML Version. 518 * 519 * @see getLevel() 520 */ 521 unsigned int getVersion() const; 522 523 524 /** 525 * Returns the package version of the package extension of this plugin 526 * object. 527 * 528 * @return the package version of the package extension of this plugin 529 * object. 530 * 531 * @see getLevel() 532 * @see getVersion() 533 */ 534 unsigned int getPackageVersion() const; 535 536 537 /** @cond doxygenLibsbmlInternal */ 538 /** 539 * If this object has a child 'math' object (or anything with ASTNodes in 540 * general), replace all nodes with the name 'id' with the provided 541 * function. 542 * 543 * @note This function does nothing itself--subclasses with ASTNode subelements must override this function. 544 */ 545 virtual void replaceSIDWithFunction(const std::string& id, const ASTNode* function); 546 /** @endcond */ 547 548 549 /** @cond doxygenLibsbmlInternal */ 550 /** 551 * If the function of this object is to assign a value has a child 'math' 552 * object (or anything with ASTNodes in general), replace the 'math' object 553 * with the function (existing/function). 554 * 555 * @note This function does nothing itself--subclasses with ASTNode subelements must override this function. 556 */ 557 virtual void divideAssignmentsToSIdByFunction(const std::string& id, const ASTNode* function); 558 /** @endcond */ 559 560 561 /** @cond doxygenLibsbmlInternal */ 562 /** 563 * If this assignment assigns a value to the 'id' element, replace the 564 * 'math' object with the function (existing*function). 565 */ 566 virtual void multiplyAssignmentsToSIdByFunction(const std::string& id, const ASTNode* function); 567 /** @endcond */ 568 569 570 /** @cond doxygenLibsbmlInternal */ 571 /** 572 * Check to see if the given prefix is used by any of the IDs defined by 573 * extension elements. A package that defines its own 'id' attribute for a 574 * core element would check that attribute here. 575 */ 576 virtual bool hasIdentifierBeginningWith(const std::string& prefix); 577 /** @endcond */ 578 579 580 /** @cond doxygenLibsbmlInternal */ 581 /** 582 * Add the given string to all identifiers in the object. If the string is 583 * added to anything other than an id or a metaid, this code is responsible 584 * for tracking down and renaming all *idRefs in the package extension that 585 * identifier comes from. 586 */ 587 virtual int prependStringToAllIdentifiers(const std::string& prefix); 588 /** @endcond */ 589 590 591 /** 592 * @copydoc doc_renamesidref_common 593 */ 594 virtual void renameSIdRefs(const std::string& oldid, const std::string& newid); 595 596 597 /** 598 * @copydoc doc_renamemetasidref_common 599 */ 600 virtual void renameMetaIdRefs(const std::string& oldid, const std::string& newid); 601 602 603 /** 604 * @copydoc doc_renameunitsidref_common 605 */ 606 virtual void renameUnitSIdRefs(const std::string& oldid, const std::string& newid); 607 608 609 /** @cond doxygenLibsbmlInternal */ 610 virtual int transformIdentifiers(IdentifierTransformer* sidTransformer); 611 /** @endcond */ 612 613 614 /** @cond doxygenLibsbmlInternal */ 615 /** 616 * Returns the line number on which this object first appears in the XML 617 * representation of the SBML document. 618 * 619 * @return the line number of the underlying SBML object. 620 * 621 * @note The line number for each construct in an SBML model is set upon 622 * reading the model. The accuracy of the line number depends on the 623 * correctness of the XML representation of the model, and on the 624 * particular XML parser library being used. The former limitation 625 * relates to the following problem: if the model is actually invalid 626 * XML, then the parser may not be able to interpret the data correctly 627 * and consequently may not be able to establish the real line number. 628 * The latter limitation is simply that different parsers seem to have 629 * their own accuracy limitations, and out of all the parsers supported 630 * by libSBML, none have been 100% accurate in all situations. (At this 631 * time, libSBML supports the use of <a target="_blank" 632 * href="http://xmlsoft.org">libxml2</a>, <a target="_blank" 633 * href="http://expat.sourceforge.net/">Expat</a> and <a target="_blank" 634 * href="http://xerces.apache.org/xerces-c/">Xerces</a>.) 635 * 636 * @see getColumn() 637 */ 638 unsigned int getLine() const; 639 /** @endcond */ 640 641 642 /** @cond doxygenLibsbmlInternal */ 643 /** 644 * Returns the column number on which this object first appears in the XML 645 * representation of the SBML document. 646 * 647 * @return the column number of the underlying SBML object. 648 * 649 * @note The column number for each construct in an SBML model is set 650 * upon reading the model. The accuracy of the column number depends on 651 * the correctness of the XML representation of the model, and on the 652 * particular XML parser library being used. The former limitation 653 * relates to the following problem: if the model is actually invalid 654 * XML, then the parser may not be able to interpret the data correctly 655 * and consequently may not be able to establish the real column number. 656 * The latter limitation is simply that different parsers seem to have 657 * their own accuracy limitations, and out of all the parsers supported 658 * by libSBML, none have been 100% accurate in all situations. (At this 659 * time, libSBML supports the use of <a target="_blank" 660 * href="http://xmlsoft.org">libxml2</a>, <a target="_blank" 661 * href="http://expat.sourceforge.net/">Expat</a> and <a target="_blank" 662 * href="http://xerces.apache.org/xerces-c/">Xerces</a>.) 663 * 664 * @see getLine() 665 */ 666 unsigned int getColumn() const; 667 /** @endcond */ 668 669 670 /** @cond doxygenLibsbmlInternal */ 671 /* gets the SBMLnamespaces - internal use only*/ 672 virtual SBMLNamespaces * getSBMLNamespaces() const; 673 /** @endcond */ 674 675 676 // ----------------------------------------------- 677 // 678 // virtual functions for elements 679 // 680 // ------------------------------------------------ 681 682 /** @cond doxygenLibsbmlInternal */ 683 /** 684 * Helper to log a common type of error for elements. 685 */ 686 virtual void logUnknownElement(const std::string &element, 687 const unsigned int sbmlLevel, 688 const unsigned int sbmlVersion, 689 const unsigned int pkgVersion ); 690 /** @endcond */ 691 692 693 virtual bool isValidTypeForList(SBase* item) const; 694 695 /** @cond doxygenLibsbmlInternal */ 696 /** 697 * Accepts the given SBMLVisitor. 698 * 699 * @return the result of calling <code>v.visit()</code>, which indicates 700 * whether or not the Visitor would like to visit the SBML object's next 701 * sibling object (if available). 702 */ 703 virtual bool accept (SBMLVisitor& v) const; 704 /** @endcond */ 705 706 /** @cond doxygenLibsbmlInternal */ 707 708 const SBMLExtension* getSBMLExtension() const; 709 710 /** @endcond */ 711 712 #ifndef SWIG 713 /** @cond doxygenLibsbmlInternal */ 714 715 // ------------------------------------------------------------------ 716 // 717 // functions to faciliate matlab binding 718 719 virtual int getAttribute(const std::string& attributeName, double& value) const; 720 721 /** @endcond */ 722 723 /** @cond doxygenLibsbmlInternal */ 724 725 virtual int getAttribute(const std::string& attributeName, bool& value) const; 726 727 /** @endcond */ 728 729 /** @cond doxygenLibsbmlInternal */ 730 731 virtual int getAttribute(const std::string& attributeName, int& value) const; 732 733 /** @endcond */ 734 735 /** @cond doxygenLibsbmlInternal */ 736 737 virtual int getAttribute(const std::string& attributeName, unsigned int& value) const; 738 739 /** @endcond */ 740 741 /** @cond doxygenLibsbmlInternal */ 742 743 virtual int getAttribute(const std::string& attributeName, std::string& value) const; 744 745 /** @endcond */ 746 747 //virtual int getAttribute(const std::string& attributeName, const char * value) const; 748 749 750 virtual bool isSetAttribute(const std::string& attributeName) const; 751 752 /** @endcond */ 753 754 /** @cond doxygenLibsbmlInternal */ 755 756 virtual int setAttribute(const std::string& attributeName, double value); 757 758 /** @endcond */ 759 760 /** @cond doxygenLibsbmlInternal */ 761 762 virtual int setAttribute(const std::string& attributeName, bool value); 763 764 /** @endcond */ 765 766 /** @cond doxygenLibsbmlInternal */ 767 768 virtual int setAttribute(const std::string& attributeName, int value); 769 770 /** @endcond */ 771 772 /** @cond doxygenLibsbmlInternal */ 773 774 virtual int setAttribute(const std::string& attributeName, unsigned int value); 775 776 /** @endcond */ 777 778 /** @cond doxygenLibsbmlInternal */ 779 780 virtual int setAttribute(const std::string& attributeName, const std::string& value); 781 782 /** @endcond */ 783 784 /** @cond doxygenLibsbmlInternal */ 785 786 //virtual int setAttribute(const std::string& attributeName, const char* value); 787 788 /** @endcond */ 789 790 /** @cond doxygenLibsbmlInternal */ 791 792 virtual int unsetAttribute(const std::string& attributeName); 793 794 /** @endcond */ 795 796 /** @cond doxygenLibsbmlInternal */ 797 798 virtual SBase* createChildObject(const std::string& elementName); 799 800 /** @endcond */ 801 802 /** @cond doxygenLibsbmlInternal */ 803 804 //virtual int setMath(const ASTNode* math); 805 806 /** @endcond */ 807 808 /** @cond doxygenLibsbmlInternal */ 809 810 /** 811 * Returns the number of "elementName" in this FbcModelPlugin. 812 * 813 * @param elementName, the name of the element to get number of. 814 * 815 * @return unsigned int number of elements. 816 */ 817 virtual unsigned int getNumObjects(const std::string& elementName); 818 819 /** @endcond */ 820 821 822 823 /** @cond doxygenLibsbmlInternal */ 824 825 /** 826 * Returns the nth object of "objectName" in this FbcModelPlugin. 827 * 828 * @param elementName, the name of the element to get number of. 829 * 830 * @param index, unsigned int the index of the object to retrieve. 831 * 832 * @return pointer to the object. 833 */ 834 virtual SBase* getObject(const std::string& elementName, unsigned int index); 835 836 /** @endcond */ 837 838 839 #endif 840 841 /** @cond doxygenLibsbmlInternal */ 842 843 virtual void updateSBMLNamespace(const std::string& package, unsigned int level, 844 unsigned int version); 845 /** @endcond */ 846 847 848 protected: 849 /** @cond doxygenLibsbmlInternal */ 850 /** 851 * Creates a new SBasePlugin object using the given parameters. 852 * 853 * @copydetails doc_what_are_xmlnamespaces 854 * 855 * @copydetails doc_what_are_sbmlnamespaces 856 * 857 * @param uri the URI of the SBML Level 3 package implemented by 858 * this libSBML package extension. 859 * 860 * @param prefix the XML namespace prefix being used for the package. 861 * 862 * @param sbmlns the namespaces object for the package. 863 */ 864 SBasePlugin (const std::string &uri, const std::string &prefix, 865 SBMLNamespaces *sbmlns); 866 867 868 /** 869 * Copy constructor. Creates a copy of this SBase object. 870 * 871 * @param orig the instance to copy. 872 */ 873 SBasePlugin(const SBasePlugin& orig); 874 875 876 /** 877 * Returns the SBMLErrorLog used to log errors while reading and 878 * validating SBML. 879 * 880 * @return the SBMLErrorLog used to log errors while reading and 881 * validating SBML. 882 */ 883 SBMLErrorLog* getErrorLog (); 884 885 886 //// ----------------------------------------------- 887 //// 888 //// virtual functions for elements 889 //// 890 //// ------------------------------------------------ 891 892 ///** 893 // * Helper to log a common type of error for elements. 894 // */ 895 //virtual void logUnknownElement(const std::string &element, 896 // const unsigned int sbmlLevel, 897 // const unsigned int sbmlVersion, 898 // const unsigned int pkgVersion ); 899 900 // ----------------------------------------------- 901 // 902 // virtual functions for attributes 903 // 904 // ------------------------------------------------ 905 906 /** 907 * Helper to log a common type of error. 908 */ 909 virtual void logUnknownAttribute(const std::string &attribute, 910 const unsigned int sbmlLevel, 911 const unsigned int sbmlVersion, 912 const unsigned int pkgVersion, 913 const std::string& element); 914 915 916 /** 917 * Helper to log a common type of error. 918 */ 919 virtual void logEmptyString(const std::string &attribute, 920 const unsigned int sbmlLevel, 921 const unsigned int sbmlVersion, 922 const unsigned int pkgVersion, 923 const std::string& element); 924 925 926 /*-- data members --*/ 927 928 // 929 // An SBMLExtension derived object of corresponding package extension 930 // The owner of this object is SBMLExtensionRegistry class. 931 // 932 const SBMLExtension *mSBMLExt; 933 934 // 935 // Parent SBMLDocument object of this plugin object. 936 // 937 SBMLDocument *mSBML; 938 939 // 940 // Parent SBase derived object to which this plugin object 941 // connected. 942 // 943 SBase *mParent; 944 945 // 946 // XML namespace of corresponding package extension 947 // 948 std::string mURI; 949 950 // 951 // SBMLNamespaces derived object of this plugin object. 952 // 953 SBMLNamespaces *mSBMLNS; 954 955 // 956 // Prefix of corresponding package extension 957 // 958 std::string mPrefix; 959 960 /** @endcond */ 961 }; 962 963 LIBSBML_CPP_NAMESPACE_END 964 965 #endif /* __cplusplus */ 966 967 #ifndef SWIG 968 969 LIBSBML_CPP_NAMESPACE_BEGIN 970 BEGIN_C_DECLS 971 972 /** 973 * Returns the XML namespace (URI) of the package extension 974 * of the given plugin structure. 975 * 976 * @param plugin the plugin structure. 977 * 978 * @return the URI of the package extension of this plugin structure, or @c NULL 979 * in case an invalid plugin structure is provided. 980 * 981 * @memberof SBasePlugin_t 982 */ 983 LIBSBML_EXTERN 984 const char* 985 SBasePlugin_getURI(SBasePlugin_t* plugin); 986 987 /** 988 * Returns the prefix of the given plugin structure. 989 * 990 * @param plugin the plugin structure. 991 * 992 * @return the prefix of the given plugin structure, or @c NULL 993 * in case an invalid plugin structure is provided. 994 * 995 * @memberof SBasePlugin_t 996 */ 997 LIBSBML_EXTERN 998 const char* 999 SBasePlugin_getPrefix(SBasePlugin_t* plugin); 1000 1001 /** 1002 * Returns the package name of the given plugin structure. 1003 * 1004 * @param plugin the plugin structure. 1005 * 1006 * @return the package name of the given plugin structure, or @c NULL 1007 * in case an invalid plugin structure is provided. 1008 * 1009 * @memberof SBasePlugin_t 1010 */ 1011 LIBSBML_EXTERN 1012 const char* 1013 SBasePlugin_getPackageName(SBasePlugin_t* plugin); 1014 1015 /** 1016 * Creates a deep copy of the given SBasePlugin_t structure 1017 * 1018 * @param plugin the SBasePlugin_t structure to be copied. 1019 * 1020 * @return a (deep) copy of the given SBasePlugin_t structure. 1021 * 1022 * @memberof SBasePlugin_t 1023 */ 1024 LIBSBML_EXTERN 1025 SBasePlugin_t* 1026 SBasePlugin_clone(SBasePlugin_t* plugin); 1027 1028 /** 1029 * Frees the given SBasePlugin_t structure 1030 * 1031 * @param plugin the SBasePlugin_t structure to be freed. 1032 * 1033 * @copydetails doc_returns_success_code 1034 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1035 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1036 * 1037 * @memberof SBasePlugin_t 1038 */ 1039 LIBSBML_EXTERN 1040 int 1041 SBasePlugin_free(SBasePlugin_t* plugin); 1042 1043 /** 1044 * Subclasses must override this method to create, store, and then 1045 * return an SBML structure corresponding to the next XMLToken in the 1046 * XMLInputStream_t if they have their specific elements. 1047 * 1048 * @param plugin the SBasePlugin_t structure. 1049 * @param stream the XMLInputStream_t structure to read from. 1050 * 1051 * @return the SBML structure corresponding to next XMLToken in the 1052 * XMLInputStream_t or @c NULL if the token was not recognized or plugin or stream 1053 * were NULL. 1054 * 1055 * @memberof SBasePlugin_t 1056 */ 1057 LIBSBML_EXTERN 1058 SBase_t* 1059 SBasePlugin_createObject(SBasePlugin_t* plugin, XMLInputStream_t* stream); 1060 1061 /** 1062 * Subclasses should override this method to read (and store) XHTML, 1063 * MathML, etc. directly from the XMLInputStream_t if the target elements 1064 * can't be parsed by SBase::readAnnotation() and/or SBase_readNotes() 1065 * functions 1066 * 1067 * @param plugin the SBasePlugin_t structure. 1068 * @param parentObject the SBase_t structure that will store the annotation. 1069 * @param stream the XMLInputStream_t structure to read from. 1070 * 1071 * @return @c 1 (true) if the subclass read from the stream, @c 0 (false) otherwise. 1072 * If an invalid plugin or stream was provided 1073 * @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} is returned. 1074 * 1075 * @memberof SBasePlugin_t 1076 */ 1077 LIBSBML_EXTERN 1078 int 1079 SBasePlugin_readOtherXML(SBasePlugin_t* plugin, SBase_t* parentObject, XMLInputStream_t* stream); 1080 1081 /** 1082 * Subclasses must override this method to write out their contained 1083 * SBML structures as XML elements if they have their specific elements. 1084 * 1085 * @param plugin the SBasePlugin_t structure. 1086 * @param stream the XMLOutputStream_t structure to write to. 1087 * 1088 * @copydetails doc_returns_success_code 1089 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1090 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1091 * 1092 * @memberof SBasePlugin_t 1093 */ 1094 LIBSBML_EXTERN 1095 int 1096 SBasePlugin_writeElements(SBasePlugin_t* plugin, XMLInputStream_t* stream); 1097 1098 /** 1099 * Checks if the plugin structure has all the required elements. 1100 * 1101 * Subclasses should override this function if they have their specific 1102 * elements. 1103 * 1104 * @param plugin the SBasePlugin_t structure. 1105 * 1106 * @return @c 1 (true) if this plugin structure has all the required elements, 1107 * otherwise @c 0 (false) will be returned. If an invalid plugin 1108 * was provided @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} is returned. 1109 * 1110 * @memberof SBasePlugin_t 1111 */ 1112 LIBSBML_EXTERN 1113 int 1114 SBasePlugin_hasRequiredElements(SBasePlugin_t* plugin); 1115 1116 /** @cond doxygenLibsbmlInternal */ 1117 /** 1118 * Subclasses should override this method to get the list of 1119 * expected attributes if they have their specific attributes. 1120 * This function is invoked from corresponding readAttributes() 1121 * function. 1122 * 1123 * @param plugin the SBasePlugin_t structure. 1124 * @param attributes the ExpectedAttributes_t structure. 1125 * 1126 * @copydetails doc_returns_success_code 1127 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1128 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1129 * 1130 * @memberof SBasePlugin_t 1131 */ 1132 LIBSBML_EXTERN 1133 int 1134 SBasePlugin_addExpectedAttributes(SBasePlugin_t* plugin, 1135 ExpectedAttributes_t* attributes); 1136 1137 /** 1138 * Subclasses must override this method to read values from the given 1139 * XMLAttributes_t if they have their specific attributes. 1140 * 1141 * @param plugin the SBasePlugin_t structure. 1142 * @param attributes the XMLAttributes_t structure. 1143 * @param expectedAttributes the ExpectedAttributes_t structure. 1144 * 1145 * @copydetails doc_returns_success_code 1146 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1147 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1148 * 1149 * @memberof SBasePlugin_t 1150 */ 1151 LIBSBML_EXTERN 1152 int 1153 SBasePlugin_readAttributes(SBasePlugin_t* plugin, 1154 XMLAttributes_t* attributes, 1155 ExpectedAttributes_t* expectedAttributes); 1156 /** @endcond*/ 1157 1158 /** 1159 * Subclasses must override this method to write their XML attributes 1160 * to the XMLOutputStream_t if they have their specific attributes. 1161 * 1162 * @param plugin the SBasePlugin_t structure. 1163 * @param stream the XMLOutputStream_t structure. 1164 * 1165 * @copydetails doc_returns_success_code 1166 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1167 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1168 * 1169 * @memberof SBasePlugin_t 1170 */ 1171 LIBSBML_EXTERN 1172 int 1173 SBasePlugin_writeAttributes(SBasePlugin_t* plugin, 1174 XMLOutputStream_t* stream); 1175 1176 /** 1177 * Checks if the plugin structure has all the required attributes. 1178 * 1179 * Subclasses should override this function if they have their specific 1180 * attributes. 1181 * 1182 * @param plugin the SBasePlugin_t structure. 1183 * 1184 * @return @c 1 (true) if this plugin structure has all the required attributes, 1185 * otherwise @c 0 (false) will be returned. If an invalid plugin 1186 * was provided @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} is returned. 1187 * 1188 * @memberof SBasePlugin_t 1189 */ 1190 LIBSBML_EXTERN 1191 int 1192 SBasePlugin_hasRequiredAttributes(SBasePlugin_t* plugin); 1193 1194 /** 1195 * Subclasses should override this method to write required xmlns attributes 1196 * to the XMLOutputStream_t (if any). 1197 * The xmlns attribute will be written in the element to which the structure 1198 * is connected. For example, xmlns attributes written by this function will 1199 * be added to Model_t element if this plugin structure connected to the Model_t 1200 * element. 1201 * 1202 * @param plugin the SBasePlugin_t structure. 1203 * @param stream the XMLOutputStream_t structure. 1204 * 1205 * @copydetails doc_returns_success_code 1206 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1207 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1208 * 1209 * @memberof SBasePlugin_t 1210 */ 1211 LIBSBML_EXTERN 1212 int 1213 SBasePlugin_writeXMLNS(SBasePlugin_t* plugin, XMLOutputStream_t* stream); 1214 1215 /** 1216 * Sets the parent SBMLDocument of th plugin structure. 1217 * 1218 * Subclasses which contain one or more SBase derived elements must 1219 * override this function. 1220 * 1221 * @param plugin the SBasePlugin_t structure. 1222 * @param d the SBMLDocument_t structure to use. 1223 * 1224 * @see SBasePlugin_connectToParent 1225 * 1226 * @copydetails doc_returns_success_code 1227 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1228 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1229 * 1230 * @memberof SBasePlugin_t 1231 */ 1232 LIBSBML_EXTERN 1233 int 1234 SBasePlugin_setSBMLDocument(SBasePlugin_t* plugin, SBMLDocument_t* d); 1235 1236 /** 1237 * Sets the parent SBML structure of this plugin structure to 1238 * this structure and child elements (if any). 1239 * (Creates a child-parent relationship by this plugin structure) 1240 * 1241 * This function is called when this structure is created by 1242 * the parent element. 1243 * Subclasses must override this this function if they have one 1244 * or more child elements. Also, SBasePlugin_connectToParent() 1245 * must be called in the overridden function. 1246 * 1247 * @param plugin the SBasePlugin_t structure. 1248 * @param sbase the SBase_t structure to use. 1249 * 1250 * @see SBasePlugin_setSBMLDocument 1251 * 1252 * @copydetails doc_returns_success_code 1253 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1254 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1255 * 1256 * @memberof SBasePlugin_t 1257 */ 1258 LIBSBML_EXTERN 1259 int 1260 SBasePlugin_connectToParent(SBasePlugin_t* plugin, SBase_t* sbase); 1261 1262 /** @cond doxygenLibsbmlInternal */ 1263 /** 1264 * Enables/Disables the given package with child elements in this plugin 1265 * structure (if any). 1266 * 1267 * Subclasses which contain one or more SBase derived elements should 1268 * override this function if elements defined in them can be extended by 1269 * some other package extension. 1270 * 1271 * @param plugin the SBasePlugin_t structure. 1272 * @param pkgURI the package uri. 1273 * @param pkgPrefix the package prefix. 1274 * @param flag indicating whether the package should be enabled (1) or disabled(0). 1275 * 1276 * @see SBasePlugin_setSBMLDocument 1277 * @see SBasePlugin_connectToParent 1278 * 1279 * @copydetails doc_returns_success_code 1280 * @li @sbmlconstant{LIBSBML_OPERATION_SUCCESS, OperationReturnValues_t} 1281 * @li @sbmlconstant{LIBSBML_INVALID_OBJECT, OperationReturnValues_t} 1282 * 1283 * @memberof SBasePlugin_t 1284 */ 1285 LIBSBML_EXTERN 1286 int 1287 SBasePlugin_enablePackageInternal(SBasePlugin_t* plugin, 1288 const char* pkgURI, const char* pkgPrefix, int flag); 1289 /** @endcond */ 1290 1291 /** 1292 * Returns the parent SBMLDocument of this plugin structure. 1293 * 1294 * @param plugin the SBasePlugin_t structure. 1295 * 1296 * @return the parent SBMLDocument_t structure of this plugin structure or @c NULL if 1297 * no document is set, or the plugin structure is invalid. 1298 * 1299 * @memberof SBasePlugin_t 1300 */ 1301 LIBSBML_EXTERN 1302 SBMLDocument_t* 1303 SBasePlugin_getSBMLDocument(SBasePlugin_t* plugin); 1304 1305 /** 1306 * Returns the parent SBase_t structure to which this plugin structure is connected. 1307 * 1308 * @param plugin the SBasePlugin_t structure. 1309 * 1310 * @return the parent SBase_t structure to which this plugin structure is connected 1311 * or @c NULL if sbase structure is set, or the plugin structure is invalid. 1312 * 1313 * @memberof SBasePlugin_t 1314 */ 1315 LIBSBML_EXTERN 1316 SBase_t* 1317 SBasePlugin_getParentSBMLObject(SBasePlugin_t* plugin); 1318 1319 /** 1320 * Returns the SBML level of the package extension of 1321 * this plugin structure. 1322 * 1323 * @param plugin the SBasePlugin_t structure. 1324 * 1325 * @return the SBML level of the package extension of 1326 * this plugin structure or SBML_INT_MAX if the structure is invalid. 1327 * 1328 * @memberof SBasePlugin_t 1329 */ 1330 LIBSBML_EXTERN 1331 unsigned int 1332 SBasePlugin_getLevel(SBasePlugin_t* plugin); 1333 1334 /** 1335 * Returns the SBML version of the package extension of 1336 * this plugin structure. 1337 * 1338 * @param plugin the SBasePlugin_t structure. 1339 * 1340 * @return the SBML version of the package extension of 1341 * this plugin structure or SBML_INT_MAX if the structure is invalid. 1342 * 1343 * @memberof SBasePlugin_t 1344 */ 1345 LIBSBML_EXTERN 1346 unsigned int 1347 SBasePlugin_getVersion(SBasePlugin_t* plugin); 1348 1349 /** 1350 * Returns the package version of the package extension of 1351 * this plugin structure. 1352 * 1353 * @param plugin the SBasePlugin_t structure. 1354 * 1355 * @return the package version of the package extension of 1356 * this plugin structure or SBML_INT_MAX if the structure is invalid. 1357 * 1358 * @memberof SBasePlugin_t 1359 */ 1360 LIBSBML_EXTERN 1361 unsigned int 1362 SBasePlugin_getPackageVersion(SBasePlugin_t* plugin); 1363 1364 1365 1366 END_C_DECLS 1367 LIBSBML_CPP_NAMESPACE_END 1368 1369 #endif /* !SWIG */ 1370 1371 #endif /* SBasePlugin_h */ 1372