/** @page libsbml-csharp-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 the libSBML C# API.

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

In LibSBML, the class libsbmlcs.SBMLDocument is used 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:
@code{.cs}
namespace LibSBMLCSExample
{
  using System;
  using System.IO;
  using libsbml;

  public class echoSBML
  {
    public static void Main ( string[] args )
    {
      if ( args.Length != 2 )
      {
        string myname = Path.GetFileName(Environment.GetCommandLineArgs()[0]);
        Console.WriteLine("Usage: {0} input-filename output-filename", myname);
        Environment.Exit(1);
      }

      string inputFile  = args[0];
      string outputFile = args[1];

      if ( ! File.Exists(inputFile) )
      {
        Console.WriteLine("[Error] {0} : No such file.", inputFile);
        Environment.Exit(1);        
      }

      SBMLReader   reader  = new SBMLReader();
      SBMLWriter   writer  = new SBMLWriter();
      SBMLDocument sbmlDoc = reader.readSBML(inputFile);

      if ( sbmlDoc.getNumErrors() > 0)
      {
        sbmlDoc.printErrors(); 
        Console.WriteLine("[Error] Cannot read {0}", inputFile);
        Environment.Exit(1);        
      }

      writer.writeSBML(sbmlDoc, outputFile);

      Console.WriteLine("[OK] Echoed {0} to {1}", inputFile, outputFile);
    }
  }

}
@endcode

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 a C# <code>import</code> command to load the libSBML API
into the running C# interpreter.  Next, it instantiates an
libsbmlcs.SBMLReader object and stores it in a variable called
<code>reader</code>.  Then, it uses this object to read an SBML model
stored in a file, creating an libsbmlcs.SBMLDocument object in the process
and storing it in the variable <code>document</code>.  Finally, it calls on
the libsbmlcs.SBMLDocument.getNumErrors() method to check if any errors
were encountered.


@section rf-reading Reading SBML

SBML may be read from a file or an in-memory character string into a
libsbmlcs.SBMLDocument object.  LibSBML defines two basic, convenient,
global functions for reading SBML:

@li <code>libsbmlcs.SBMLDocument libsbmlcs.libsbml.readSBMLFromFile(string filename)</code>.
This function takes a file name, attempts to read an SBML document from the
file, and returns a libsbmlcs.SBMLDocument object if successful.
@li <code>libsbmlcs.SBMLDocument libsbmlcs.libsbml.readSBMLFromString(string
xml)</code>.  This function takes a string assumed to contain XML content,
attempts to read an SBML document from the string, and returns a
libsbmlcs.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 libsbmlcs.SBMLDocument container

As might be deduced from the examples so far, an libsbmlcs.SBMLDocument
object in libSBML represents a whole SBML model and its associated data.
The libsbmlcs.SBMLDocument class corresponds roughly to the class <i>SBML</i>
(respectively, <i>Sbml</i>) defined in the specification for SBML
Level&nbsp;3 (respectively, Level&nbsp;2), 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.)

libsbmlcs.SBMLDocument is derived from libsbmlcs.SBase, so that it contains
the usual libsbmlcs.SBase attributes (in SBML Level&nbsp;2 Version&nbsp;3)
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.  libsbmlcs.SBase (and
thus its subclasses such as libsbmlcs.SBMLDocument) provides methods for
querying this information:

@li <code>int libsbmlcs.SBMLDocument.getLevel()</code> returns the SBML
Level of the model.
@li <code>int libsbmlcs.SBMLDocument.getVersion()</code> 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>libsbmlcs.SBMLDocument.getModel()</code> returns a libsbmlcs.Model
object for the SBML model contained in the libsbmlcs.SBMLDocument.

libsbmlcs.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>int libsbmlcs.SBMLDocument.getNumErrors()</code> returns a count of the
diagnostic messages logged during while attempting to read an SBML model
using either libsbmlcs.libsbml.readSBMLFromFile() or
libsbmlcs.libsbml.readSBMLFromString().
@li <code>libsbmlcs.SBMLError libsbmlcs.SBMLDocument.getError(long n)</code>
returns the error indexed by integer @c n in the error log.  The
libsbmlcs.SBMLError object class provides methods for displaying an error
message, 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>libsbmlcs.SBMLDocument.printErrors()</code> prints to standard
output all of the errors and diagnostics logged with the given
libsbmlcs.SBMLDocument().
@li <code>libsbmlcs.SBMLDocument.printErrors(OStream stream)</code> is
identical to the method above, but prints all of the diagnostics to the
given output stream instead of the terminal.

Finally, another set of libsbmlcs.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 and
Level&nbsp;3 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>int libsbmlcs.SBMLDocument.checkConsistency()</code> performs a
set of structural and mathematical checks on the SBML content and reports
the number of failed checks (errors) encountered.  Use the
libsbmlcs.SBMLDocument.getNumErrors() and
libsbmlcs.SBMLDocument.getError(int n) interfaces to examine the individual
errors.
@li <code>int libsbmlcs.SBMLDocument.checkL1Compatibility()</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 @c 0.
@li <code>int libsbmlcs.SBMLDocument.checkL2v1Compatibility()</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 @c 0.
@li <code>int libsbmlcs.SBMLDocument.checkL2v2Compatibility()</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 @c 0.
@li <code>int libsbmlcs.SBMLDocument.checkL2v3Compatibility()</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 @c 0.
@li <code>int libsbmlcs.SBMLDocument.checkL2v4Compatibility()</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 @c 0.
@li <code>int libsbmlcs.SBMLDocument.checkL3v1Compatibility()</code>
peforms a set of semantic consistency checks on the document to establish
whether it can be converted to SBML Level&nbsp;3 Version&nbsp;1, and
returns the number of failures.  If all the checks succeed, it returns @c 0.

This release of libSBML supports Levels/Versions of SBML up through
Level&nbsp;3 Version&nbsp;2 Core Release&nbsp;1 (RC&nbsp;2).


@section rf-writing Writing SBML

Writing SBML is, in the end, a very simple matter in libsbmlcs.  The library
provides the following methods for this purposes:

@li <code>int libsbmlcs.libsbml.writeSBMLToFile(SBMLDocument d, string filename)</code>
writes the given SBML document to a 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 <code>string libsbmlcs.libsbml.writeSBMLToString(SBMLDocument d)</code> returns
the given SBML document as a character string, or returns an empty string
if a failure occurred.

*/
