Detailed Description

Interface to an XML output stream.

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.

SBML content is serialized using XML; the resulting data can be stored and read to/from a file or data stream. Low-level XML parsers such as Xerces provide facilities to read XML data. To permit the use of different XML parsers (Xerces, Expat or libxml2), libSBML implements an abstraction layer. XMLInputStream_t and XMLOutputStream_t are two parts of that abstraction layer.

XMLOutputStream_t provides a wrapper above output streams to facilitate writing XML. XMLOutputStream_t keeps track of start and end elements, indentation, XML namespace prefixes, and more. The interface provides features for converting non-text data types into appropriate textual form; this takes the form of overloaded writeAttribute(...) methods that allow users to simply use the same method with any data type. For example, suppose an element testElement has two attributes, size and id, and the attributes are variables in your code as follows: Then, the element and the attributes can be written to the standard output stream (provided as cout in the libSBML language bindings) as follows:

Other classes in SBML take XMLOutputStream_t objects as arguments, and use that to write elements and attributes seamlessly to the XML output stream.

It is also worth noting that unlike XMLInputStream_t, XMLOutputStream_t is actually independent of the underlying XML parsers. It does not use the XML parser libraries at all.

Note: The convenience of the XMLInputStream_t and XMLOutputStream_t abstraction may be useful for developers interested in creating parsers for other XML formats besides SBML. It can provide developers with a layer above more basic XML parsers, as well as some useful programmatic elements such as XMLToken_t, XMLError_t, etc.

See also: XMLInputStream_t

Public Member Functions
LIBLAX_EXTERN XMLOutputStream_t *	XMLOutputStream_createAsStdout (const char *encoding, int writeXMLDecl)
	Creates a new XMLOutputStream_t that wraps std output stream. More...

LIBLAX_EXTERN XMLOutputStream_t *	XMLOutputStream_createAsStdoutWithProgramInfo (const char encoding, int writeXMLDecl, const char programName, const char *programVersion)
	Creates a new XMLOutputStream_t instance for use as a standard output stream (stdout). More...

LIBLAX_EXTERN XMLOutputStream_t *	XMLOutputStream_createAsString (const char *encoding, int writeXMLDecl)
	Creates a new XMLOutputStream_t instance for use as a string. More...

LIBLAX_EXTERN XMLOutputStream_t *	XMLOutputStream_createAsStringWithProgramInfo (const char encoding, int writeXMLDecl, const char programName, const char *programVersion)
	Creates a new XMLOutputStream_t that wraps std string output stream and adds program information as a comment. More...

LIBLAX_EXTERN XMLOutputStream_t *	XMLOutputStream_createFile (const char filename, const char encoding, int writeXMLDecl)
	Creates a new XMLOutputStream_t that wraps std file output stream. More...

LIBLAX_EXTERN XMLOutputStream_t *	XMLOutputStream_createFileWithProgramInfo (const char filename, const char encoding, int writeXMLDecl, const char programName, const char programVersion)
	Creates a new XMLOutputStream_t that wraps std file output stream and adds program information as a comment. More...

LIBLAX_EXTERN void	XMLOutputStream_downIndent (XMLOutputStream_t *stream)
	Decreases the indentation level for this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_endElement (XMLOutputStream_t stream, const char name)
	Writes the given XML end element name to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_endElementTriple (XMLOutputStream_t stream, const XMLTriple_t triple)
	Writes the given XML end element 'prefix:name' to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_free (XMLOutputStream_t *stream)
	Deletes this XMLOutputStream_t. More...

LIBLAX_EXTERN const char *	XMLOutputStream_getString (XMLOutputStream_t *stream)
	Returns the given string associated to the underlying string stream. More...

LIBLAX_EXTERN void	XMLOutputStream_setAutoIndent (XMLOutputStream_t *stream, int indent)
	Turns automatic indentation on or off for this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_startElement (XMLOutputStream_t stream, const char name)
	Writes the given XML start element name to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_startElementTriple (XMLOutputStream_t stream, const XMLTriple_t triple)
	Writes the given XML start element 'prefix:name' to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_startEndElement (XMLOutputStream_t stream, const char name)
	Writes the given XML start and end element name to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_startEndElementTriple (XMLOutputStream_t stream, const XMLTriple_t triple)
	Writes the given XML start and end element 'prefix:name' to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_upIndent (XMLOutputStream_t *stream)
	Increases the indentation level for this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeBool (XMLOutputStream_t stream, const char name, const int flag)
	Writes the given attribute, name="true" or name="false" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeBoolTriple (XMLOutputStream_t stream, const XMLTriple_t triple, const int flag)
	Writes the given attribute, prefix:name="true" or prefix:name="false" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeChars (XMLOutputStream_t stream, const char name, const char *chars)
	Writes the given attribute, name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeCharsTriple (XMLOutputStream_t stream, const XMLTriple_t triple, const char *chars)
	Writes the given attribute, prefix:name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeDouble (XMLOutputStream_t stream, const char name, const double value)
	Writes the given attribute, name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeDoubleTriple (XMLOutputStream_t stream, const XMLTriple_t triple, const double value)
	Writes the given attribute, prefix:name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeInt (XMLOutputStream_t stream, const char name, const int value)
	Writes the given attribute, name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeIntTriple (XMLOutputStream_t stream, const XMLTriple_t triple, const int value)
	Writes the given attribute, prefix:name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeLong (XMLOutputStream_t stream, const char name, const long value)
	Writes the given attribute, name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeLongTriple (XMLOutputStream_t stream, const XMLTriple_t triple, const long value)
	Writes the given attribute, prefix:name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeUInt (XMLOutputStream_t stream, const char name, const unsigned int value)
	Writes the given attribute, name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeAttributeUIntTriple (XMLOutputStream_t stream, const XMLTriple_t triple, const unsigned int value)
	Writes the given attribute, prefix:name="value" to this XMLOutputStream_t. More...

LIBLAX_EXTERN void	XMLOutputStream_writeChars (XMLOutputStream_t stream, const char chars)
	Outputs the given characters to the underlying stream. More...

LIBLAX_EXTERN void	XMLOutputStream_writeDouble (XMLOutputStream_t *stream, const double value)
	Outputs the given double to the underlying stream. More...

LIBLAX_EXTERN void	XMLOutputStream_writeLong (XMLOutputStream_t *stream, const long value)
	Outputs the given long to the underlying stream. More...

LIBLAX_EXTERN void	XMLOutputStream_writeXMLDecl (XMLOutputStream_t *stream)
	Writes the XML declaration: <?xml version="1.0" encoding="..."?> More...

Member Function Documentation

LIBLAX_EXTERN XMLOutputStream_t * XMLOutputStream_createAsStdout	(	const char *	encoding,
		int	writeXMLDecl
	)

Creates a new XMLOutputStream_t that wraps std output stream.

LIBLAX_EXTERN XMLOutputStream_t * XMLOutputStream_createAsStdoutWithProgramInfo	(	const char *	encoding,
		int	writeXMLDecl,
		const char *	programName,
		const char *	programVersion
	)

Creates a new XMLOutputStream_t instance for use as a standard output stream (stdout).

The functionality associated with the programName and programVersion arguments concerns an optional comment that libSBML can write at the beginning of the output stream. The comment is intended for human readers of the XML file, and has the following form:

<!-- Created by <program name> version <program version>
on yyyy-MM-dd HH:mm with libSBML version <libsbml version>. -->

This program information comment is a separate item from the XML declaration that this method can also write to this output stream. The comment is also not mandated by any SBML specification. This libSBML functionality is provided for the convenience of calling programs, and to help humans trace the origin of SBML files.

The XML declaration has the form

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

Note that the SBML specifications require the use of UTF-8 encoding and version 1.0, so for SBML documents, the above is the standard XML declaration.

Parameters

encoding	the XML encoding to declare in the output. This value should be `"UTF-8"` for SBML documents. The default value is `"UTF-8"` if no value is supplied for this parameter.
writeXMLDecl	whether to write a standard XML declaration at the beginning of the content written on `stream`. The default is `true`.
programName	an optional program name to write as a comment in the output stream.
programVersion	an optional version identification string to write as a comment in the output stream.

LIBLAX_EXTERN XMLOutputStream_t * XMLOutputStream_createAsString	(	const char *	encoding,
		int	writeXMLDecl
	)

Creates a new XMLOutputStream_t instance for use as a string.

LIBLAX_EXTERN XMLOutputStream_t * XMLOutputStream_createAsStringWithProgramInfo	(	const char *	encoding,
		int	writeXMLDecl,
		const char *	programName,
		const char *	programVersion
	)

Creates a new XMLOutputStream_t that wraps std string output stream and adds program information as a comment.

LIBLAX_EXTERN XMLOutputStream_t * XMLOutputStream_createFile	(	const char *	filename,
		const char *	encoding,
		int	writeXMLDecl
	)

Creates a new XMLOutputStream_t that wraps std file output stream.

LIBLAX_EXTERN XMLOutputStream_t * XMLOutputStream_createFileWithProgramInfo	(	const char *	filename,
		const char *	encoding,
		int	writeXMLDecl,
		const char *	programName,
		const char *	programVersion
	)

Creates a new XMLOutputStream_t that wraps std file output stream and adds program information as a comment.

LIBLAX_EXTERN void XMLOutputStream_downIndent ( XMLOutputStream_t * stream )

Decreases the indentation level for this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_endElement	(	XMLOutputStream_t *	stream,
		const char *	name
	)

Writes the given XML end element name to this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_endElementTriple	(	XMLOutputStream_t *	stream,
		const XMLTriple_t *	triple
	)

Writes the given XML end element 'prefix:name' to this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_free ( XMLOutputStream_t * stream )

Deletes this XMLOutputStream_t.

LIBLAX_EXTERN const char * XMLOutputStream_getString ( XMLOutputStream_t * stream )

Returns the given string associated to the underlying string stream.

LIBLAX_EXTERN void XMLOutputStream_setAutoIndent	(	XMLOutputStream_t *	stream,
		int	indent
	)

Turns automatic indentation on or off for this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_startElement	(	XMLOutputStream_t *	stream,
		const char *	name
	)

Writes the given XML start element name to this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_startElementTriple	(	XMLOutputStream_t *	stream,
		const XMLTriple_t *	triple
	)

Writes the given XML start element 'prefix:name' to this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_startEndElement	(	XMLOutputStream_t *	stream,
		const char *	name
	)

Writes the given XML start and end element name to this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_startEndElementTriple	(	XMLOutputStream_t *	stream,
		const XMLTriple_t *	triple
	)

Writes the given XML start and end element 'prefix:name' to this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_upIndent ( XMLOutputStream_t * stream )

Increases the indentation level for this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_writeAttributeBool	(	XMLOutputStream_t *	stream,
		const char *	name,
		const int	flag
	)

Writes the given attribute, name="true" or name="false" to this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_writeAttributeBoolTriple	(	XMLOutputStream_t *	stream,
		const XMLTriple_t *	triple,
		const int	flag
	)

Writes the given attribute, prefix:name="true" or prefix:name="false" to this XMLOutputStream_t.

LIBLAX_EXTERN void XMLOutputStream_writeAttributeChars	(	XMLOutputStream_t *	stream,
		const char *	name,
		const char *	chars
	)