SBMLReader.h File Reference

Reads an SBML Document into memory. More...

Include dependency graph for SBMLReader.h:

This graph shows which files directly or indirectly include this file:

Classes
class	SBMLReader
	File and text-string SBML reader. More...

Functions
SBMLDocument_t *	readSBML (const char *filename)
	Reads an SBML document from the given file. More...
SBMLDocument_t *	readSBMLFromFile (const char *filename)
	Reads an SBML document from the given file. More...
SBMLDocument_t *	readSBMLFromString (const char *xml)
	Reads an SBML document from a text string. More...

Detailed Description

Reads an SBML Document into memory.

Author

Ben Bornstein

Function Documentation

SBMLDocument_t* readSBML

(

const char *

filename

)

Reads an SBML document from the given file.

If the file named filename does not exist or its content is not valid SBML, one or more errors will be logged with the SBMLDocument object returned by this method. Callers can use the methods on SBMLDocument such as , SBMLDocument::getNumErrors() and SBMLDocument::getError() to get the errors. The object returned by SBMLDocument::getError() is an SBMLError object, and it has methods to get the error code, category, and severity level of the problem, as well as a textual description of the problem. The possible severity levels range from informational messages to fatal errors; see the documentation for SBMLError for more information.

If the file filename could not be read, the file-reading error will appear first. The error code (a value drawn from the enumeration XMLErrorCode_t) can provide a clue about what happened. For example, a file might be unreadable (either because it does not actually exist or because the user does not have the necessary access privileges to read it) or some sort of file operation error may have been reported by the underlying operating system. Callers can check for these situations using a program fragment such as the following:

SBMLReader reader;
SBMLDocument* doc  = reader.readSBMLFromFile(filename);

if (doc->getNumErrors() > 0)
{
  if (doc->getError(0)->getErrorId() == XMLError::XMLFileUnreadable)
  {
    // Handle case of unreadable file here.
  }
  else if (doc->getError(0)->getErrorId() == XMLError::XMLFileOperationError)
  {
    // Handle case of other file operation error here.
  }
  else
  {
    // Handle other cases -- see error codes defined in XMLErrorCode_t
    // for other possible cases to check.
  }
}

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), the file is assumed to be compressed in gzip format and will be automatically decompressed upon reading. Similarly, if the given filename ends with ".zip" or ".bz2", the file is assumed to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be read uncompressed. Note that if the file is in zip format but the archive contains more than one file, only the first file in the archive will be read and the rest ignored.

To read a gzip/zip file, libSBML needs to be configured and linked with the zlib library at compile time. It also needs to be linked with the bzip2 library to read files in bzip2 format. (Both of these are the default configurations for libSBML.) Errors about unreadable files will be logged if a compressed filename is given and libSBML was not linked with the corresponding required library.

Examples:

addCustomValidator.cpp, addCVTerms.cpp, addingEvidenceCodes_1.cpp, addingEvidenceCodes_2.cpp, addLayout.cpp, addModelHistory.cpp, appendAnnotation.cpp, callExternalValidator.cpp, convertCobraToFbc.cpp, convertFbcToCobra.cpp, convertSBML.cpp, echoSBML.cpp, flattenModel.cpp, inlineFunctionDefintions.cpp, printMath.cpp, printSBML.cpp, printUnits.cpp, promoteParameters.cpp, rngvalidator.cpp, and stripPackage.cpp.

SBMLDocument_t* readSBMLFromFile

(

const char *

filename

)

Reads an SBML document from the given file.

If the file named filename does not exist or its content is not valid SBML, one or more errors will be logged with the SBMLDocument object returned by this method. Callers can use the methods on SBMLDocument such as , SBMLDocument::getNumErrors() and SBMLDocument::getError() to get the errors. The object returned by SBMLDocument::getError() is an SBMLError object, and it has methods to get the error code, category, and severity level of the problem, as well as a textual description of the problem. The possible severity levels range from informational messages to fatal errors; see the documentation for SBMLError for more information.

If the file filename could not be read, the file-reading error will appear first. The error code (a value drawn from the enumeration XMLErrorCode_t) can provide a clue about what happened. For example, a file might be unreadable (either because it does not actually exist or because the user does not have the necessary access privileges to read it) or some sort of file operation error may have been reported by the underlying operating system. Callers can check for these situations using a program fragment such as the following:

SBMLReader reader;
SBMLDocument* doc  = reader.readSBMLFromFile(filename);

if (doc->getNumErrors() > 0)
{
  if (doc->getError(0)->getErrorId() == XMLError::XMLFileUnreadable)
  {
    // Handle case of unreadable file here.
  }
  else if (doc->getError(0)->getErrorId() == XMLError::XMLFileOperationError)
  {
    // Handle case of other file operation error here.
  }
  else
  {
    // Handle other cases -- see error codes defined in XMLErrorCode_t
    // for other possible cases to check.
  }
}

If the given filename ends with the suffix ".gz" (for example, "myfile.xml.gz"), the file is assumed to be compressed in gzip format and will be automatically decompressed upon reading. Similarly, if the given filename ends with ".zip" or ".bz2", the file is assumed to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be read uncompressed. Note that if the file is in zip format but the archive contains more than one file, only the first file in the archive will be read and the rest ignored.

To read a gzip/zip file, libSBML needs to be configured and linked with the zlib library at compile time. It also needs to be linked with the bzip2 library to read files in bzip2 format. (Both of these are the default configurations for libSBML.) Errors about unreadable files will be logged if a compressed filename is given and libSBML was not linked with the corresponding required library.

Parameters

filename

the name or full pathname of the file to be read.

Returns

a pointer to the SBMLDocument structure created from the SBML content in filename.

Examples:

convertLayout.cpp, spec_example1.cpp, spec_example2.cpp, spec_example3.cpp, spec_example4.cpp, and translateL3Math.cpp.

SBMLDocument_t* readSBMLFromString

(

const char *

xml

)

Reads an SBML document from a text string.

This method is flexible with respect to the presence of an XML declaration at the beginning of the string. In particular, if the string in xml does not begin with the XML declaration

<?xml version='1.0' encoding='UTF-8'?>

then this method will automatically prepend the declaration to xml.

This method will log a fatal error if the content given in the parameter xml is not in SBML format. See the method documentation for SBMLReader::readSBML() for an example of code for testing the returned error code.

Parameters

xml	a string containing a full SBML model.

Returns

a pointer to the SBMLDocument structure created from the SBML content in xml.

Note

When using this method to read an SBMLDocument that uses the SBML Level 3 Hierarchical Model Composition package (comp) the document location cannot be set automatically. Thus, if the model contains references to ExternalModelDefinition objects, it will be necessary to manually set the document URI location (SBMLDocument::setLocationURI() ) in order to facilitate resolving these models.

Examples:

SBMLHttpResolverExample.cpp.