001/* ---------------------------------------------------------------------------- 002 * This file was automatically generated by SWIG (http://www.swig.org). 003 * Version 2.0.12 004 * 005 * Do not make changes to this file unless you know what you are doing--modify 006 * the SWIG interface file instead. 007 * ----------------------------------------------------------------------------- */ 008 009package org.sbml.libsbml; 010 011 012/** 013 * Wrapper class for global methods and constants defined by libSBML. 014 * <p> 015 * <em style='color: #555'> 016 * This class of objects is defined by libSBML only and has no direct 017 * equivalent in terms of SBML components. This class is not prescribed by 018 * the SBML specifications, although it is used to implement features 019 * defined in SBML. 020 * </em> 021 * <p> 022 * In the C++ and C versions of libSBML, there exists a small number of 023 * methods that are global in scope; in addition, libSBML uses a number 024 * of enum's to define such things as error codes in a way that can be 025 * used by both C++ and C. This poses a problem in languages such as 026 * Java, where there is no concept of global method or global constant. 027 * SWIG wraps these global identifiers in the class whose documentation 028 * you see before you. 029 */ 030public class libsbml implements libsbmlConstants { 031 032 033 /** 034 * Downcast a package extension object to its specific package class. 035 * 036 * This method is used in the implementation of libSBML extensions to 037 * support SBML Level 3 packages. It allows an object to be 038 * downcast to the actual {@link SBMLExtension} object it is. 039 * 040 * @param cPtr the the pointer to the object 041 * @param owner if <code>true</code>, it indicates the caller will "own" 042 * the memory associated with the object and will be responsible for 043 * freeing it. 044 * 045 * @return the {@link SBMLExtension} for the package 046 * 047 * @internal 048 */ 049 public static SBMLExtension DowncastExtension(long cPtr, boolean owner) 050 { 051 if (cPtr == 0) return null; 052 053 SBMLExtension ext = new SBMLExtension(cPtr, false); 054 String pkgName = ext.getName(); 055 056 057 if (pkgName.equals("fbc")) 058 return new FbcExtension(cPtr, owner); 059 060 061 if (pkgName.equals("layout")) 062 return new LayoutExtension(cPtr, owner); 063 064 065 if (pkgName.equals("render")) 066 return new RenderExtension(cPtr, owner); 067 068 069 if (pkgName.equals("groups")) 070 return new GroupsExtension(cPtr, owner); 071 072 073 if (pkgName.equals("comp")) 074 return new CompExtension(cPtr, owner); 075 076 077 if (pkgName.equals("qual")) 078 return new QualExtension(cPtr, owner); 079 080 081 return new SBMLExtension(cPtr,owner); 082 } 083 084 /** 085 * SBMLExtension derived classes must override this method 086 * @internal 087 */ 088 public static SBasePlugin DowncastSBasePlugin(long cPtr, boolean owner) 089 { 090 if (cPtr == 0) return null; 091 092 SBasePlugin sbp = new SBasePlugin(cPtr,false); 093 String pkgName = sbp.getPackageName(); 094 095 SBMLExtension sbmlext = SBMLExtensionRegistry.getInstance().getExtension(pkgName); 096 if (sbmlext != null) 097 { 098 return sbmlext.DowncastSBasePlugin(cPtr,owner); 099 } 100 return new SBasePlugin(cPtr,owner); 101 } 102 103 /** 104 * @internal 105 */ 106 public static SBMLNamespaces DowncastSBMLNamespaces(long cPtr, boolean owner) 107 { 108 if (cPtr == 0) return null; 109 110 SBMLNamespaces sbn = new SBMLNamespaces(cPtr, false); 111 if (sbn != null) 112 { 113 XMLNamespaces ns = sbn.getNamespaces(); 114 115 116 117 if (ns.hasURI(FbcExtension.getXmlnsL3V1V1())) 118 { 119 return new FbcPkgNamespaces(cPtr, owner); 120 } 121 122 123 124 if (ns.hasURI(QualExtension.getXmlnsL3V1V1())) 125 { 126 return new QualPkgNamespaces(cPtr, owner); 127 } 128 129 130 131 if (ns.hasURI(GroupsExtension.getXmlnsL3V1V1())) 132 { 133 return new GroupsPkgNamespaces(cPtr, owner); 134 } 135 136 137 138 if (ns.hasURI(CompExtension.getXmlnsL3V1V1())) 139 { 140 return new CompPkgNamespaces(cPtr, owner); 141 } 142 143 144 145 if (ns.hasURI(RenderExtension.getXmlnsL3V1V1()) || ns.hasURI(RenderExtension.getXmlnsL2())) 146 { 147 return new RenderPkgNamespaces(cPtr, owner); 148 } 149 150 151 152 if (ns.hasURI(LayoutExtension.getXmlnsL3V1V1()) || ns.hasURI(LayoutExtension.getXmlnsL2())) 153 { 154 return new LayoutPkgNamespaces(cPtr, owner); 155 } 156 157 158 } 159 return new SBMLNamespaces(cPtr, owner); 160 } 161 162 /** 163 * Internal method. 164 * 165 * @internal 166 */ 167 public static SBase DowncastSBase(long cPtr, boolean owner) 168 { 169 if (cPtr == 0) return null; 170 171 SBase sb = new SBase(cPtr,false); 172 String pkgName = sb.getPackageName(); 173 if (pkgName.equals("core")) 174 { 175 switch( sb.getTypeCode() ) 176 { 177 case libsbmlConstants.SBML_COMPARTMENT: 178 return new Compartment(cPtr, owner); 179 180 case libsbmlConstants.SBML_COMPARTMENT_TYPE: 181 return new CompartmentType(cPtr, owner); 182 183 case libsbmlConstants.SBML_CONSTRAINT: 184 return new Constraint(cPtr, owner); 185 186 case libsbmlConstants.SBML_DOCUMENT: 187 return new SBMLDocument(cPtr, owner); 188 189 case libsbmlConstants.SBML_DELAY: 190 return new Delay(cPtr, owner); 191 192 case libsbmlConstants.SBML_EVENT: 193 return new Event(cPtr, owner); 194 195 case libsbmlConstants.SBML_EVENT_ASSIGNMENT: 196 return new EventAssignment(cPtr, owner); 197 198 case libsbmlConstants.SBML_FUNCTION_DEFINITION: 199 return new FunctionDefinition(cPtr, owner); 200 201 case libsbmlConstants.SBML_INITIAL_ASSIGNMENT: 202 return new InitialAssignment(cPtr, owner); 203 204 case libsbmlConstants.SBML_KINETIC_LAW: 205 return new KineticLaw(cPtr, owner); 206 207 case libsbmlConstants.SBML_LIST_OF: 208 String name = sb.getElementName(); 209 if(name.equals("listOf")){ 210 return new ListOf(cPtr, owner); 211 } 212 else if(name.equals("listOfCompartments")){ 213 return new ListOfCompartments(cPtr, owner); 214 } 215 else if(name.equals("listOfCompartmentTypes")){ 216 return new ListOfCompartmentTypes(cPtr, owner); 217 } 218 else if(name.equals("listOfConstraints")){ 219 return new ListOfConstraints(cPtr, owner); 220 } 221 else if(name.equals("listOfEvents")){ 222 return new ListOfEvents(cPtr, owner); 223 } 224 else if(name.equals("listOfEventAssignments")){ 225 return new ListOfEventAssignments(cPtr, owner); 226 } 227 else if(name.equals("listOfFunctionDefinitions")){ 228 return new ListOfFunctionDefinitions(cPtr, owner); 229 } 230 else if(name.equals("listOfInitialAssignments")){ 231 return new ListOfInitialAssignments(cPtr, owner); 232 } 233 else if(name.equals("listOfParameters")){ 234 return new ListOfParameters(cPtr, owner); 235 } 236 else if(name.equals("listOfLocalParameters")){ 237 return new ListOfLocalParameters(cPtr, owner); 238 } 239 else if(name.equals("listOfReactions")){ 240 return new ListOfReactions(cPtr, owner); 241 } 242 else if(name.equals("listOfRules")){ 243 return new ListOfRules(cPtr, owner); 244 } 245 else if(name.equals("listOfSpecies")){ 246 return new ListOfSpecies(cPtr, owner); 247 } 248 else if(name.equals("listOfUnknowns")){ 249 return new ListOfSpeciesReferences(cPtr, owner); 250 } 251 else if(name.equals("listOfReactants")){ 252 return new ListOfSpeciesReferences(cPtr, owner); 253 } 254 else if(name.equals("listOfProducts")){ 255 return new ListOfSpeciesReferences(cPtr, owner); 256 } 257 else if(name.equals("listOfModifiers")){ 258 return new ListOfSpeciesReferences(cPtr, owner); 259 } 260 else if(name.equals("listOfSpeciesTypes")){ 261 return new ListOfSpeciesTypes(cPtr, owner); 262 } 263 else if(name.equals("listOfUnits")){ 264 return new ListOfUnits(cPtr, owner); 265 } 266 else if(name.equals("listOfUnitDefinitions")){ 267 return new ListOfUnitDefinitions(cPtr, owner); 268 } 269 return new ListOf(cPtr, owner); 270 271 case libsbmlConstants.SBML_MODEL: 272 return new Model(cPtr, owner); 273 274 case libsbmlConstants.SBML_PARAMETER: 275 return new Parameter(cPtr, owner); 276 277 case libsbmlConstants.SBML_PRIORITY: 278 return new Priority(cPtr, owner); 279 280 case libsbmlConstants.SBML_LOCAL_PARAMETER: 281 return new LocalParameter(cPtr, owner); 282 283 case libsbmlConstants.SBML_REACTION: 284 return new Reaction(cPtr, owner); 285 286 case libsbmlConstants.SBML_SPECIES: 287 return new Species(cPtr, owner); 288 289 case libsbmlConstants.SBML_SPECIES_REFERENCE: 290 return new SpeciesReference(cPtr, owner); 291 292 case libsbmlConstants.SBML_MODIFIER_SPECIES_REFERENCE: 293 return new ModifierSpeciesReference(cPtr, owner); 294 295 case libsbmlConstants.SBML_SPECIES_TYPE: 296 return new SpeciesType(cPtr, owner); 297 298 case libsbmlConstants.SBML_TRIGGER: 299 return new Trigger(cPtr, owner); 300 301 case libsbmlConstants.SBML_UNIT_DEFINITION: 302 return new UnitDefinition(cPtr, owner); 303 304 case libsbmlConstants.SBML_UNIT: 305 return new Unit(cPtr, owner); 306 307 case libsbmlConstants.SBML_ALGEBRAIC_RULE: 308 return new AlgebraicRule(cPtr, owner); 309 310 case libsbmlConstants.SBML_ASSIGNMENT_RULE: 311 return new AssignmentRule(cPtr, owner); 312 313 case libsbmlConstants.SBML_RATE_RULE: 314 return new RateRule(cPtr, owner); 315 316 case libsbmlConstants.SBML_STOICHIOMETRY_MATH: 317 return new StoichiometryMath(cPtr, owner); 318 319 default: 320 return new SBase(cPtr, owner); 321 } 322 } 323 else 324 { 325 SBMLExtension sbmlext = SBMLExtensionRegistry.getInstance().getExtension(pkgName); 326 if (sbmlext != null) 327 { 328 return sbmlext.DowncastSBase(cPtr,owner); 329 } 330 } 331 return new SBase(cPtr, owner); 332 } 333 334 335 336 public static ASTBase DowncastASTBase(long cPtr, boolean owner) 337 { 338 if (cPtr == 0) return null; 339 340 ASTBase ab = new ASTBase(cPtr,false); 341 switch( ab.getTypeCode() ) 342 { 343 default: 344 case libsbmlConstants.AST_TYPECODE_BASE: 345 return new ASTBase(cPtr, owner); 346 /* 347 case libsbmlConstants.AST_TYPECODE_CN_BASE: 348 return new ASTCnBase(cPtr, owner); 349 case libsbmlConstants.AST_TYPECODE_FUNCTION_BASE: 350 return new ASTFunctionBase(cPtr, owner); 351 case libsbmlConstants.AST_TYPECODE_NUMBER: 352 return new ASTNumber(cPtr, owner); 353 case libsbmlConstants.AST_TYPECODE_CN_INTEGER: 354 return new ASTCnIntegerNode(cPtr, owner); 355 case libsbmlConstants.AST_TYPECODE_CN_EXPONENTIAL: 356 return new ASTCnExponentialNode(cPtr, owner); 357 case libsbmlConstants.AST_TYPECODE_CN_RATIONAL: 358 return new ASTCnRationalNode(cPtr, owner); 359 case libsbmlConstants.AST_TYPECODE_CN_REAL: 360 return new ASTCnRealNode(cPtr, owner); 361 case libsbmlConstants.AST_TYPECODE_CSYMBOL: 362 return new ASTCSymbol(cPtr, owner); 363 case libsbmlConstants.AST_TYPECODE_CSYMBOL_AVOGADRO: 364 return new ASTCSymbolAvogadroNode(cPtr, owner); 365 case libsbmlConstants.AST_TYPECODE_CSYMBOL_DELAY: 366 return new ASTCSymbolDelayNode(cPtr, owner); 367 case libsbmlConstants.AST_TYPECODE_CSYMBOL_TIME: 368 return new ASTCSymbolTimeNode(cPtr, owner); 369 case libsbmlConstants.AST_TYPECODE_FUNCTION: 370 return new ASTFunction(cPtr, owner); 371 case libsbmlConstants.AST_TYPECODE_FUNCTION_UNARY: 372 return new ASTUnaryFunctionNode(cPtr, owner); 373 case libsbmlConstants.AST_TYPECODE_FUNCTION_BINARY: 374 return new ASTBinaryFunctionNode(cPtr, owner); 375 case libsbmlConstants.AST_TYPECODE_FUNCTION_NARY: 376 return new ASTNaryFunctionNode(cPtr, owner); 377 case libsbmlConstants.AST_TYPECODE_FUNCTION_PIECEWISE: 378 return new ASTPiecewiseFunctionNode(cPtr, owner); 379 case libsbmlConstants.AST_TYPECODE_FUNCTION_LAMBDA: 380 return new ASTLambdaFunctionNode(cPtr, owner); 381 case libsbmlConstants.AST_TYPECODE_FUNCTION_CI: 382 return new ASTCiFunctionNode(cPtr, owner); 383 case libsbmlConstants.AST_TYPECODE_FUNCTION_SEMANTIC: 384 return new ASTSemanticsNode(cPtr, owner); 385 case libsbmlConstants.AST_TYPECODE_FUNCTION_QUALIFIER: 386 return new ASTQualifierNode(cPtr, owner);*/ 387 case libsbmlConstants.AST_TYPECODE_ASTNODE: 388 return new ASTNode(cPtr, owner); 389 390 } 391 //return new ASTBase(cPtr, owner); 392 } 393 394 395 396 static String getAbsolutePath(String filename) 397 { 398 java.io.File file = new java.io.File(filename); 399 return file.getAbsolutePath(); 400 } 401 402 403 /** 404 * Stream handle for low-level C++ standard output stream. 405 * <p> 406 * A few libSBML methods accept an argument for indicating where to send 407 * text string output. An example is the {@link 408 * SBMLDocument#printErrors} method. However, the methods use C++ style 409 * streams and not Java stream objects. The OStream object class in the 410 * libSBML Java interface provides a wrapper for the underlying C++ 411 * streams. The present object (cout) is a static final variable that 412 * can be used directly from your code. An example use might be 413 * something like this: 414 * <p> 415 * <div class="fragment"><pre class="fragment"> 416 * SBMLDocument document = libsbml.readSBML("somefile.xml"); 417 * if (document.getNumErrors() > 0) 418 * { 419 * document.printErrors(libsbml.cout); 420 * println("Please correct the above problems first."); 421 * System.exit(1); 422 * }</div> 423 * 424 * @see #cerr 425 * @see #clog 426 */ 427 public final static OStream cout; 428 429 430 /** 431 * Stream handle for low-level C++ standard error stream. 432 * <p> 433 * A few libSBML methods accept an argument for indicating where to send 434 * text string output. An example is the {@link 435 * SBMLDocument#printErrors} method. However, the methods use C++ style 436 * streams and not Java stream objects. The OStream object class in the 437 * libSBML Java interface provides a wrapper for the underlying C++ 438 * streams. The present object (cerr) is a static final variable that 439 * can be used directly from your code. An example use might be 440 * something like this: 441 * <p> 442 * <div class="fragment"><pre class="fragment"> 443 * SBMLDocument document = libsbml.readSBML("somefile.xml"); 444 * if (document.getNumErrors() > 0) 445 * { 446 * document.printErrors(libsbml.cerr); 447 * println("Please correct the above problems first."); 448 * System.exit(1); 449 * }</div> 450 * <p> 451 * By default, most operating systems have have their standard error and 452 * logging output streams directed to the console/terminal, and this is 453 * where text messages will be shown. This can usually be redirected 454 * elsewhere, although how to do this depends on the specific environment 455 * where the program is running. 456 * 457 * @see #cout 458 * @see #clog 459 */ 460 public final static OStream cerr; 461 462 463 /** 464 * Stream handle for low-level C++ standard logging stream. 465 * <p> 466 * A few libSBML methods accept an argument for indicating where to send 467 * text string output. An example is the {@link 468 * SBMLDocument#printErrors} method. However, the methods use C++ style 469 * streams and not Java stream objects. The OStream object class in the 470 * libSBML Java interface provides a wrapper for the underlying C++ 471 * streams. The present object (clog) is a static final variable that 472 * can be used directly from your code. An example use might be 473 * something like this: 474 * <p> 475 * <div class="fragment"><pre class="fragment"> 476 * SBMLDocument document = libsbml.readSBML("somefile.xml"); 477 * if (document.getNumErrors() > 0) 478 * { 479 * document.printErrors(libsbml.clog); 480 * println("Please correct the above problems first."); 481 * System.exit(1); 482 * }</div> 483 * <p> 484 * By default, most operating systems have have their standard error and 485 * logging output streams directed to the console/terminal, and this is 486 * where text messages will be shown. This can usually be redirected 487 * elsewhere, although how to do this depends on the specific environment 488 * where the program is running. 489 * 490 * @see #cout 491 * @see #cerr 492 */ 493 public final static OStream clog; 494 495 static { 496 cout = new OStream(OStream.COUT); 497 cerr = new OStream(OStream.CERR); 498 clog = new OStream(OStream.CLOG); 499 } 500 501 /** 502 * This private constructor does nothing and never invoked. 503 * The purpose of this constuctor is to hide a default constructor of this 504 * class in javadoc documentation. 505 */ 506 private libsbml() {} 507 508 509 510/** 511 * Returns the version number of this copy of libSBML as an integer. 512 <p> 513 * @return the libSBML version as an integer; version 1.2.3 becomes 10203. 514 */ public 515 static int getLibSBMLVersion() { 516 return libsbmlJNI.getLibSBMLVersion(); 517 } 518 519 520/** 521 * Returns the version number of this copy of libSBML as a string. 522 <p> 523 * @return the libSBML version as a string; version 1.2.3 becomes 524 * '1.2.3'. 525 <p> 526 * @see #getLibSBMLVersionString() 527 */ public 528 static String getLibSBMLDottedVersion() { 529 return libsbmlJNI.getLibSBMLDottedVersion(); 530 } 531 532 533/** 534 * Returns the version number of this copy of libSBML as a string without 535 * periods. 536 <p> 537 * @return the libSBML version as a string: version 1.2.3 becomes '10203'. 538 <p> 539 * @see #getLibSBMLDottedVersion() 540 */ public 541 static String getLibSBMLVersionString() { 542 return libsbmlJNI.getLibSBMLVersionString(); 543 } 544 545 546/** 547 * Returns an indication whether libSBML has been compiled with 548 * against a specific library. 549 <p> 550 * @param option the library to test against, this can be one of 551 * 'expat', 'libxml', 'xerces-c', 'bzip2', 'zip' 552 <p> 553 * @return 0 in case the libSBML has not been compiled against 554 * that library and non-zero otherwise (for libraries 555 * that define an integer version number that number will 556 * be returned). 557 <p> 558 * @see #getLibSBMLDependencyVersionOf(String option) 559 */ public 560 static int isLibSBMLCompiledWith(String option) { 561 return libsbmlJNI.isLibSBMLCompiledWith(option); 562 } 563 564 565/** 566 * Returns the version string for the dependency library used. 567 <p> 568 * @param option the library for which the version 569 * should be retrieved, this can be one of 570 * 'expat', 'libxml', 'xerces-c', 'bzip2', 'zip' 571 <p> 572 * @return null in case libSBML has not been compiled against 573 * that library and a version string otherwise. 574 <p> 575 * @see #isLibSBMLCompiledWith(String option) 576 */ public 577 static String getLibSBMLDependencyVersionOf(String option) { 578 return libsbmlJNI.getLibSBMLDependencyVersionOf(option); 579 } 580 581 582/** 583 * This method takes an SBML operation return value and returns a string representing 584 * the code. 585 <p> 586 * @param returnValue the operation return value to convert to a string 587 <p> 588 * @return a human readable name for the given 589 * operation return value . 590 <p> 591 * @note The caller does not own the returned string and is therefore not 592 * allowed to modify it. 593 */ public 594 static String OperationReturnValue_toString(int returnValue) { 595 return libsbmlJNI.OperationReturnValue_toString(returnValue); 596 } 597 598 599/** 600 * Reads an SBML document from the given file <code>filename</code>. 601 <p> 602 * If <code>filename</code> does not exist, or it is not an SBML file, an error will 603 * be logged in the error log of the {@link SBMLDocument} object returned by this 604 * method. Calling programs can inspect this error log to determine 605 * the nature of the problem. Please refer to the definition of 606 * SBMLDocument_t for more information about the error reporting mechanism. 607 <p> 608 * <code> 609 * SBMLReader_t *sr; 610 611 * SBMLDocument_t *d; 612 <p> 613 * sr = SBMLReader_create(); 614 <p> 615 * d = SBMLReader_readSBML(reader, filename); 616 <p> 617 * if (SBMLDocument_getNumErrors(d) > 0) 618 619 * { 620 621 * if (XMLError_getId(SBMLDocument_getError(d, 0)) 622 * == SBML_READ_ERROR_FILE_NOT_FOUND) 623 624 * if (XMLError_getId(SBMLDocument_getError(d, 0)) 625 * == SBML_READ_ERROR_NOT_SBML) 626 627 * } 628 629 * </code> 630 <p> 631 * If the filename ends with @em .gz, the file will be read as a <em>gzip</em> file. 632 * Similary, if the filename ends with @em .zip or @em .bz2, the file will be 633 * read as a <em>zip</em> or <em>bzip2</em> file, respectively. Otherwise, the fill will be 634 * read as an uncompressed file. 635 * If the filename ends with @em .zip, only the first file in the archive will 636 * be read if the zip archive contains two or more files. 637 <p> 638 * To read a gzip/zip file, underlying libSBML needs to be linked with zlib 639 * at compile time. Also, underlying libSBML needs to be linked with bzip2 640 * to read a bzip2 file. File unreadable error will be logged if a compressed 641 * file name is given and underlying libSBML is not linked with the corresponding 642 * required library. 643 * SBMLReader_hasZlib() and SBMLReader_hasBzip2() can be used to check 644 * whether libSBML is linked with each library. 645 <p> 646 * @return a pointer to the {@link SBMLDocument} read. 647 */ public 648 static SBMLDocument readSBML(String filename) { 649 long cPtr = libsbmlJNI.readSBML(libsbml.getAbsolutePath(filename)); 650 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 651 } 652 653 654/** 655 * Reads an SBML document from the given file <code>filename</code>. 656 <p> 657 * If <code>filename</code> does not exist, or it is not an SBML file, an error will 658 * be logged in the error log of the {@link SBMLDocument} object returned by this 659 * method. Calling programs can inspect this error log to determine 660 * the nature of the problem. Please refer to the definition of 661 * SBMLDocument_t for more information about the error reporting mechanism. 662 <p> 663 <p> 664 * <code> 665 * SBMLReader_t *sr; 666 667 * SBMLDocument_t *d; 668 <p> 669 * sr = SBMLReader_create(); 670 <p> 671 * d = SBMLReader_readSBML(reader, filename); 672 <p> 673 * if (SBMLDocument_getNumErrors(d) > 0) 674 675 * { 676 677 * if (XMLError_getId(SBMLDocument_getError(d, 0)) 678 * == SBML_READ_ERROR_FILE_NOT_FOUND) 679 680 * if (XMLError_getId(SBMLDocument_getError(d, 0)) 681 * == SBML_READ_ERROR_NOT_SBML) 682 683 * } 684 685 * </code> 686 <p> 687 * If the filename ends with @em .gz, the file will be read as a <em>gzip</em> file. 688 * Similary, if the filename ends with @em .zip or @em .bz2, the file will be 689 * read as a <em>zip</em> or <em>bzip2</em> file, respectively. Otherwise, the fill will be 690 * read as an uncompressed file. 691 * If the filename ends with @em .zip, only the first file in the archive will 692 * be read if the zip archive contains two or more files. 693 <p> 694 * To read a gzip/zip file, underlying libSBML needs to be linked with zlib 695 * at compile time. Also, underlying libSBML needs to be linked with bzip2 696 * to read a bzip2 file. File unreadable error will be logged if a compressed 697 * file name is given and underlying libSBML is not linked with the corresponding 698 * required library. 699 * SBMLReader_hasZlib() and SBMLReader_hasBzip2() can be used to check 700 * whether libSBML is linked with each library. 701 <p> 702 * @return a pointer to the {@link SBMLDocument} read. 703 */ public 704 static SBMLDocument readSBMLFromFile(String filename) { 705 long cPtr = libsbmlJNI.readSBMLFromFile(libsbml.getAbsolutePath(filename)); 706 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 707 } 708 709 710/** 711 * Reads an SBML document from the given XML string <code>xml</code>. 712 <p> 713 * If the string does not begin with XML declaration, 714 *<div class='fragment'><pre class='fragment'> 715<?xml version='1.0' encoding='UTF-8'?> 716</pre></div> 717 <p> 718 * an XML declaration string will be prepended. 719 <p> 720 * This method will report an error if the given string <code>xml</code> is not SBML. 721 * The error will be logged in the error log of the SBMLDocument_t structure 722 * returned by this method. Calling programs can inspect this error log to 723 * determine the nature of the problem. Please refer to the definition of 724 * {@link SBMLDocument} for more information about the error reporting mechanism. 725 <p> 726 * @return a pointer to the SBMLDocument_t read. 727 <p> 728 * @note When using this method to read an {@link SBMLDocument} that uses 729 * the SBML L3 Hierarchical {@link Model} Composition package (comp) the 730 * document location cannot be set automatically. Thus, if the model 731 * contains references to ExternalModelDefinitions, it will be necessary 732 * to manually set the document URI location (setLocationURI) in order 733 * to facilitate resolving these models. 734 */ public 735 static SBMLDocument readSBMLFromString(String xml) { 736 long cPtr = libsbmlJNI.readSBMLFromString(xml); 737 return (cPtr == 0) ? null : new SBMLDocument(cPtr, true); 738 } 739 740 741/** 742 * Writes the given SBML document <code>d</code> to the file named by <code>filename</code>. 743 * This convenience function is functionally equivalent to: 744 <p> 745 * SBMLWriter_writeSBML(SBMLWriter_create(), d, filename); 746 <p> 747 * If the given filename ends with the suffix <code>".gz"</code> 748(for example, <code>"myfile.xml.gz"</code>), libSBML assumes the 749caller wants the file to be written compressed in <em>gzip</em> format. 750Similarly, if the given filename ends with <code>".zip"</code> or 751<code>".bz2"</code>, libSBML assumes the caller wants the file to 752be compressed in <em>zip</em> or <em>bzip2</em> format (respectively). 753Files whose names lack these suffixes will be written uncompressed. 754<em>Special considerations for the zip format</em>: If the given filename 755ends with <code>".zip"</code>, the file placed in the zip archive 756will have the suffix <code>".xml"</code> or 757<code>".sbml"</code>. For example, the file in the zip archive 758will be named <code>"test.xml"</code> if the given filename is 759<code>"test.xml.zip"</code> or <code>"test.zip"</code>. 760Similarly, the filename in the archive will be 761<code>"test.sbml"</code> if the given filename is 762<code>"test.sbml.zip"</code>. 763 764 <p> 765 * @param d the {@link SBMLDocument} object to be written out in XML format 766 <p> 767 * @param filename a string giving the path to a file where the XML 768 * content is to be written. 769 <p> 770 * @return <code>1</code> on success and <code>0</code> (zero) if <code>filename</code> could not be 771 * written. Some possible reasons for failure include (a) being unable to 772 * open the file, and (b) using a filename that indicates a compressed SBML 773 * file (i.e., a filename ending in <code>".zip"</code> or 774 * similar) when the compression functionality has not been enabled in 775 * the underlying copy of libSBML. 776 <p> 777 * @see SBMLWriter#hasZlib() 778 * @see SBMLWriter#hasBzip2() 779 */ public 780 static int writeSBML(SBMLDocument d, String filename) { 781 return libsbmlJNI.writeSBML(SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename)); 782 } 783 784 785/** 786 * Writes the given SBML document <code>d</code> to an in-memory string and returns a 787 * pointer to it. The string is owned by the caller and should be freed 788 * (with free()) when no longer needed. This convenience function is 789 * functionally equivalent to: 790 <p> 791 * SBMLWriter_writeSBMLToString(SBMLWriter_create(), d); 792 <p> 793 * but does not require the caller to create an {@link SBMLWriter} object first. 794 <p> 795 * @param d an {@link SBMLDocument} object to be written out in XML format 796 <p> 797 * @return the string on success and <code>null</code> if one of the underlying parser 798 * components fail. 799 */ public 800 static String writeSBMLToString(SBMLDocument d) { 801 return libsbmlJNI.writeSBMLToString(SBMLDocument.getCPtr(d), d); 802 } 803 804 805/** 806 * Writes the given SBML document <code>d</code> to the file <code>filename</code>. 807 * This convenience function is functionally equivalent to: 808 <p> 809 * SBMLWriter_writeSBMLToFile(SBMLWriter_create(), d, filename); 810 <p> 811 * but that does not require the caller to create an {@link SBMLWriter} object first. 812 <p> 813 * If the given filename ends with the suffix <code>".gz"</code> 814(for example, <code>"myfile.xml.gz"</code>), libSBML assumes the 815caller wants the file to be written compressed in <em>gzip</em> format. 816Similarly, if the given filename ends with <code>".zip"</code> or 817<code>".bz2"</code>, libSBML assumes the caller wants the file to 818be compressed in <em>zip</em> or <em>bzip2</em> format (respectively). 819Files whose names lack these suffixes will be written uncompressed. 820<em>Special considerations for the zip format</em>: If the given filename 821ends with <code>".zip"</code>, the file placed in the zip archive 822will have the suffix <code>".xml"</code> or 823<code>".sbml"</code>. For example, the file in the zip archive 824will be named <code>"test.xml"</code> if the given filename is 825<code>"test.xml.zip"</code> or <code>"test.zip"</code>. 826Similarly, the filename in the archive will be 827<code>"test.sbml"</code> if the given filename is 828<code>"test.sbml.zip"</code>. 829 830 <p> 831 * @param d an {@link SBMLDocument} object to be written out in XML format 832 <p> 833 * @param filename a string giving the path to a file where the XML 834 * content is to be written. 835 <p> 836 * @return <code>1</code> on success and <code>0</code> (zero) if <code>filename</code> could not be 837 * written. Some possible reasons for failure include (a) being unable to 838 * open the file, and (b) using a filename that indicates a compressed SBML 839 * file (i.e., a filename ending in <code>".zip"</code> or 840 * similar) when the compression functionality has not been enabled in 841 * the underlying copy of libSBML. 842 <p> 843 <p> 844 <p> 845 * @see SBMLWriter#hasZlib() 846 * @see SBMLWriter#hasBzip2() 847 */ public 848 static int writeSBMLToFile(SBMLDocument d, String filename) { 849 return libsbmlJNI.writeSBMLToFile(SBMLDocument.getCPtr(d), d, libsbml.getAbsolutePath(filename)); 850 } 851 852 853/** 854 * This method takes an SBML type code and returns a string representing 855 * the code. 856 <p> 857 * LibSBML attaches an identifying code to every 858 * kind of SBML object. These are known as <em>SBML type codes</em>. In 859 * other languages, the set of type codes is stored in an enumeration; in 860 * the Java language interface for libSBML, the type codes are defined as 861 * static integer constants in the interface class {@link 862 * libsbmlConstants}. The names of the type codes all begin with the 863 * characters <code>SBML_.</code> 864 <p> 865 * @return a human readable name for the given 866 * SBML type code. 867 <p> 868 * @note The caller does not own the returned string and is therefore not 869 * allowed to modify it. 870 */ public 871 static String SBMLTypeCode_toString(int tc, String pkgName) { 872 return libsbmlJNI.SBMLTypeCode_toString(tc, pkgName); 873 } 874 875 876/** 877 * Tests for logical equality between two given <code>UNIT_KIND_</code> 878 * code values. 879 <p> 880 * This function behaves exactly like C's <code>==</code> operator, except 881 * for the following two cases: 882 * <ul> 883 * <li>{@link libsbmlConstants#UNIT_KIND_LITER UNIT_KIND_LITER} <code>==</code> {@link libsbmlConstants#UNIT_KIND_LITRE UNIT_KIND_LITRE} 884 * <li>{@link libsbmlConstants#UNIT_KIND_METER UNIT_KIND_METER} <code>==</code> {@link libsbmlConstants#UNIT_KIND_METRE UNIT_KIND_METRE} 885 * </ul> 886 <p> 887 * In the two cases above, C equality comparison would yield <code>false</code> 888 * (because each of the above is a distinct enumeration value), but 889 * this function returns <code>true.</code> 890 <p> 891 * @param uk1 a <code>UNIT_KIND_</code> value 892 * @param uk2 a second <code>UNIT_KIND_</code> value to compare to <code>uk1</code> 893 <p> 894 * @return nonzero (for <code>true</code>) if <code>uk1</code> is logically equivalent to 895 * <code>uk2</code>, zero (for <code>false</code>) otherwise. 896 <p> 897 * @note For more information about the libSBML unit codes, please refer to 898 * the class documentation for {@link Unit}. 899 */ public 900 static int UnitKind_equals(int uk1, int uk2) { 901 return libsbmlJNI.UnitKind_equals(uk1, uk2); 902 } 903 904 905/** 906 * Converts a text string naming a kind of unit to its corresponding 907 * libSBML <code>UNIT_KIND_</code> constant/enumeration value. 908 <p> 909 * @param name a string, the name of a predefined base unit in SBML 910 <p> 911 * @return a value the set of <code>UNIT_KIND_</code> codes 912 * defined in class {@link libsbmlConstants}, corresponding to the string 913 * <code>name</code> (determined in a case-insensitive manner). 914 <p> 915 * @note For more information about the libSBML unit codes, please refer to 916 * the class documentation for {@link Unit}. 917 */ public 918 static int UnitKind_forName(String name) { 919 return libsbmlJNI.UnitKind_forName(name); 920 } 921 922 923/** 924 * Converts a unit code to a text string equivalent. 925 <p> 926 * @param uk a value from the set of <code>UNIT_KIND_</code> codes 927 * defined in the class {@link libsbmlConstants} 928 <p> 929 <p> 930 * @return the name corresponding to the given unit code. 931 <p> 932 * @note For more information about the libSBML unit codes, please refer to 933 * the class documentation for {@link Unit}. 934 <p> 935 * @warning The string returned is a static data value. The caller does not 936 * own the returned string and is therefore not allowed to modify it. 937 */ public 938 static String UnitKind_toString(int uk) { 939 return libsbmlJNI.UnitKind_toString(uk); 940 } 941 942 943/** 944 * Predicate for testing whether a given string corresponds to a 945 * predefined libSBML unit code. 946 <p> 947 * @param str a text string naming a base unit defined by SBML 948 * @param level the Level of SBML 949 * @param version the Version within the Level of SBML 950 <p> 951 * @return nonzero (for <code>true</code>) if string is the name of a valid 952 * <code>UNIT_KIND_</code> value, zero (for <code>false</code>) otherwise. 953 <p> 954 * @note For more information about the libSBML unit codes, please refer to 955 * the class documentation for {@link Unit}. 956 */ public 957 static int UnitKind_isValidUnitKindString(String str, long level, long version) { 958 return libsbmlJNI.UnitKind_isValidUnitKindString(str, level, version); 959 } 960 961 public static boolean representsNumber(int type) { 962 return libsbmlJNI.representsNumber(type); 963 } 964 965 public static boolean representsFunction(int type, ASTBasePlugin plugin) { 966 return libsbmlJNI.representsFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin); 967 } 968 969 public static boolean representsFunction(int type) { 970 return libsbmlJNI.representsFunction__SWIG_1(type); 971 } 972 973 public static boolean representsUnaryFunction(int type, ASTBasePlugin plugin) { 974 return libsbmlJNI.representsUnaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin); 975 } 976 977 public static boolean representsUnaryFunction(int type) { 978 return libsbmlJNI.representsUnaryFunction__SWIG_1(type); 979 } 980 981 public static boolean representsBinaryFunction(int type, ASTBasePlugin plugin) { 982 return libsbmlJNI.representsBinaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin); 983 } 984 985 public static boolean representsBinaryFunction(int type) { 986 return libsbmlJNI.representsBinaryFunction__SWIG_1(type); 987 } 988 989 public static boolean representsNaryFunction(int type, ASTBasePlugin plugin) { 990 return libsbmlJNI.representsNaryFunction__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin); 991 } 992 993 public static boolean representsNaryFunction(int type) { 994 return libsbmlJNI.representsNaryFunction__SWIG_1(type); 995 } 996 997 public static boolean representsQualifier(int type, ASTBasePlugin plugin) { 998 return libsbmlJNI.representsQualifier__SWIG_0(type, ASTBasePlugin.getCPtr(plugin), plugin); 999 } 1000 1001 public static boolean representsQualifier(int type) { 1002 return libsbmlJNI.representsQualifier__SWIG_1(type); 1003 } 1004 1005 public static boolean representsFunctionRequiringAtLeastTwoArguments(int type) { 1006 return libsbmlJNI.representsFunctionRequiringAtLeastTwoArguments(type); 1007 } 1008 1009 public static int getCoreTypeFromName(String name) { 1010 return libsbmlJNI.getCoreTypeFromName(name); 1011 } 1012 1013 public static String getNameFromCoreType(int type) { 1014 return libsbmlJNI.getNameFromCoreType(type); 1015 } 1016 1017 public static boolean isCoreTopLevelMathMLFunctionNodeTag(String name) { 1018 return libsbmlJNI.isCoreTopLevelMathMLFunctionNodeTag(name); 1019 } 1020 1021 public static boolean isCoreTopLevelMathMLNumberNodeTag(String name) { 1022 return libsbmlJNI.isCoreTopLevelMathMLNumberNodeTag(name); 1023 } 1024 1025 1026/** 1027 * Reads the MathML from the given XML string, constructs a corresponding 1028 * abstract syntax tree, and returns a pointer to the root of the tree. 1029 <p> 1030 * @param xml a string containing a full MathML expression 1031 <p> 1032 * @return the root of an AST corresponding to the given mathematical 1033 * expression, otherwise <code>null</code> is returned if the given string is <code>null</code> 1034 * or invalid. 1035 */ public 1036 static ASTNode readMathMLFromString(String xml) { 1037 long cPtr = libsbmlJNI.readMathMLFromString(xml); 1038 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 1039 } 1040 1041 1042/** 1043 * Reads the MathML from the given XML string, constructs a corresponding 1044 * abstract syntax tree, and returns a pointer to the root of the tree. 1045 <p> 1046 * @param xml a string containing a full MathML expression 1047 * @param xmlns a XMLNamespaces_t object containing namespaces that 1048 * are considered active during the read e.g. an L3 package namespace 1049 <p> 1050 * @return the root of an AST corresponding to the given mathematical 1051 * expression, otherwise <code>null</code> is returned if the given string is <code>null</code> 1052 * or invalid. 1053 */ public 1054 static ASTNode readMathMLFromStringWithNamespaces(String xml, XMLNamespaces xmlns) { 1055 long cPtr = libsbmlJNI.readMathMLFromStringWithNamespaces(xml, XMLNamespaces.getCPtr(xmlns), xmlns); 1056 return (cPtr == 0) ? null : new ASTNode(cPtr, false); 1057 } 1058 1059 1060/** 1061 * Writes the given ASTNode_t (and its children) to a string as MathML, and 1062 * returns the string. 1063 <p> 1064 * @param node the root of an AST to write out to the stream. 1065 <p> 1066 * @return a string containing the written-out MathML representation 1067 * of the given AST. 1068 <p> 1069 * @note The string is owned by the caller and should be freed (with 1070 * free()) when no longer needed. <code>null</code> is returned if the given 1071 * argument is <code>null.</code> 1072 */ public 1073 static String writeMathMLToString(ASTNode node) { 1074 return libsbmlJNI.writeMathMLToString(ASTNode.getCPtr(node), node); 1075 } 1076 1077 1078/** 1079 * Parses the given SBML formula and returns a representation of it as an 1080 * Abstract Syntax Tree (AST). 1081 <p> 1082 * <p> 1083 * The text-string form of mathematical formulas produced by 1084 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code> 1085 * and read by <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code> 1086 * use a simple C-inspired infix notation taken from SBML Level 1. A 1087 * formula in this text-string form therefore can be handed to a program 1088 * that understands SBML Level 1 mathematical expressions, or used as 1089 * part of a formula translation system. The syntax is described in detail 1090 * in the documentation for {@link ASTNode}. 1091 <p> 1092 * Note that this facility is provided as a convenience by libSBML—the 1093 * MathML standard does not actually define a 'string-form' equivalent to 1094 * MathML expression trees, so the choice of formula syntax is somewhat 1095 * arbitrary. The approach taken by libSBML is to use the syntax defined by 1096 * SBML Level 1 (which in fact used a text-string representation of 1097 * formulas and not MathML). This formula syntax is based mostly on C 1098 * programming syntax, and may contain operators, function calls, symbols, 1099 * and white space characters. The following table provides the precedence 1100 * rules for the different entities that may appear in formula strings. 1101 <p> 1102 * <table border="0" class="centered text-table width80 normal-font alt-row-colors" style="padding-bottom: 0.5em"> 1103 <tr style="background: lightgray; font-size: 14px;"> 1104 <th align="left">Token</th> 1105 <th align="left">Operation</th> 1106 <th align="left">Class</th> 1107 <th>Precedence</th> 1108 <th align="left">Associates</th> 1109 </tr> 1110<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">6</td><td>n/a</td></tr> 1111<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align="center">6</td><td>n/a</td></tr> 1112<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align="center">6</td><td>left</td></tr> 1113<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align="center">5</td><td>right</td></tr> 1114<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">4</td><td>left</td></tr> 1115<tr><td><code>*</code></td><td>multiplication</td><td>binary</td><td align="center">3</td><td>left</td></tr> 1116<tr><td><code>/</code></td><td>divison</td><td>binary</td><td align="center">3</td><td>left</td></tr> 1117<tr><td><code>+</code></td><td>addition</td><td>binary</td><td align="center">2</td><td>left</td></tr> 1118<tr><td><code>-</code></td><td>subtraction</td><td>binary</td><td align="center">2</td><td>left</td></tr> 1119<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr> 1120<caption class="top-caption">A table of the expression operators and their precedence in the 1121text-string format for mathematical expressions used by SBML_parseFormula(). 1122</caption> 1123</table> 1124 1125 1126 <p> 1127 * In the table above, <em>operand</em> implies the construct is an operand, 1128 * <em>prefix</em> implies the operation is applied to the following arguments, 1129 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are 1130 * two arguments. The values in the <b>Precedence</b> column show how the 1131 * order of different types of operation are determined. For example, the 1132 * expression <code>a * b + c</code> is evaluated as <code>(a * b) + 1133 * c</code> because the @c * operator has higher precedence. The 1134 * <b>Associates</b> column shows how the order of similar precedence 1135 * operations is determined; for example, <code>a - b + c</code> is 1136 * evaluated as <code>(a - b) + c</code> because the <code>+</code> and <code>-</code> 1137 * operators are left-associative. 1138 <p> 1139 * The function call syntax consists of a function name, followed by optional 1140 * white space, followed by an opening parenthesis token, followed by a 1141 * sequence of zero or more arguments separated by commas (with each comma 1142 * optionally preceded and/or followed by zero or more white space 1143 * characters, followed by a closing parenthesis token. The function name 1144 * must be chosen from one of the pre-defined functions in SBML or a 1145 * user-defined function in the model. The following table lists the names 1146 * of certain common mathematical functions; this table corresponds to 1147 * Table 6 in the <a target='_blank' href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML Level 1 Version 2 specification</a>: 1148 <p> 1149 * <table border="0" class="centered text-table width80 normal-font alt-row-colors"> 1150 <tr> 1151 <th align="left" width="60">Name</th> 1152 <th align="left" width="35">Args</th> 1153 <th align="left">Formula or meaning</th> 1154 <th align="left" width="110">Argument Constraints</th> 1155 <th align="left" width="100">Result constraints</th> 1156 </tr> 1157<tr><td><code>abs</code></td><td><em>x</em></td><td>absolute value of <em>x</em></td><td></td><td></td></tr> 1158<tr><td><code>acos</code></td><td><em>x</em></td><td>arc cosine of <em>x</em> in radians</td><td>-1.0 ≤ <em>x</em> ≤ 1.0</td><td>0 ≤ <em>acos(x)</em> ≤ π</td></tr> 1159<tr><td><code>asin</code></td><td><em>x</em></td><td>arc sine of <em>x</em> in radians</td><td>-1.0 ≤ <em>x</em> ≤ 1.0</td><td>0 ≤ <em>asin(x)</em> ≤ π</td></tr> 1160<tr><td><code>atan</code></td><td><em>x</em></td><td>arc tangent of <em>x</em> in radians</td><td></td><td>0 ≤ <em>atan(x)</em> ≤ π</td></tr> 1161<tr><td><code>ceil</code></td><td><em>x</em></td><td>smallest number not less than <em>x</em> whose value is an exact integer</td><td></td><td></td></tr> 1162<tr><td><code>cos</code></td><td><em>x</em></td><td>cosine of <em>x</em></td><td></td><td></td></tr> 1163<tr><td><code>exp</code></td><td><em>x</em></td><td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm</td><td></td><td></td></tr> 1164<tr><td><code>floor</code></td><td><em>x</em></td><td>the largest number not greater than <em>x</em> whose value is an exact integer</td><td></td><td></td></tr> 1165<tr><td><code>log</code></td><td><em>x</em></td><td>natural logarithm of <em>x</em></td><td><em>x</em> > 0</td><td></td></tr> 1166<tr><td><code>log10</code></td><td><em>x</em></td><td>base 10 logarithm of <em>x</em></td><td><em>x</em> > 0</td><td></td></tr> 1167<tr><td><code>pow</code></td><td><em>x, y</em></td><td><em>x</em><sup><em> y</em></sup></td><td></td><td></td></tr> 1168<tr><td><code>sqr</code></td><td><em>x</em></td><td><em>x</em><sup><em>2</em></sup></td><td></td><td></td></tr> 1169<tr><td><code>sqrt</code></td><td><em>x</em></td><td>√<em>x</em></td><td><em>x</em> > 0</td><td><em>sqrt(x)</em> ≥ 0</td></tr> 1170<tr><td><code>sin</code></td><td><em>x</em></td><td>sine of <em>x</em></td><td></td><td></td></tr> 1171<tr><td><code>tan</code></td><td><em>x</em></td><td>tangent of <em>x</em></td><td>x ≠ n*π/2, for odd integer <em>n</em></td><td></td></tr> 1172<caption class="bottom-caption">The names of mathematical functions defined in the SBML 1173Level 1 Version 2 text-string formula syntax.</caption> 1174</table> 1175 1176 1177 <p> 1178 * @warning <span class='warning'>There are differences between the symbols 1179 * used to represent the common mathematical functions and the corresponding 1180 * MathML token names. This is a potential source of incompatibilities. 1181 * Note in particular that in this text-string syntax, <code>log(x)</code> 1182 * represents the natural logarithm, whereas in MathML, the natural logarithm 1183 * is <code><ln/></code>. Application writers are urged to be careful 1184 * when translating between text forms and MathML forms, especially if they 1185 * provide a direct text-string input facility to users of their software 1186 * systems.</span> 1187 <p> 1188 * <p> 1189 * @warning <span class='warning'>We urge developers to keep in mind that 1190 * the text-string formula syntax is specific to SBML Level 1's C-like 1191 * mathematical formula syntax. In particular, it is <em>not a 1192 * general-purpose mathematical expression syntax</em>. LibSBML provides 1193 * methods for parsing and transforming text-string math formulas back and 1194 * forth from AST structures, but it is important to keep the system's 1195 * limitations in mind.</span> 1196 <p> 1197 * @param formula the text-string formula expression to be parsed 1198 <p> 1199 * @return the root node of the AST corresponding to the <code>formula</code>, or 1200 * <code>null</code> if an error occurred in parsing the formula 1201 <p> 1202 <p> 1203 <p> 1204 <p> 1205 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1206 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 1207 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1208 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 1209 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 1210 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 1211 */ public 1212 static ASTNode parseFormula(String formula) { 1213 long cPtr = libsbmlJNI.parseFormula(formula); 1214 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 1215 } 1216 1217 1218/** 1219 * Converts an AST to a string representation of a formula using a syntax 1220 * basically derived from SBML Level 1. 1221 <p> 1222 * <p> 1223 * The text-string form of mathematical formulas produced by 1224 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code> 1225 * and read by <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code> 1226 * use a simple C-inspired infix notation taken from SBML Level 1. A 1227 * formula in this text-string form therefore can be handed to a program 1228 * that understands SBML Level 1 mathematical expressions, or used as 1229 * part of a formula translation system. The syntax is described in detail 1230 * in the documentation for {@link ASTNode}. 1231 <p> 1232 * Note that this facility is provided as a convenience by libSBML—the 1233 * MathML standard does not actually define a 'string-form' equivalent to 1234 * MathML expression trees, so the choice of formula syntax is somewhat 1235 * arbitrary. The approach taken by libSBML is to use the syntax defined by 1236 * SBML Level 1 (which in fact used a text-string representation of 1237 * formulas and not MathML). This formula syntax is based mostly on C 1238 * programming syntax, and may contain operators, function calls, symbols, 1239 * and white space characters. The following table provides the precedence 1240 * rules for the different entities that may appear in formula strings. 1241 <p> 1242 * <table border="0" class="centered text-table width80 normal-font alt-row-colors" style="padding-bottom: 0.5em"> 1243 <tr style="background: lightgray; font-size: 14px;"> 1244 <th align="left">Token</th> 1245 <th align="left">Operation</th> 1246 <th align="left">Class</th> 1247 <th>Precedence</th> 1248 <th align="left">Associates</th> 1249 </tr> 1250<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">6</td><td>n/a</td></tr> 1251<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align="center">6</td><td>n/a</td></tr> 1252<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align="center">6</td><td>left</td></tr> 1253<tr><td><code>-</code></td><td>negation</td><td>unary</td><td align="center">5</td><td>right</td></tr> 1254<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">4</td><td>left</td></tr> 1255<tr><td><code>*</code></td><td>multiplication</td><td>binary</td><td align="center">3</td><td>left</td></tr> 1256<tr><td><code>/</code></td><td>divison</td><td>binary</td><td align="center">3</td><td>left</td></tr> 1257<tr><td><code>+</code></td><td>addition</td><td>binary</td><td align="center">2</td><td>left</td></tr> 1258<tr><td><code>-</code></td><td>subtraction</td><td>binary</td><td align="center">2</td><td>left</td></tr> 1259<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr> 1260<caption class="top-caption">A table of the expression operators and their precedence in the 1261text-string format for mathematical expressions used by SBML_parseFormula(). 1262</caption> 1263</table> 1264 1265 1266 <p> 1267 * In the table above, <em>operand</em> implies the construct is an operand, 1268 * <em>prefix</em> implies the operation is applied to the following arguments, 1269 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are 1270 * two arguments. The values in the <b>Precedence</b> column show how the 1271 * order of different types of operation are determined. For example, the 1272 * expression <code>a * b + c</code> is evaluated as <code>(a * b) + 1273 * c</code> because the @c * operator has higher precedence. The 1274 * <b>Associates</b> column shows how the order of similar precedence 1275 * operations is determined; for example, <code>a - b + c</code> is 1276 * evaluated as <code>(a - b) + c</code> because the <code>+</code> and <code>-</code> 1277 * operators are left-associative. 1278 <p> 1279 * The function call syntax consists of a function name, followed by optional 1280 * white space, followed by an opening parenthesis token, followed by a 1281 * sequence of zero or more arguments separated by commas (with each comma 1282 * optionally preceded and/or followed by zero or more white space 1283 * characters, followed by a closing parenthesis token. The function name 1284 * must be chosen from one of the pre-defined functions in SBML or a 1285 * user-defined function in the model. The following table lists the names 1286 * of certain common mathematical functions; this table corresponds to 1287 * Table 6 in the <a target='_blank' href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML Level 1 Version 2 specification</a>: 1288 <p> 1289 * <table border="0" class="centered text-table width80 normal-font alt-row-colors"> 1290 <tr> 1291 <th align="left" width="60">Name</th> 1292 <th align="left" width="35">Args</th> 1293 <th align="left">Formula or meaning</th> 1294 <th align="left" width="110">Argument Constraints</th> 1295 <th align="left" width="100">Result constraints</th> 1296 </tr> 1297<tr><td><code>abs</code></td><td><em>x</em></td><td>absolute value of <em>x</em></td><td></td><td></td></tr> 1298<tr><td><code>acos</code></td><td><em>x</em></td><td>arc cosine of <em>x</em> in radians</td><td>-1.0 ≤ <em>x</em> ≤ 1.0</td><td>0 ≤ <em>acos(x)</em> ≤ π</td></tr> 1299<tr><td><code>asin</code></td><td><em>x</em></td><td>arc sine of <em>x</em> in radians</td><td>-1.0 ≤ <em>x</em> ≤ 1.0</td><td>0 ≤ <em>asin(x)</em> ≤ π</td></tr> 1300<tr><td><code>atan</code></td><td><em>x</em></td><td>arc tangent of <em>x</em> in radians</td><td></td><td>0 ≤ <em>atan(x)</em> ≤ π</td></tr> 1301<tr><td><code>ceil</code></td><td><em>x</em></td><td>smallest number not less than <em>x</em> whose value is an exact integer</td><td></td><td></td></tr> 1302<tr><td><code>cos</code></td><td><em>x</em></td><td>cosine of <em>x</em></td><td></td><td></td></tr> 1303<tr><td><code>exp</code></td><td><em>x</em></td><td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm</td><td></td><td></td></tr> 1304<tr><td><code>floor</code></td><td><em>x</em></td><td>the largest number not greater than <em>x</em> whose value is an exact integer</td><td></td><td></td></tr> 1305<tr><td><code>log</code></td><td><em>x</em></td><td>natural logarithm of <em>x</em></td><td><em>x</em> > 0</td><td></td></tr> 1306<tr><td><code>log10</code></td><td><em>x</em></td><td>base 10 logarithm of <em>x</em></td><td><em>x</em> > 0</td><td></td></tr> 1307<tr><td><code>pow</code></td><td><em>x, y</em></td><td><em>x</em><sup><em> y</em></sup></td><td></td><td></td></tr> 1308<tr><td><code>sqr</code></td><td><em>x</em></td><td><em>x</em><sup><em>2</em></sup></td><td></td><td></td></tr> 1309<tr><td><code>sqrt</code></td><td><em>x</em></td><td>√<em>x</em></td><td><em>x</em> > 0</td><td><em>sqrt(x)</em> ≥ 0</td></tr> 1310<tr><td><code>sin</code></td><td><em>x</em></td><td>sine of <em>x</em></td><td></td><td></td></tr> 1311<tr><td><code>tan</code></td><td><em>x</em></td><td>tangent of <em>x</em></td><td>x ≠ n*π/2, for odd integer <em>n</em></td><td></td></tr> 1312<caption class="bottom-caption">The names of mathematical functions defined in the SBML 1313Level 1 Version 2 text-string formula syntax.</caption> 1314</table> 1315 1316 1317 <p> 1318 * @warning <span class='warning'>There are differences between the symbols 1319 * used to represent the common mathematical functions and the corresponding 1320 * MathML token names. This is a potential source of incompatibilities. 1321 * Note in particular that in this text-string syntax, <code>log(x)</code> 1322 * represents the natural logarithm, whereas in MathML, the natural logarithm 1323 * is <code><ln/></code>. Application writers are urged to be careful 1324 * when translating between text forms and MathML forms, especially if they 1325 * provide a direct text-string input facility to users of their software 1326 * systems.</span> 1327 <p> 1328 * <p> 1329 * @warning <span class='warning'>We urge developers to keep in mind that 1330 * the text-string formula syntax is specific to SBML Level 1's C-like 1331 * mathematical formula syntax. In particular, it is <em>not a 1332 * general-purpose mathematical expression syntax</em>. LibSBML provides 1333 * methods for parsing and transforming text-string math formulas back and 1334 * forth from AST structures, but it is important to keep the system's 1335 * limitations in mind.</span> 1336 <p> 1337 * @param tree the AST to be converted. 1338 <p> 1339 * @return the formula from the given AST as an SBML Level 1 text-string 1340 * mathematical formula. The caller owns the returned string and is 1341 * responsible for freeing it when it is no longer needed. 1342 <p> 1343 <p> 1344 <p> 1345 <p> 1346 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1347 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 1348 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1349 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 1350 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 1351 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 1352 */ public 1353 static String formulaToString(ASTNode tree) { 1354 return libsbmlJNI.formulaToString(ASTNode.getCPtr(tree), tree); 1355 } 1356 1357 1358/** 1359 * Parses the given mathematical formula and returns a representation of it 1360 * as an Abstract Syntax Tree (AST). 1361 <p> 1362 * <p> 1363 * The text-string form of mathematical formulas read by the functions 1364 * <code><a 1365 * href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'>libsbml.formulaToL3String(ASTNode 1366 * tree)</a></code> and <code><a 1367 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String 1368 * formula)</a></code> are expanded versions of the formats produced 1369 * and read by <code><a 1370 * href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode 1371 * tree)</a></code> and * <code><a 1372 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String 1373 * formula)</a></code>, respectively. The latter two libSBML 1374 * functions were originally developed to support conversion between SBML 1375 * Levels 1 and 2, and were focused on the syntax of mathematical 1376 * formulas used in SBML Level 1. With time, and the use of MathML in 1377 * SBML Levels 2 and 3, it became clear that supporting 1378 * Level 2 and 3's expanded mathematical syntax would be useful for 1379 * software developers. 1380 * To maintain backwards compatibility, the original 1381 * <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode)'>libsbml.formulaToString(ASTNode tree)</a></code> 1382 * and 1383 * <code><a href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String formula)</a></code> 1384 * have been left untouched, and instead, the new functionality is 1385 * provided in the form of 1386 * <cod 1387e><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1388 * and <code><a 1389 * href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'>libsbml.formulaToL3String(ASTNode 1390 * tree)</a></code>. 1391 <p> 1392 * The following are the differences in the formula syntax supported by the 1393 * 'L3' versions of the formula parsers and formatters, compared to what is 1394 * supported by * <code><a 1395 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String 1396 * formula)</a></code> and <code><a 1397 * href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'>libsbml.formulaToL3String(ASTNode 1398 * tree)</a></code>: 1399 <p> 1400 * <ul> 1401 * <li> Units may be asociated with bare numbers, using the following syntax: 1402 * <div style='margin: 10px auto 10px 25px; display: block'> 1403 * <span class='code' style='background-color: #d0d0ee'>number</span> 1404 * <span class='code' style='background-color: #edd'>unit</span> 1405 * </div> 1406 * The <span class='code' style='background-color: #d0d0ee'>number</span> 1407 * may be in any form (an integer, real, or rational 1408 * number), and the 1409 * <span class='code' style='background-color: #edd'>unit</span> 1410 * must conform to the syntax of an SBML identifier (technically, the 1411 * type defined as <code>SId</code> in the SBML specifications). The whitespace between 1412 * <span class='code' style='background-color: #d0d0ee'>number</span> 1413 * and <span class='code' style='background-color: #edd'>unit</span> 1414 * is optional. 1415 <p> 1416 * <li> The Boolean function symbols <code>&&</code>, <code>||</code>, <code>!</code>, and <code>!=</code> may be 1417 * used. 1418 <p> 1419 * <li> The <em>modulo</em> operation is allowed as the symbol <code>@%</code> and will 1420 * produce a piecewise function in the MathML. 1421 <p> 1422 * <li> All inverse trigonometric functions may be defined in the infix either 1423 * using <code>arc</code> as a prefix or simply <code>a</code>; in other words, both <code>arccsc</code> 1424 * and <code>acsc</code> are interpreted as the operator <em>arccosecant</em> defined in 1425 * MathML. (Many functions in the SBML Level 1 infix-notation parser 1426 * implemented by * <code><a 1427 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String 1428 * formula)</a></code> are defined this way as well, but not all.) 1429 <p> 1430 * <li> The following expression is parsed as a rational number instead of 1431 * as a numerical division: 1432 * <pre style='display: block; margin-left: 25px'> 1433 * (<span class='code' style='background-color: #d0d0ee'>integer</span>/<span class='code' style='background-color: #d0d0ee'>integer</span>)</pre> 1434 * No spaces are allowed in this construct; in other words, 1435 * "<code>(3 / 4)</code>" will be parsed into the MathML 1436 * <code><divide></code> construct rather than a rational number. The 1437 * general number syntax allows you to assign units to a rational number, e.g., 1438 * "<code>(3/4) ml</code>". (If the string is a division, units 1439 * are not interpreted in this way.) 1440 <p> 1441 * <li> Various settings may be altered by using an {@link L3ParserSettings} object in 1442 * conjunction with the functions <code><a 1443 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, 1444 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String 1445 * formula, {@link L3ParserSettings} settings)</a></code> and <code><a 1446 * href='libsbml.html#formulaToL3String(org.sbml.libsbml.ASTNode)'>libsbml.formulaToL3String(ASTNode 1447 * tree)</a></code>, including the following: 1448 * <ul> 1449 * <li> The function <code>log</code> with a single argument ("<code>log(x)</code>") 1450 * can be parsed as <code>log10(x)</code>, <code>ln(x)</code>, or treated 1451 * as an error, as desired. 1452 * <li> Unary minus signs can be collapsed or preserved; that is, 1453 * sequential pairs of unary minuses (e.g., "<code>- -3</code>") 1454 * can be removed from the input entirely and single unary minuses can be 1455 * incorporated into the number node, or all minuses can be preserved in 1456 * the AST node structure. 1457 * <li> Parsing of units embedded in the input string can be turned on and 1458 * off. 1459 * <li> The string <code>avogadro</code> can be parsed as a MathML <em>csymbol</em> or 1460 * as an identifier. 1461 * <li> A {@link Model} object may optionally be provided to the parser using the 1462 * variant function call 1463 * <code><a 1464 * href='libsbml.html#parseL3FormulaWithModel(java.lang.String, 1465 * org.sbml.libsbml.Model)'>libsbml.parseL3FormulaWithModel(String formula, 1466 * {@link Model} model)</a></code> or stored in a {@link L3ParserSettings} object 1467 * passed to the variant function <code><a 1468 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, 1469 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String 1470 * formula, {@link L3ParserSettings} settings)</a></code>. 1471 * When a {@link Model} object is provided, identifiers (values of type <code>SId</code>) from 1472 * that model are used in preference to pre-defined MathML definitions. More 1473 * precisely, the {@link Model} entities whose identifiers will shadow identical 1474 * symbols in the mathematical formula are: {@link Species}, {@link Compartment}, {@link Parameter}, 1475 * {@link Reaction}, and {@link SpeciesReference}. For instance, if the parser is given a 1476 * {@link Model} containing a {@link Species} with the identifier 1477 * "<code>pi</code>", and the formula to be parsed is 1478 * "<code>3*pi</code>", the MathML produced will contain the 1479 * construct <code><ci> pi </ci></code> instead of the construct 1480 * <code><pi/></code>. <li> Similarly, when a {@link Model} object is 1481 * provided, <code>SId</code> values of user-defined functions present in the model 1482 * will be used preferentially over pre-defined MathML functions. For 1483 * example, if the passed-in {@link Model} contains a {@link FunctionDefinition} with the 1484 * identifier "<code>sin</code>", that function will be used 1485 * instead of the predefined MathML function <code><sin/></code>. 1486 * </ul> 1487 * These configuration settings cannot be changed using the basic parser and 1488 * formatter functions, but can be changed on a per-call basis by using the 1489 * alternative functions <code><a 1490 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, 1491 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String 1492 * formula, {@link L3ParserSettings} settings)</a></code> and <code><a 1493 * href='libsbml.html#formulaToL3StringWithSettings(const ASTNode_t tree, 1494 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(ASTNode tree 1495 * {@link L3ParserSettings} settings)</a></code>. 1496 * 1497 * </ul> <p> 1498 * The parser function <code><a 1499 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, 1500 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String 1501 * formula, {@link L3ParserSettings} settings)</a></code> 1502 * returns the root node of the AST corresponding to the 1503 * formula given as the argument. If the formula contains a syntax error, 1504 * the function will return <code>null</code> instead. When <code>null</code> is returned, an 1505 * error is set; information about the error can be retrieved using 1506 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>. 1507 <p> 1508 * Note that this facility and the SBML Level 1-based <code><a 1509 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String 1510 * formula)</a></code> are provided as a convenience by 1511 * libSBML—the MathML standard does not actually define a 'string-form' 1512 * equivalent to MathML expressions, so the choice of formula syntax is 1513 * arbitrary. The approach taken by libSBML is to start with the syntax 1514 * defined by SBML Level 1 (which in fact used a text-string 1515 * representation of formulas, and not MathML), and expand it to include the 1516 * above functionality. This formula syntax is based mostly on C programming 1517 * syntax, and may contain operators, function calls, symbols, and white 1518 * space characters. The following table provides the precedence rules for 1519 * the different entities that may appear in formula strings. 1520 <p> 1521 * <table border="0" class="centered text-table width80 normal-font alt-row-colors" style="padding-bottom: 0.5em"> 1522 <tr style="background: lightgray; font-size: 14px;"> 1523 <th align="left">Token</th> 1524 <th align="left">Operation</th> 1525 <th align="left">Class</th> 1526 <th>Precedence</th> 1527 <th align="left">Associates</th> 1528 </tr> 1529<tr><td><em>name</em></td><td>symbol reference</td><td>operand</td><td align="center">8</td><td>n/a</td></tr> 1530<tr><td><code>(</code><em>expression</em><code>)</code></td><td>expression grouping</td><td>operand</td><td align="center">8</td><td>n/a</td></tr> 1531<tr><td><code>f(</code><em>...</em><code>)</code></td><td>function call</td><td>prefix</td><td align="center">8</td><td>left</td></tr> 1532<tr><td><code>^</code></td><td>power</td><td>binary</td><td align="center">7</td><td>left</td></tr> 1533<tr><td><code>-, !</code></td><td>negation and boolean 'not'</td><td>unary</td><td align="center">6</td><td>right</td></tr> 1534<tr><td><code>*, /, %</code></td><td>multiplication, division, and modulo</td><td>binary</td><td align="center">5</td><td>left</td></tr> 1535<tr><td><code>+, -</code></td><td>addition and subtraction</td><td>binary</td><td align="center">4</td><td>left</td></tr> 1536<tr><td><code>==, <, >, <=, >=, !=</code></td><td>boolean equality, inequality, and comparison</td><td>binary</td><td align="center">3</td><td>left</td></tr> 1537<tr><td><code>&&, ||</code></td><td>boolean 'and' and 'or'</td><td>binary</td><td align="center">2</td><td>left</td></tr> 1538<tr><td><code>,</code></td><td>argument delimiter</td><td>binary</td><td align="center">1</td><td>left</td></tr> 1539<caption class="top-caption">A table of the expression operators and their precedence in the 1540text-string format for mathematical expressions used by SBML_parseL3Formula(). 1541</caption> 1542</table> 1543 1544 1545 <p> 1546 * In the table above, <em>operand</em> implies the construct is an operand, 1547 * <em>prefix</em> implies the operation is applied to the following arguments, 1548 * <em>unary</em> implies there is one argument, and <em>binary</em> implies there are 1549 * two arguments. The values in the <b>Precedence</b> column show how the 1550 * order of different types of operation are determined. For example, the 1551 * expression <code>a + b * c</code> is evaluated as <code>a + (b * c)</code> 1552 * because the @c * operator has higher precedence. The 1553 * <b>Associates</b> column shows how the order of similar precedence 1554 * operations is determined; for example, <code>a && b || c</code> is 1555 * evaluated as <code>(a && b) || c</code> because the <code>&&</code> and <code>||</code> 1556 * operators are left-associative and have the same precedence. 1557 <p> 1558 * The function call syntax consists of a function name, followed by optional 1559 * white space, followed by an opening parenthesis token, followed by a 1560 * sequence of zero or more arguments separated by commas (with each comma 1561 * optionally preceded and/or followed by zero or more white space 1562 * characters), followed by a closing parenthesis token. The function name 1563 * must be chosen from one of the pre-defined functions in SBML or a 1564 * user-defined function in the model. The following table lists the names 1565 * of certain common mathematical functions; this table corresponds to 1566 * Table 6 in the <a target='_blank' 1567 * href='http://sbml.org/Documents/Specifications#SBML_Level_1_Version_2'>SBML 1568 * Level 1 Version 2 specification</a> with additions based on the 1569 * functions added in SBML Level 2 and Level 3: 1570 <p> 1571 * <table border="0" class="centered text-table width80 normal-font alt-row-colors"> 1572 <tr> 1573 <th align="left" width="100">Name</th> 1574 <th align="left" width="100">Argument(s)</th> 1575 <th align="left">Formula or meaning</th> 1576 <th align="left" width="110">Argument Constraints</th> 1577 <th align="left" width="100">Result constraints</th> 1578 </tr> 1579<tr><td><code>abs</code></td> 1580 <td><em>x</em></td> 1581 <td>Absolute value of <em>x</em>.</td> 1582 <td></td> 1583 <td></td> 1584</tr> 1585<tr><td><code>acos</code>, <code>arccos</code></td> 1586 <td><em>x</em></td> 1587 <td>Arccosine of <em>x</em> in radians.</td> 1588 <td>-1.0 ≤ <em>x</em> ≤ 1.0</td> 1589 <td>0 ≤ <em>acos(x)</em> ≤ π</td> 1590</tr> 1591<tr><td><code>acosh</code>, <code>arccosh</code></td> 1592 <td><em>x</em></td> 1593 <td>Hyperbolic arccosine of <em>x</em> in radians.</td> 1594 <td></td> 1595 <td></td> 1596</tr> 1597<tr><td><code>acot</code>, <code>arccot</code></td> 1598 <td><em>x</em></td> 1599 <td>Arccotangent of <em>x</em> in radians.</td> 1600 <td></td> 1601 <td></td> 1602</tr> 1603<tr><td><code>acoth</code>, <code>arccoth</code></td> 1604 <td><em>x</em></td> 1605 <td>Hyperbolic arccotangent of <em>x</em> in radians.</td> 1606 <td></td> 1607 <td></td> 1608</tr> 1609<tr><td><code>acsc</code>, <code>arccsc</code></td> 1610 <td><em>x</em></td> 1611 <td>Arccosecant of <em>x</em> in radians.</td> 1612 <td></td> 1613 <td></td> 1614</tr> 1615<tr><td><code>acsch</code>, <code>arccsch</code></td> 1616 <td><em>x</em></td> 1617 <td>Hyperbolic arccosecant of <em>x</em> in radians.</td> 1618 <td></td> 1619 <td></td> 1620</tr> 1621<tr><td><code>asec</code>, <code>arcsec</code></td> 1622 <td><em>x</em></td> 1623 <td>Arcsecant of <em>x</em> in radians.</td> 1624 <td></td> 1625 <td></td> 1626</tr> 1627<tr><td><code>asech</code>, <code>arcsech</code></td> 1628 <td><em>x</em></td> 1629 <td>Hyperbolic arcsecant of <em>x</em> in radians.</td> 1630 <td></td> 1631 <td></td> 1632</tr> 1633<tr><td><code>asin</code>, <code>arcsin</code></td> 1634 <td><em>x</em></td><td>Arcsine of <em>x</em> in radians.</td> 1635 <td>-1.0 ≤ <em>x</em> ≤ 1.0</td> 1636 <td>0 ≤ <em>asin(x)</em> ≤ π</td> 1637</tr> 1638<tr><td><code>atan</code>, <code>arctan</code></td> 1639 <td><em>x</em></td> 1640 <td>Arctangent of <em>x</em> in radians.</td> 1641 <td></td> 1642 <td>0 ≤ <em>atan(x)</em> ≤ π</td> 1643</tr> 1644<tr><td><code>atanh</code>, <code>arctanh</code></td> 1645 <td><em>x</em></td> 1646 <td>Hyperbolic arctangent of <em>x</em> in radians.</td> 1647 <td></td> 1648 <td></td> 1649</tr> 1650<tr><td><code>ceil</code>, <code>ceiling</code></td> 1651 <td><em>x</em></td> 1652 <td>Smallest number not less than <em>x</em> whose value is an exact integer.</td> 1653 <td></td> 1654 <td></td> 1655</tr> 1656<tr><td><code>cos</code></td> 1657 <td><em>x</em></td> 1658 <td>Cosine of <em>x</em></td> 1659 <td></td> 1660 <td></td> 1661</tr> 1662<tr><td><code>cosh</code></td> 1663 <td><em>x</em></td> 1664 <td>Hyperbolic cosine of <em>x</em>.</td> 1665 <td></td> 1666 <td></td> 1667</tr> 1668<tr><td><code>cot</code></td> 1669 <td><em>x</em></td> 1670 <td>Cotangent of <em>x</em>.</td> 1671 <td></td> 1672 <td></td> 1673</tr> 1674<tr><td><code>coth</code></td> 1675 <td><em>x</em></td> 1676 <td>Hyperbolic cotangent of <em>x</em>.</td> 1677 <td></td> 1678 <td></td> 1679</tr> 1680<tr><td><code>csc</code></td> 1681 <td><em>x</em></td> 1682 <td>Cosecant of <em>x</em>.</td> 1683 <td></td> 1684 <td></td> 1685</tr> 1686<tr><td><code>csch</code></td> 1687 <td><em>x</em></td> 1688 <td>Hyperbolic cosecant of <em>x</em>.</td> 1689 <td></td> 1690 <td></td> 1691</tr> 1692<tr><td><code>delay</code></td> 1693 <td><em>x, y</em></td> 1694 <td>The value of <em>x</em> at <em>y</em> time units in the past.</td> 1695 <td></td> 1696 <td></td> 1697</tr> 1698<tr><td><code>factorial</code></td> 1699 <td><em>n</em></td> 1700 <td>The factorial of <em>n</em>. Factorials are defined by n! = n*(n-1)* ... * 1.</td> 1701 <td><em>n</em> must be an integer.</td> 1702 <td></td> 1703</tr> 1704<tr><td><code>exp</code></td> 1705 <td><em>x</em></td> 1706 <td><em>e</em><sup><em> x</em></sup>, where <em>e</em> is the base of the natural logarithm.</td> 1707 <td></td> 1708 <td></td> 1709</tr> 1710<tr><td><code>floor</code></td> 1711 <td><em>x</em></td> 1712 <td>The largest number not greater than <em>x</em> whose value is an exact integer.</td> 1713 <td></td> 1714 <td></td> 1715</tr> 1716<tr><td><code>ln</code></td> 1717 <td><em>x</em></td> 1718 <td>Natural logarithm of <em>x</em>.</td> 1719 <td><em>x</em> > 0</td> 1720 <td></td> 1721</tr> 1722<tr><td><code>log</code></td> 1723 <td><em>x</em></td> 1724 <td>By default, the base 10 logarithm of <em>x</em>, but can be set to be the natural logarithm of <em>x</em>, or to be an illegal construct.</td> 1725 <td><em>x</em> > 0</td> 1726 <td></td> 1727</tr> 1728<tr><td><code>log</code></td> 1729 <td><em>x, y</em></td> 1730 <td>The base <em>x</em> logarithm of <em>y</em>.</td> 1731 <td><em>y</em> > 0</td> 1732 <td></td> 1733</tr> 1734<tr><td><code>log10</code></td> 1735 <td><em>x</em></td> 1736 <td>Base 10 logarithm of <em>x</em>.</td> 1737 <td><em>x</em> > 0</td> 1738 <td></td> 1739</tr> 1740<tr><td><code>piecewise</code></td> 1741 <td><em>x1, y1, [x2, y2,] [...] [z]</em></td> 1742 <td>A piecewise function: if (<em>y1</em>), <em>x1</em>. Otherwise, if (<em>y2</em>), <em>x2</em>, etc. Otherwise, z. </td> 1743 <td><em>y1, y2, y3 [etc]</em> must be boolean</td> 1744 <td></td> 1745</tr> 1746<tr><td><code>pow</code>, <code>power</code> </td> 1747 <td><em>x, y</em></td> 1748 <td><em>x</em><sup><em> y</em></sup>.</td> 1749 <td></td> 1750 <td></td> 1751</tr> 1752<tr><td><code>root</code></td> 1753 <td><em>b, x</em></td> 1754 <td>The root base <em>b</em> of <em>x</em>.</td> 1755 <td></td> 1756 <td></td> 1757</tr> 1758<tr><td><code>sec</code></td> 1759 <td><em>x</em></td> 1760 <td>Secant of <em>x</em>.</td> 1761 <td></td> 1762 <td></td> 1763</tr> 1764<tr><td><code>sech</code></td> 1765 <td><em>x</em></td> 1766 <td>Hyperbolic secant of <em>x</em>.</td> 1767 <td></td> 1768 <td></td> 1769</tr> 1770<tr><td><code>sqr</code></td> 1771 <td><em>x</em></td> 1772 <td><em>x</em><sup><em>2</em></sup>.</td> 1773 <td></td> 1774 <td></td> 1775</tr> 1776<tr><td><code>sqrt</code></td> 1777 <td><em>x</em></td> 1778 <td>√<em>x</em>.</td> 1779 <td><em>x</em> > 0</td> 1780 <td><em>sqrt(x)</em> ≥ 0</td> 1781</tr> 1782<tr><td><code>sin</code></td> 1783 <td><em>x</em></td> 1784 <td>Sine of <em>x</em>.</td> 1785 <td></td> 1786 <td></td> 1787</tr> 1788<tr><td><code>sinh</code></td> 1789 <td><em>x</em></td> 1790 <td>Hyperbolic sine of <em>x</em>.</td> 1791 <td></td> 1792 <td></td> 1793</tr> 1794<tr><td><code>tan</code></td> 1795 <td><em>x</em></td> 1796 <td>Tangent of <em>x</em>.</td> 1797 <td>x ≠ n*π/2, for odd integer <em>n</em></td> 1798 <td></td> 1799</tr> 1800<tr><td><code>tanh</code></td> 1801 <td><em>x</em></td> 1802 <td>Hyperbolic tangent of <em>x</em>.</td> 1803 <td></td> 1804 <td></td> 1805</tr> 1806<tr><td><code>and</code></td> 1807 <td><em>x, y, z...</em></td> 1808 <td>Boolean and(<em>x, y, z...</em>): returns true if all of its arguments are true. Note that 'and' is an n-ary function, taking 0 or more arguments, and that and() returns 'true'.</td> 1809 <td>All arguments must be boolean</td> 1810 <td></td> 1811</tr> 1812<tr><td><code>not</code></td> 1813 <td><em>x</em></td> 1814 <td>Boolean not(<em>x</em>)</td> 1815 <td><em>x</em> must be boolean</td> 1816 <td></td> 1817</tr> 1818<tr><td><code>or</code></td> 1819 <td><em>x, y, z...</em></td> 1820 <td>Boolean or(<em>x, y, z...</em>): returns true if at least one of its arguments is true. Note that 'or' is an n-ary function, taking 0 or more arguments, and that or() returns 'false'.</td> 1821 <td>All arguments must be boolean</td> 1822 <td></td> 1823</tr> 1824<tr><td><code>xor</code></td> 1825 <td><em>x, y, z...</em></td> 1826 <td>Boolean xor(<em>x, y, z...</em>): returns true if an odd number of its arguments is true. Note that 'xor' is an n-ary function, taking 0 or more arguments, and that xor() returns 'false'.</td> 1827 <td>All arguments must be boolean</td> 1828 <td></td> 1829</tr> 1830<tr><td><code>eq</code></td> 1831 <td><em>x, y, z...</em></td> 1832 <td>Boolean eq(<em>x, y, z...</em>): returns true if all arguments are equal. Note that 'eq' is an n-ary function, but must take 2 or more arguments.</td> 1833 <td></td> 1834 <td></td> 1835</tr> 1836<tr><td><code>geq</code></td> 1837 <td><em>x, y, z...</em></td> 1838 <td>Boolean geq(<em>x, y, z...</em>): returns true if each argument is greater than or equal to the argument following it. Note that 'geq' is an n-ary function, but must take 2 or more arguments.</td> 1839 <td></td> 1840 <td></td> 1841</tr> 1842<tr><td><code>gt</code></td> 1843 <td><em>x, y, z...</em></td> 1844 <td>Boolean gt(<em>x, y, z...</em>): returns true if each argument is greater than the argument following it. Note that 'gt' is an n-ary function, but must take 2 or more arguments.</td> 1845 <td></td> 1846 <td></td> 1847</tr> 1848<tr><td><code>leq</code></td> 1849 <td><em>x, y, z...</em></td> 1850 <td>Boolean leq(<em>x, y, z...</em>): returns true if each argument is less than or equal to the argument following it. Note that 'leq' is an n-ary function, but must take 2 or more arguments.</td> 1851 <td></td> 1852 <td></td> 1853</tr> 1854<tr><td><code>lt</code></td> 1855 <td><em>x, y, z...</em></td> 1856 <td>Boolean lt(<em>x, y, z...</em>): returns true if each argument is less than the argument following it. Note that 'lt' is an n-ary function, but must take 2 or more arguments.</td> 1857 <td></td> 1858 <td></td> 1859</tr> 1860<tr><td><code>neq</code></td> 1861 <td><em>x, y</em></td> 1862 <td>Boolean <em>x</em> != <em>y</em>: returns true unless x and y are equal.</td> 1863 <td></td> 1864 <td></td> 1865</tr> 1866<tr><td><code>plus</code></td> 1867 <td><em>x, y, z...</em></td> 1868 <td><em>x</em> + <em>y</em> + <em>z</em> + <em>...</em>: The sum of the arguments of the function. Note that 'plus' is an n-ary function taking 0 or more arguments, and that 'plus()' returns 0.</td> 1869 <td></td> 1870 <td></td> 1871</tr> 1872<tr><td><code>times</code></td> 1873 <td><em>x, y, z...</em></td> 1874 <td><em>x</em> * <em>y</em> * <em>z</em> * <em>...</em>: The product of the arguments of the function. Note that 'times' is an n-ary function taking 0 or more arguments, and that 'times()' returns 1.</td> 1875 <td></td> 1876 <td></td> 1877</tr> 1878<tr><td><code>minus</code></td> 1879 <td><em>x, y</em></td> 1880 <td><em>x</em> - <em>y</em>.</td> 1881 <td></td> 1882 <td></td> 1883</tr> 1884<tr><td><code>divide</code></td> 1885 <td><em>x, y</em></td> 1886 <td><em>x</em> / <em>y</em>.</td> 1887 <td></td> 1888 <td></td> 1889</tr> 1890 1891<caption class="top-caption">The names of mathematical functions defined 1892in the text-string formula syntax understood by SBML_parseL3Formula() and 1893related functions.</caption> 1894 1895</table> 1896 1897 1898 <p> 1899 * Note that the manner in which the 'L3' versions of the formula parser and 1900 * formatter interpret the function "<code>log</code>" can be 1901 * changed. To do so, callers should use the function <code><a 1902 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, 1903 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String 1904 * formula, {@link L3ParserSettings} settings)</a></code> 1905 * and pass it an appropriate {@link L3ParserSettings} object. By default, 1906 * unlike the SBML Level 1 parser implemented by <code><a 1907 * href='libsbml.html#parseFormula(java.lang.String)'>libsbml.parseFormula(String 1908 * formula)</a></code>, the string "<code>log</code>" is 1909 * interpreted as the base 10 logarithm, and <em>not</em> as the natural 1910 * logarithm. However, you can change the interpretation to be base-10 log, 1911 * natural log, or as an error; since the name 'log' by itself is ambiguous, 1912 * you require that the parser uses <code>log10</code> or <code>ln</code> instead, which are more 1913 * clear. Please refer to <code><a 1914 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, 1915 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String 1916 * formula, {@link L3ParserSettings} settings)</a></code>. 1917 <p> 1918 * In addition, the following symbols will be translated to their MathML 1919 * equivalents, if no symbol with the same <code>SId</code> identifier string exists 1920 * in the {@link Model} object provided: 1921 <p> 1922 * <table border="0" class="centered text-table width80 normal-font alt-row-colors"> 1923 <tr> 1924 <th align="left" width="60">Name</th> 1925 <th align="left" width="200">Meaning</th> 1926 <th align="left">MathML</th> 1927 </tr> 1928<tr><td><code>true</code></td> 1929 <td>The boolean value <code>true</code></td> 1930 <td><code><true/></code></td> 1931</tr> 1932<tr><td><code>false</code></td> 1933 <td>The boolean value <code>false</code></td> 1934 <td><code><false/></code></td> 1935</tr> 1936<tr><td><code>pi</code></td> 1937 <td>The mathematical constant pi</td> 1938 <td><code><pi/></code></td> 1939</tr> 1940<tr><td><code>avogadro</code></td> 1941 <td>The numerical value of Avogadro's constant, as defined in the SBML specification</td> 1942 <td><code><csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/avogadro"> avogadro </csymbol/></code></td> 1943</tr> 1944<tr><td><code>time</code></td> 1945 <td>Simulation time as defined in SBML</td> 1946 <td><code><csymbol encoding="text" definitionURL="http://www.sbml.org/sbml/symbols/time"> time </csymbol/></code></td> 1947</tr> 1948<tr><td><code>inf</code> or <code>infinity</code></td> 1949 <td>The mathematical constant "infinity"</td> 1950 <td><code><infinity/></code></td> 1951</tr> 1952<tr><td><code>nan</code> or <code>notanumber</code></td> 1953 <td>The mathematical concept "not a number"</td> 1954 <td><code><notanumber/></code></td> 1955</tr> 1956 1957<caption class="top-caption">The names of mathematical symbols defined 1958in the text-string formula syntax understood by 1959SBML_parseL3Formula() and related functions. 1960</caption> 1961</table> 1962 1963 <p> 1964 * Note that whether the string "<code>avogadro</code>" is parsed 1965 * as an AST node of type {@link libsbmlConstants#AST_NAME_AVOGADRO 1966 * AST_NAME_AVOGADRO} or {@link libsbmlConstants#AST_NAME AST_NAME} 1967 * is configurable; use the alternate version of this function, called <code><a 1968 * href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, 1969 * org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String 1970 * formula, {@link L3ParserSettings} settings)</a></code>. This 1971 * functionality is provided because SBML Level 2 models may not use 1972 * {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} AST nodes. 1973<p> 1974 * @param formula the text-string formula expression to be parsed 1975 <p> 1976 * @return the root node of an AST representing the mathematical formula, 1977 * or <code>null</code> if an error occurred while parsing the formula. When <code>null</code> 1978 * is returned, an error is recorded internally; information about the 1979 * error can be retrieved using 1980 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>. 1981 <p> 1982 <p> 1983 <p> 1984 <p> 1985 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 1986 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 1987 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 1988 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 1989 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 1990 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 1991 */ public 1992 static ASTNode parseL3Formula(String formula) { 1993 long cPtr = libsbmlJNI.parseL3Formula(formula); 1994 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 1995 } 1996 1997 1998/** 1999 * Parses the given mathematical formula using specific a specific {@link Model} to 2000 * resolve symbols, and returns an Abstract Syntax Tree (AST) 2001 * representation of the result. 2002 <p> 2003 * This is identical to 2004 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>, 2005 * except that this function uses the given model in the argument <code>model</code> 2006 * to check against identifiers that appear in the <code>formula</code>. 2007 <p> 2008 * For more details about the parser, please see the definition of 2009 * the function <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 2010 <p> 2011 * @param formula the mathematical formula expression to be parsed 2012 <p> 2013 * @param model the {@link Model} object to use for checking identifiers 2014 <p> 2015 * @return the root node of an AST representing the mathematical formula, 2016 * or <code>null</code> if an error occurred while parsing the formula. When <code>null</code> 2017 * is returned, an error is recorded internally; information about the 2018 * error can be retrieved using 2019 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>. 2020 <p> 2021 <p> 2022 <p> 2023 <p> 2024 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 2025 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 2026 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 2027 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 2028 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 2029 */ public 2030 static ASTNode parseL3FormulaWithModel(String formula, Model model) { 2031 long cPtr = libsbmlJNI.parseL3FormulaWithModel(formula, Model.getCPtr(model), model); 2032 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 2033 } 2034 2035 2036/** 2037 * Parses the given mathematical formula using specific parser settings and 2038 * returns an Abstract Syntax Tree (AST) representation of the result. 2039 <p> 2040 * This is identical to 2041 <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>, 2042 * except that this function uses the parser settings given in the argument 2043 * <code>settings</code>. The settings override the default parsing behavior. 2044 <p> 2045 * The parameter <code>settings</code> allows callers to change the following parsing 2046 * behaviors: 2047 <p> 2048 * <ul> 2049 * <li> Use a specific {@link Model} object against which identifiers to compare 2050 * identifiers. This causes the parser to search the {@link Model} for identifiers 2051 * that the parser encounters in the formula. If a given symbol in the 2052 * formula matches the identifier of a {@link Species}, {@link Compartment}, {@link Parameter}, 2053 * {@link Reaction}, {@link SpeciesReference} or {@link FunctionDefinition} in the {@link Model}, then the 2054 * symbol is assumed to refer to that model entity instead of any possible 2055 * mathematical terms with the same symbol. For example, if the parser is 2056 * given a {@link Model} containing a {@link Species} with the identifier 2057 * "<code>pi</code>", and the formula to be parsed is 2058 * "<code>3*pi</code>", the MathML produced will contain the 2059 * construct <code><ci> pi </ci></code> instead of the 2060 * construct <code><pi/></code>. 2061 * <li> Whether to parse "<code>log(x)</code>" with a single 2062 * argument as the base 10 2063 * logarithm of x, the natural logarithm of x, or treat the case as an 2064 * error. 2065 * <li> Whether to parse "<code>number id</code>" by interpreting 2066 * <code>id</code> as the identifier of a unit of measurement associated with the 2067 * number, or whether to treat the case as an error. 2068 * <li> Whether to parse "<code>avogadro</code>" as an {@link ASTNode} of 2069 * type {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or 2070 * as type {@link libsbmlConstants#AST_NAME AST_NAME}. 2071 * <li> Whether to always create explicit ASTNodes of type {@link 2072 * libsbmlConstants#AST_MINUS AST_MINUS} for all unary minuses, or 2073 * collapse and remove minuses where possible. 2074 * 2075 * </ul> <p> 2076 * For more details about the parser, please see the definition of 2077 * {@link L3ParserSettings} and 2078 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 2079 <p> 2080 * @param formula the mathematical formula expression to be parsed 2081 <p> 2082 * @param settings the settings to be used for this parser invocation 2083 <p> 2084 * @return the root node of an AST representing the mathematical formula, 2085 * or <code>null</code> if an error occurred while parsing the formula. When <code>null</code> 2086 * is returned, an error is recorded internally; information about the 2087 * error can be retrieved using 2088 * <code><a href='libsbml.html#getLastParseL3Error()'>libsbml.getLastParseL3Error()</a></code>. 2089 <p> 2090 <p> 2091 <p> 2092 <p> 2093 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 2094 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 2095 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 2096 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 2097 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 2098 */ public 2099 static ASTNode parseL3FormulaWithSettings(String formula, L3ParserSettings settings) { 2100 long cPtr = libsbmlJNI.parseL3FormulaWithSettings(formula, L3ParserSettings.getCPtr(settings), settings); 2101 return (cPtr == 0) ? null : new ASTNode(cPtr, true); 2102 } 2103 2104 2105/** 2106 * Returns a copy of the default parser settings used by <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 2107 <p> 2108 * The settings structure allows callers to change the following parsing 2109 * behaviors: 2110 <p> 2111 * <ul> 2112 * <li> Use a specific {@link Model} object against which identifiers to compare 2113 * identifiers. This causes the parser to search the {@link Model} for identifiers 2114 * that the parser encounters in the formula. If a given symbol in the 2115 * formula matches the identifier of a {@link Species}, {@link Compartment}, {@link Parameter}, 2116 * {@link Reaction}, {@link SpeciesReference} or {@link FunctionDefinition} in the {@link Model}, then the 2117 * symbol is assumed to refer to that model entity instead of any possible 2118 * mathematical terms with the same symbol. For example, if the parser is 2119 * given a {@link Model} containing a {@link Species} with the identifier 2120 * "<code>pi</code>", and the formula to be parsed is 2121 * "<code>3*pi</code>", the MathML produced will contain the 2122 * construct <code><ci> pi </ci></code> instead of the 2123 * construct <code><pi/></code>. 2124 * <li> Whether to parse "<code>log(x)</code>" with a single 2125 * argument as the base 10 2126 * logarithm of x, the natural logarithm of x, or treat the case as an 2127 * error. 2128 * <li> Whether to parse "<code>number id</code>" by interpreting 2129 * <code>id</code> as the identifier of a unit of measurement associated with the 2130 * number, or whether to treat the case as an error. 2131 * <li> Whether to parse "<code>avogadro</code>" as an {@link ASTNode} of 2132 * type {@link libsbmlConstants#AST_NAME_AVOGADRO AST_NAME_AVOGADRO} or 2133 * as type {@link libsbmlConstants#AST_NAME AST_NAME}. 2134 * <li> Whether to always create explicit ASTNodes of type {@link 2135 * libsbmlConstants#AST_MINUS AST_MINUS} for all unary minuses, or 2136 * collapse and remove minuses where possible. 2137 * 2138 * </ul> <p> 2139 * For more details about the parser, please see the definition of 2140 * {@link L3ParserSettings} and 2141 * <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>. 2142 <p> 2143 <p> 2144 <p> 2145 <p> 2146 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 2147 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 2148 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 2149 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 2150 * @see <code><a href='libsbml.html#getLastParseL3Error()'>getLastParseL3Error()</a></code> 2151 */ public 2152 static L3ParserSettings getDefaultL3ParserSettings() { 2153 long cPtr = libsbmlJNI.getDefaultL3ParserSettings(); 2154 return (cPtr == 0) ? null : new L3ParserSettings(cPtr, true); 2155 } 2156 2157 2158/** 2159 * Returns the last error reported by the parser. 2160 <p> 2161 * If <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code>, 2162 * <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, {@link L3ParserSettings} settings)</a></code>, or 2163 * <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>libsbml.parseL3FormulaWithModel(String formula, {@link Model} model)</a></code> return <code>null</code>, an error is set internally which is accessible 2164 * via this function. 2165 <p> 2166 * @return a string describing the error that occurred. This will contain 2167 * the string the parser was trying to parse, which character it had parsed 2168 * when it encountered the error, and a description of the error. 2169 <p> 2170 <p> 2171 <p> 2172 <p> 2173 * @see <code><a href='libsbml.html#formulaToString(org.sbml.libsbml.ASTNode tree)'>libsbml.formulaToString(ASTNode tree)</a></code> 2174 * @see <code><a href='libsbml.html#parseL3FormulaWithSettings(java.lang.String, org.sbml.libsbml.L3ParserSettings)'>libsbml.parseL3FormulaWithSettings(String formula, L3ParserSettings settings)</a></code> 2175 * @see <code><a href='libsbml.html#parseL3Formula(java.lang.String)'>libsbml.parseL3Formula(String formula)</a></code> 2176 * @see <code><a href='libsbml.html#parseL3FormulaWithModel(java.lang.String, org.sbml.libsbml.Model)'>parseL3FormulaWithModel(String formula, Model model)</a></code> 2177 * @see <code><a href='libsbml.html#getDefaultL3ParserSettings()'>getDefaultL3ParserSettings()</a></code> 2178 */ public 2179 static String getLastParseL3Error() { 2180 return libsbmlJNI.getLastParseL3Error(); 2181 } 2182 2183 2184/** 2185 * takes an annotation that has been read into the model 2186 * identifies the RDF elements 2187 * and creates a List of Layouts from the annotation 2188 */ public 2189 static void parseLayoutAnnotation(XMLNode annotation, ListOfLayouts layouts) { 2190 libsbmlJNI.parseLayoutAnnotation(XMLNode.getCPtr(annotation), annotation, ListOfLayouts.getCPtr(layouts), layouts); 2191 } 2192 2193 2194/** 2195 * Takes an {@link XMLNode} and tries to find the layout annotation node and deletes it if it was found. 2196 */ public 2197 static XMLNode deleteLayoutAnnotation(XMLNode pAnnotation) { 2198 long cPtr = libsbmlJNI.deleteLayoutAnnotation(XMLNode.getCPtr(pAnnotation), pAnnotation); 2199 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 2200 } 2201 2202 2203/** 2204 * Creates an {@link XMLNode} that represents the layouts of the model from the given {@link Model} object. 2205 */ public 2206 static XMLNode parseLayouts(Model pModel) { 2207 long cPtr = libsbmlJNI.parseLayouts(Model.getCPtr(pModel), pModel); 2208 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 2209 } 2210 2211 2212/** 2213 * takes an annotation that has been read into the species reference 2214 * identifies the id elements and set the id of the species reference 2215 */ public 2216 static void parseSpeciesReferenceAnnotation(XMLNode annotation, SimpleSpeciesReference sr) { 2217 libsbmlJNI.parseSpeciesReferenceAnnotation(XMLNode.getCPtr(annotation), annotation, SimpleSpeciesReference.getCPtr(sr), sr); 2218 } 2219 2220 2221/** 2222 * Takes an {@link XMLNode} and tries to find the layoutId annotation node and deletes it if it was found. 2223 */ public 2224 static XMLNode deleteLayoutIdAnnotation(XMLNode pAnnotation) { 2225 long cPtr = libsbmlJNI.deleteLayoutIdAnnotation(XMLNode.getCPtr(pAnnotation), pAnnotation); 2226 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 2227 } 2228 2229 2230/** 2231 * Creates an {@link XMLNode} that represents the layoutId annotation of the species reference from the given {@link SpeciesReference} object. 2232 */ public 2233 static XMLNode parseLayoutId(SimpleSpeciesReference sr) { 2234 long cPtr = libsbmlJNI.parseLayoutId(SimpleSpeciesReference.getCPtr(sr), sr); 2235 return (cPtr == 0) ? null : new XMLNode(cPtr, true); 2236 } 2237 2238}