Detailed Description

File and text-string SBML reader.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The SBMLReader_t class provides the main interface for reading SBML content from files and strings. The methods for reading SBML all return an SBMLDocument_t object representing the results. In the case of failures (such as if the SBML contains errors or a file cannot be read), the errors will be recorded with the SBMLErrorLog_t object kept in the SBMLDocument_t returned by SBMLReader_t. Consequently, immediately after calling a method on SBMLReader_t, callers should always check for errors and warnings using the methods for this purpose provided by SBMLDocument_t.

For convenience as well as easy access from other languages besides C++, this file also defines two global functions, readSBML() and readSBMLFromString(). They are equivalent to creating an SBMLReader_t object and then calling the and methods, respectively.

Support for reading compressed files

LibSBML provides support for reading (as well as writing) compressed SBML files. The process is transparent to the calling application—the application does not need to do anything deliberate to invoke the functionality. If a given SBML filename ends with an extension for the gzip, zip or bzip2 compression formats (respectively, .gz, .zip, or .bz2), then the methods and

will automatically decompress and compress the file while reading and writing it. If the filename has no such extension, it will be read and written uncompressed as normal.

The compression feature requires that the zlib (for gzip and zip formats) and/or bzip2 (for bzip2 format) be available on the system running libSBML, and that libSBML was configured with their support compiled-in. Please see the libSBML installation instructions for more information about this. The methods hasZlib() and hasBzip2() can be used by an application to query at run-time whether support for the compression libraries is available in the present copy of libSBML.

Support for compression is not mandated by the SBML standard, but applications may find it helpful, particularly when large SBML models are being communicated across data links of limited bandwidth.

Public Member 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...

SBMLReader_t *	SBMLReader_create (void)
	Creates a new SBMLReader_t and returns it. More...

void	SBMLReader_free (SBMLReader_t *sr)
	Frees the given SBMLReader_t. More...

int	SBMLReader_hasBzip2 ()
	Returns `1` (true) if the underlying libSBML supports bzip2 format compression. More...

int	SBMLReader_hasZlib ()
	Returns `1` (true) if the underlying libSBML supports gzip and zlib format compression. More...

SBMLDocument_t *	SBMLReader_readSBML (SBMLReader_t sr, const char filename)
	Reads an SBML document from the given file. More...

SBMLDocument_t *	SBMLReader_readSBMLFromFile (SBMLReader_t sr, const char filename)
	Reads an SBML document from the given file. More...

SBMLDocument_t *	SBMLReader_readSBMLFromString (SBMLReader_t sr, const char xml)
	Reads an SBML document from a text string. More...

Member 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_t object returned by this method. Callers can use the methods on SBMLDocument_t such as , SBMLDocument_getNumErrors() and SBMLDocument_getError() to get the errors. The object returned by SBMLDocument_getError() is an SBMLError_t 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_t 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_t   *sr;
SBMLDocument_t *d;
sr = SBMLReader_create();
d = SBMLReader_readSBML(sr, filename);
if (SBMLDocument_getNumErrors(d) > 0)
{
  if (XMLError_getId(SBMLDocument_getError(d, 0))
      == SBML_READ_ERROR_FILE_NOT_FOUND)
  {
     ...
  }
  if (XMLError_getId(SBMLDocument_getError(d, 0))
      == SBML_READ_ERROR_NOT_SBML)
  {
     ...
  }
}

: 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:: addCVTerms.c, addingEvidenceCodes_1.c, addingEvidenceCodes_2.c, addModelHistory.c, appendAnnotation.c, convertSBML.c, echoSBML.c, flattenModel.c, printAnnotation.c, printMath.c, printNotes.c, printSBML.c, printUnits.c, promoteParameters.c, readSBML.c, stripPackage.c, unsetAnnotation.c, unsetNotes.c, and validateSBML.c.

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_t object returned by this method. Callers can use the methods on SBMLDocument_t such as , SBMLDocument_getNumErrors() and SBMLDocument_getError() to get the errors. The object returned by SBMLDocument_getError() is an SBMLError_t 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_t 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_t   *sr;
SBMLDocument_t *d;
sr = SBMLReader_create();
d = SBMLReader_readSBML(sr, filename);
if (SBMLDocument_getNumErrors(d) > 0)
{
  if (XMLError_getId(SBMLDocument_getError(d, 0))
      == SBML_READ_ERROR_FILE_NOT_FOUND)
  {
     ...
  }
  if (XMLError_getId(SBMLDocument_getError(d, 0))
      == SBML_READ_ERROR_NOT_SBML)
  {
     ...
  }
}

: 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_t structure created from the SBML content in filename.

Examples:: translateL3Math.c.

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_t structure created from the SBML content in xml.

Note: When using this method to read an SBMLDocument_t 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_t objects, it will be necessary to manually set the document URI location (SBMLDocument_setLocationURI() ) in order to facilitate resolving these models.

SBMLReader_t * SBMLReader_create ( void )

Creates a new SBMLReader_t and returns it.

By default, XML Schema validation is off.

void SBMLReader_free ( SBMLReader_t * sr )

Frees the given SBMLReader_t.

int SBMLReader_hasBzip2 ( )

Returns 1 (true) if the underlying libSBML supports bzip2 format compression.

This predicate tests whether the underlying copy of the libSBML library has been linked with the necessary libraries to support bzip2 compression.

Returns: 1 (true) if libSBML is linked with bzip2, 0 (false) otherwise.

int SBMLReader_hasZlib ( )

Returns 1 (true) if the underlying libSBML supports gzip and zlib format compression.

This predicate tests whether the underlying copy of the libSBML library has been linked with the necessary libraries to support zlib compression.

Returns: 1 (true) if libSBML is linked with zlib, 0 (false) otherwise.

SBMLDocument_t * SBMLReader_readSBML	(	SBMLReader_t *	sr,
		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_t object returned by this method. Callers can use the methods on SBMLDocument_t such as , SBMLDocument_getNumErrors() and SBMLDocument_getError() to get the errors. The object returned by SBMLDocument_getError() is an SBMLError_t 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_t 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_t   *sr;
SBMLDocument_t *d;
sr = SBMLReader_create();
d = SBMLReader_readSBML(sr, filename);
if (SBMLDocument_getNumErrors(d) > 0)
{
  if (XMLError_getId(SBMLDocument_getError(d, 0))
      == SBML_READ_ERROR_FILE_NOT_FOUND)
  {
     ...
  }
  if (XMLError_getId(SBMLDocument_getError(d, 0))
      == SBML_READ_ERROR_NOT_SBML)
  {
     ...
  }
}

: 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.

This function is identical to SBMLReader_readSBMLFromFile().

Parameters

sr	the SBMLReader_t structure to use.
filename	a string giving the path to a file where the XML content is to be found.

Returns: a pointer to the SBMLDocument_t structure created from the SBML content read from filename.

Note: LibSBML versions 2.x and later versions behave differently in error handling in several respects. One difference is how early some errors are caught and whether libSBML continues processing a file in the face of some early errors. In general, libSBML versions after 2.x stop parsing SBML inputs sooner than libSBML version 2.x in the face of XML errors, because the errors may invalidate any further SBML content. For example, a missing XML declaration at the beginning of the file was ignored by libSBML 2.x but in version 3.x and later, it will cause libSBML to stop parsing the rest of the input altogether. While this behavior may seem more severe and intolerant, it was necessary in order to provide uniform behavior regardless of which underlying XML parser (Expat, Xerces, libxml2) is being used by libSBML. The XML parsers themselves behave differently in their error reporting, and sometimes libSBML has to resort to the lowest common denominator.

SBMLDocument_t * SBMLReader_readSBMLFromFile	(	SBMLReader_t *	sr,
		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_t object returned by this method. Callers can use the methods on SBMLDocument_t such as , SBMLDocument_getNumErrors() and SBMLDocument_getError() to get the errors. The object returned by SBMLDocument_getError() is an SBMLError_t 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_t 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_t   *sr;
SBMLDocument_t *d;
sr = SBMLReader_create();
d = SBMLReader_readSBML(sr, filename);
if (SBMLDocument_getNumErrors(d) > 0)
{
  if (XMLError_getId(SBMLDocument_getError(d, 0))
      == SBML_READ_ERROR_FILE_NOT_FOUND)
  {
     ...
  }
  if (XMLError_getId(SBMLDocument_getError(d, 0))
      == SBML_READ_ERROR_NOT_SBML)
  {
     ...
  }
}

: 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.

This function is identical to SBMLReader_readSBML().

Parameters

sr	the SBMLReader_t structure to use.
filename	a string giving the path to a file where the XML content is to be found.

Returns: a pointer to the SBMLDocument_t structure created from the SBML content read from filename.

Note: LibSBML versions 2.x and later versions behave differently in error handling in several respects. One difference is how early some errors are caught and whether libSBML continues processing a file in the face of some early errors. In general, libSBML versions after 2.x stop parsing SBML inputs sooner than libSBML version 2.x in the face of XML errors, because the errors may invalidate any further SBML content. For example, a missing XML declaration at the beginning of the file was ignored by libSBML 2.x but in version 3.x and later, it will cause libSBML to stop parsing the rest of the input altogether. While this behavior may seem more severe and intolerant, it was necessary in order to provide uniform behavior regardless of which underlying XML parser (Expat, Xerces, libxml2) is being used by libSBML. The XML parsers themselves behave differently in their error reporting, and sometimes libSBML has to resort to the lowest common denominator.

SBMLDocument_t * SBMLReader_readSBMLFromString	(	SBMLReader_t *	sr,
		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

sr	the SBMLReader_t structure to use.
xml	the input xml string.

Returns: a pointer to the SBMLDocument_t read.

Note: When using this method to read an SBMLDocument_t 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_t objects, it will be necessary to manually set the document URI location (SBMLDocument_setLocationURI() ) in order to facilitate resolving these models.

Detailed Description

Support for reading compressed files

Public Member Functions

Member Function Documentation