/** @page libsbml-reading-files Reading and writing SBML content from your software

This section summarizes how to read and write SBML content using the
facilities provided by libSBML.

@section rf-started Getting started: the 1-minute introduction

LibSBML uses the class SBMLDocument as a top-level container for storing
SBML content and data associated with it (such as warnings and error
messages).  Here is a simple example to start this discussion:
@verbatim
#include <iostream>
#include <sbml/SBMLTypes.h>

using namespace std;

int
main (int argc, char* argv[])
{
  SBMLDocument* document = readSBML(argv[1]);

  unsigned int errors = document->getNumErrors();

  cout << endl;
  cout << "  filename: " << argv[1] << endl;
  cout << "  error(s): " << errors  << endl;
  cout << endl;

  if (errors > 0) document->printErrors(cerr);

  return errors;
}
@endverbatim
The code above illustrates probably the simplest possible use of libSBML:
reading a model and printing any errors or warnings encountered.  The code
begins with the inclusion of a single SBML header file, SBMLTypes.h, which
serves to include most of the other useful libSBML individual header files.
Next, in the body of the main function, the line
@verbatim
SBMLDocument* document = readSBML(argv[1]);
@endverbatim
reads in a file and returns a pointer to an SBMLDocument object.  A
subsequent call to the method @link SBMLDocument::getNumErrors()
getNumErrors() @endlink on that object returns the number of errors
encountered (if any), and a call to @link SBMLDocument::printErrors()
printErrors() @endlink method prints the errors (if any) to the C++
standard error output stream.


@section rf-reading Reading SBML

SBML may be read from a file or an in-memory character string into an
SBMLDocument.  LibSBML defines two basic, convenient, global functions (not
methods on a specific object class, but global functions in the classic C
programming sense) for reading SBML:

@li <code>SBMLDocument* readSBML(const char* filename)</code>.  This
function takes a file name, attempts to read an SBML document from the
file, and returns a pointer to an SBMLDocument object if successful.

@li <code>SBMLDocument* readSBMLFromString(const char* xml)</code>.  This
function takes a string, attempts to read an SBML document from the string,
and returns a pointer to an SBMLDocument object if successful.

The model may be either in SBML Level&nbsp;1 or SBML Level&nbsp;2 format.
LibSBML implements an unified object model for SBML that encompasses both
Level&nbsp;1 and Level&nbsp;2, so applications generally do not need to
worry about differences in syntax between these definitions of SBML when
reading and writing models.  (However, applications still need to be
concerned about the @em constructs used and how they are interpreted, since
there are substantial differences between SBML Level&nbsp;1 and
Level&nbsp;2!)


@section rf-sbmldocument The SBMLDocument container

As might be deduced from the examples so far, an SBMLDocument object in
libSBML represents a whole SBML model and its associated data.
SBMLDocument corresponds roughly to the class <i>Sbml</i> defined in the
SBML Level&nbsp;2 specification, but it does not have a direct
correspondence in SBML Level&nbsp;1.  (But, it is created by libSBML no
matter whether the model is Level&nbsp;1 or Level&nbsp;2.)

SBMLDocument is derived from SBase, so that it contains the usual SBase
attributes (in SBML Level&nbsp;2 Version&nbsp;4) of "metaid" and "sboTerm",
as well as the subelements "notes" and "annotation".  It also contains the
attributes "level" and "version" indicating the Level and Version of the
SBML read.  SBase (and thus its subclasses such as SBMLDocument) provides
methods for querying this information:

@li <code>unsigned int @link SBMLDocument::getLevel()
getLevel()@endlink</code> on an SBMLDocument object returns the SBML Level
of the model.

@li <code>unsigned int @link SBMLDocument::getVersion()
getVersion()@endlink</code> on an SBMLDocument object returns the SBML
Version within the Level of the model.

Of course, the whole point of reading an SBML file or data stream is to get
at the SBML model it contains.  The following method allows access to the
Model object within an SBML document:

@li <code>Model* @link SBMLDocument::getModel() getModel()@endlink</code>
on an SBMLDocument object returns a Model object representing the SBML
model contained within that SBMLDocument object.

SBMLDocument also acts to log any problems encountered while reading the
model from the file or data stream.  Whether the problems are warnings or
errors, they are reported through a single common interface involving the
object class SBMLError.  The example earlier on this page already showed
some of the methods available for accessing errors and warnings; here is a
slightly more complete list:

@li <code>unsigned int @link SBMLDocument::getNumErrors()
getNumErrors()@endlink</code> on an SBMLDocument object returns a count of
the diagnostic messages logged while attempting to read an SBML model using
either readSBML(const char *filename) or readFromString(const char *xml).

@li <code>const SBMLError* @link SBMLDocument::getError()
getError(unsigned int n)@endlink</code> returns a specific error
indexed by the integer @c n.  (Callers should first use <code>@link
SBMLDocument::getNumErrors() getNumErrors()@endlink</code> to get the
number of errors, so that they can know the range of valid index numbers.)
The SBMLError object class provides methods for assessing the severity of
the problem encountered and for finding out the line and column number of
where the problem occurred in the SBML input.

@li <code>void @link SBMLDocument::printErrors()
printErrors(std::ostream& stream = std::cerr)@endlink</code> on
an SBMLDocument object prints all of the diagnostics to the given output
stream, defaulting to the standard error stream if no stream argument is
given in the call.

Finally, another set of SBMLDocument methods worth mentioning in the
context of reading SBML are those for running consistency-checking and
validation rules on the SBML content.  These methods assess whether the
SBML is legal according to basic rules listed in the SBML Level&nbsp;2
Versions&nbsp;2 through&nbsp;4 specification documents.  Note that they are
mostly structural checks, in the sense that they can indicate whether the
SBML is properly constructed; they cannot tell if a model is nonsense.
(But at least they can assess whether it's syntactically correct
nonsense!).

@li <code>unsigned int @link SBMLDocument::checkConsistency()
checkConsistency()@endlink</code>, invoked on an SBMLDocument object,
performs a set of structural and mathematical checks on the SBML content
and reports the number of failed checks (errors) encountered.  Callers may
use <code>@link SBMLDocument::getNumErrors() getNumErrors()@endlink</code>
and <code>@link SBMLDocument::getError() getError(unsigned
int n)@endlink</code> interfaces to examine the individual errors.

@li <code>unsigned int @link SBMLDocument::checkL1Compatibility()
checkL1Compatibility()@endlink</code> peforms a set of semantic consistency
checks on the document to establish whether it can be converted to SBML
Level&nbsp;1, and returns the number of failures.  If all the checks
succeed, it returns 0.

@li <code>unsigned int @link SBMLDocument::checkL2v1Compatibility()
checkL2v1Compatibility()@endlink</code> peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;2 Version 1, and returns the number of failures.  If all
the checks succeed, it returns 0.

@li <code>unsigned int @link SBMLDocument::checkL2v2Compatibility()
checkL2v2Compatibility()@endlink</code> peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;2 Version&nbsp;2, and returns the number of failures.
If all the checks succeed, it returns 0.

@li <code>unsigned int @link SBMLDocument::checkL2v3Compatibility()
checkL2v3Compatibility()@endlink</code> peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;2 Version&nbsp;3, and returns the number of failures.
If all the checks succeed, it returns 0.

@li <code>unsigned int @link SBMLDocument::checkL2v4Compatibility()
checkL2v4Compatibility()@endlink</code> peforms a set of semantic
consistency checks on the document to establish whether it can be converted
to SBML Level&nbsp;2 Version&nbsp;4, and returns the number of failures.
If all the checks succeed, it returns 0.

At the time of this release of libSBML, the most recent release of SBML is
Level&nbsp;2 Version&nbsp;4.


@section rf-writing Writing SBML

Writing SBML is, in the end, a very simple matter in libSBML.  The library
provides the following two global functions for this purposes:

@li @link writeSBML(const SBMLDocument_t *d, const char *filename) 
<code>int writeSBML(const SBMLDocument* d, const char* filename)</code>@endlink
writes the given SBML document to the named file and returns either @c 1 on
success or @c 0 on failure.  Reasons for failure can be, for example, that
the named file could not be opened for writing.

@li @link writeSBMLToString(const SBMLDocument_t *d)
<code>char * writeSBMLToString(const SBMLDocument *d)</code>@endlink writes
the given SBML document to a character string and returns a pointer to it, or
returns @c 0 if a failure occurred.  The string is owned by the caller and
should be freed (using the standard C function <code>free()</code>)
after it is no longer needed.



*/