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 and XMLOutputStream are two parts of that abstraction layer.

XMLOutputStream provides a wrapper above output streams to facilitate writing XML. XMLOutputStream 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:

double size = 3.2;

std::string id = "id";

Then, the element and the attributes can be written to the standard output stream as follows:

double size = 3.2;
std::string id = "id";
// Create an XMLOutputStream object that will write to the
// standard output stream:
XMLOutputStream xos = new XMLOutputStream(cout);
// Create the start element, write the attributes, and close
// the element.  The output will be written immediately as
// each method is called.
xos.startElement("testElement")
xos.writeAttribute("size", size)
xos.writeAttribute("id", id)
xos.endElement("testElement")

Other classes in SBML take XMLOutputStream 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, XMLOutputStream is actually independent of the underlying XML parsers. It does not use the XML parser libraries at all.

Note: The convenience of the XMLInputStream and XMLOutputStream 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, XMLError, etc.

See also: XMLInputStream

Public Member Functions
void	downIndent ()
	Decreases the indentation level for this XMLOutputStream. More...

void	endElement (const std::string &name, const std::string prefix="")
	Writes the given XML end element name to this XMLOutputStream. More...

void	endElement (const XMLTriple &triple, bool text=false)
	Writes the given element to the stream. More...

SBMLNamespaces *	getSBMLNamespaces ()
	Returns the SBMLNamespaces object attached to this output stream. More...

XMLOutputStream &	operator<< (const std::string &chars)
	Writes the given characters to the underlying stream. More...

XMLOutputStream &	operator<< (const double &value)
	Writes the given double-type number to the underlying stream. More...

XMLOutputStream &	operator<< (const long &value)
	Outputs the given long-type number to the underlying stream. More...

XMLOutputStream &	operator<< (const char &c)
	Outputs a single character to the underlying stream. More...

void	setAutoIndent (bool indent)
	Turns automatic indentation on or off for this XMLOutputStream. More...

void	setSBMLNamespaces (SBMLNamespaces *sbmlns)
	Sets the SBMLNamespaces object associated with this output stream. More...

void	startElement (const std::string &name, const std::string prefix="")
	Writes the given XML start element name to this XMLOutputStream. More...

void	startElement (const XMLTriple &triple)
	Writes the given XML start element `prefix:name` on this output stream. More...

void	startEndElement (const std::string &name, const std::string prefix="")
	Writes the given XML start and end element name to this XMLOutputStream. More...

void	startEndElement (const XMLTriple &triple)
	Writes the given start element to this output stream. More...

void	upIndent ()
	Increases the indentation level for this XMLOutputStream. More...

void	writeAttribute (const std::string &name, const std::string &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const std::string &prefix, const std::string &value)
	Writes the given namespace-prefixed attribute value to this output stream. More...

void	writeAttribute (const XMLTriple &triple, const std::string &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const char *value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const std::string &prefix, const char *value)
	Writes the given namespace-prefixed attribute value to this output stream. More...

void	writeAttribute (const XMLTriple &triple, const char *value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const bool &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const std::string &prefix, const bool &value)
	Writes the given namespace-prefixed attribute value to this output stream. More...

void	writeAttribute (const XMLTriple &triple, const bool &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const double &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const std::string &prefix, const double &value)
	Writes the given namespace-prefixed attribute value to this output stream. More...

void	writeAttribute (const XMLTriple &triple, const double &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const long &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const std::string &prefix, const long &value)
	Writes the given namespace-prefixed attribute value to this output stream. More...

void	writeAttribute (const XMLTriple &triple, const long &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const int &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const std::string &prefix, const int &value)
	Writes the given namespace-prefixed attribute value to this output stream. More...

void	writeAttribute (const XMLTriple &triple, const int &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const unsigned int &value)
	Writes the given attribute and value to this output stream. More...

void	writeAttribute (const std::string &name, const std::string &prefix, const unsigned int &value)
	Writes the given namespace-prefixed attribute value to this output stream. More...

void	writeAttribute (const XMLTriple &triple, const unsigned int &value)
	Writes the given attribute and value to this output stream. More...

void	writeComment (const std::string &programName, const std::string &programVersion, bool writeTimestamp=true)
	Writes an XML comment with the name and version of this program. More...

void	writeXMLDecl ()
	Writes a standard XML declaration to this output stream. More...

	XMLOutputStream (std::ostream &stream, const std::string encoding="UTF-8", bool writeXMLDecl=true, const std::string programName="", const std::string programVersion="")
	Creates a new XMLOutputStream that wraps the given `stream`. More...

virtual	~XMLOutputStream ()
	Destroys this XMLOutputStream. More...

Static Public Member Functions
static std::string	getLibraryName ()

static std::string	getLibraryVersion ()

static bool	getWriteComment ()

static bool	getWriteTimestamp ()

static void	setLibraryName (const std::string &libraryName)
	sets the name of the library writing the XML More...

static void	setLibraryVersion (const std::string &libraryVersion)
	sets the name of the library writing the output More...

static void	setWriteComment (bool writeComment)
	sets a flag, whether the output stream will write an XML comment at the top of the file. More...

static void	setWriteTimestamp (bool writeTimestamp)
	sets a flag, whether the output stream will write an XML comment with a timestamp at the top of the file. More...

Constructor & Destructor Documentation

XMLOutputStream::XMLOutputStream	(	std::ostream &	stream,
		const std::string	encoding = `"UTF-8"`,
		bool	writeXMLDecl = `true`,
		const std::string	programName = `""`,
		const std::string	programVersion = `""`
	)

Creates a new XMLOutputStream that wraps the given stream.

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

stream	the input stream to wrap.
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.

virtual XMLOutputStream::~XMLOutputStream ( )

virtual

Destroys this XMLOutputStream.

Member Function Documentation

void XMLOutputStream::downIndent ( )

Decreases the indentation level for this XMLOutputStream.

Callers can manually control indentation further by using the XMLOutputStream::upIndent() and XMLOutputStream::downIndent() methods to increase and decrease, respectively, the current level of indentation in the XML output.

See also: upIndent()

void XMLOutputStream::endElement	(	const std::string &	name,
		const std::string	prefix = `""`
	)

Writes the given XML end element name to this XMLOutputStream.

Parameters

name	the name of the element.
prefix	an optional XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.)

void XMLOutputStream::endElement	(	const XMLTriple &	triple,
		bool	text = `false`
	)

Writes the given element to the stream.

Parameters

triple	the XML element to write.
text	the text to put

static std::string XMLOutputStream::getLibraryName ( )

static

Returns: the name of the library to be used in comments ('libSBML' by default).

static std::string XMLOutputStream::getLibraryVersion ( )

static

Returns: a string representing the version of the library writing the output. This is the value of getLibSBMLDottedVersion() by default.

SBMLNamespaces* XMLOutputStream::getSBMLNamespaces ( )

Returns the SBMLNamespaces object attached to this output stream.

Returns: the SBMLNamespaces object, or NULL if none has been set.

static bool XMLOutputStream::getWriteComment ( )

static

Returns: a boolean, whether the output stream will write an XML comment at the top of the file. (Enabled by default.)

static bool XMLOutputStream::getWriteTimestamp ( )

static

Returns: a boolean, whether the output stream will write an XML comment with a timestamp at the top of the file. (Enabled by default.)

XMLOutputStream& XMLOutputStream::operator<< ( const std::string & chars )

Writes the given characters to the underlying stream.

Parameters

chars the characters to write.

XMLOutputStream& XMLOutputStream::operator<< ( const double & value )

Writes the given double-type number to the underlying stream.

Parameters

value the value to write.

XMLOutputStream& XMLOutputStream::operator<< ( const long & value )

Outputs the given long-type number to the underlying stream.

Parameters

value the value to write.

XMLOutputStream& XMLOutputStream::operator<< ( const char & c )

Outputs a single character to the underlying stream.

Parameters

c	the value to write.

void XMLOutputStream::setAutoIndent ( bool indent )

Turns automatic indentation on or off for this XMLOutputStream.

Parameters

indent if true, automatic indentation is turned on.

static void XMLOutputStream::setLibraryName ( const std::string & libraryName )

static

sets the name of the library writing the XML

Parameters

libraryName the name of the library to be used in comments.

static void XMLOutputStream::setLibraryVersion ( const std::string & libraryVersion )

static

sets the name of the library writing the output

Parameters

libraryVersion the version information as string.

void XMLOutputStream::setSBMLNamespaces ( SBMLNamespaces * sbmlns )

Sets the SBMLNamespaces object associated with this output stream.

Parameters

sbmlns the namespace object.

static void XMLOutputStream::setWriteComment ( bool writeComment )

static

sets a flag, whether the output stream will write an XML comment at the top of the file.

(Enabled by default.)

Parameters

writeComment the flag.

static void XMLOutputStream::setWriteTimestamp ( bool writeTimestamp )

static

sets a flag, whether the output stream will write an XML comment with a timestamp at the top of the file.

(Enabled by default.)

Parameters

writeTimestamp the flag.

void XMLOutputStream::startElement	(	const std::string &	name,
		const std::string	prefix = `""`
	)

Writes the given XML start element name to this XMLOutputStream.

Parameters

name	the name of the element.
prefix	an optional XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.)

void XMLOutputStream::startElement ( const XMLTriple & triple )

Writes the given XML start element prefix:name on this output stream.

Parameters

triple the start element to write.

void XMLOutputStream::startEndElement	(	const std::string &	name,
		const std::string	prefix = `""`
	)

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

Parameters

name	the name of the element.
prefix	an optional XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.)

void XMLOutputStream::startEndElement ( const XMLTriple & triple )

Writes the given start element to this output stream.

Parameters

triple the XML element to write.

void XMLOutputStream::upIndent ( )

Increases the indentation level for this XMLOutputStream.

Callers can manually control indentation further by using the XMLOutputStream::upIndent() and XMLOutputStream::downIndent() methods to increase and decrease, respectively, the current level of indentation in the XML output.

See also: downIndent()

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const std::string &	value
	)

Writes the given attribute and value to this output stream.

Parameters

name	the name of the attribute.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const std::string &	prefix,
		const std::string &	value
	)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters

name	the name of the attribute.
prefix	an XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.) See other versions of this method for a variant that does not require a prefix.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const XMLTriple &	triple,
		const std::string &	value
	)

Writes the given attribute and value to this output stream.

Parameters

triple	the attribute, in the form of an XMLTriple.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const char *	value
	)

Writes the given attribute and value to this output stream.

Parameters

name	the name of the attribute.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const std::string &	prefix,
		const char *	value
	)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters

name	the name of the attribute.
prefix	an XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.) See other versions of this method for a variant that does not require a prefix.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const XMLTriple &	triple,
		const char *	value
	)

Writes the given attribute and value to this output stream.

Parameters

triple	the attribute, in the form of an XMLTriple.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const bool &	value
	)

Writes the given attribute and value to this output stream.

Parameters

name	the name of the attribute.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const std::string &	prefix,
		const bool &	value
	)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters

name	the name of the attribute.
prefix	an XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.) See other versions of this method for a variant that does not require a prefix.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const XMLTriple &	triple,
		const bool &	value
	)

Writes the given attribute and value to this output stream.

Parameters

triple	the attribute, in the form of an XMLTriple.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const double &	value
	)

Writes the given attribute and value to this output stream.

Parameters

name	the name of the attribute.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const std::string &	prefix,
		const double &	value
	)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters

name	the name of the attribute.
prefix	an XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.) See other versions of this method for a variant that does not require a prefix.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const XMLTriple &	triple,
		const double &	value
	)

Writes the given attribute and value to this output stream.

Parameters

triple	the attribute, in the form of an XMLTriple.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const long &	value
	)

Writes the given attribute and value to this output stream.

Parameters

name	the name of the attribute.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const std::string &	prefix,
		const long &	value
	)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters

name	the name of the attribute.
prefix	an XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.) See other versions of this method for a variant that does not require a prefix.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const XMLTriple &	triple,
		const long &	value
	)

Writes the given attribute and value to this output stream.

Parameters

triple	the attribute, in the form of an XMLTriple.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const int &	value
	)

Writes the given attribute and value to this output stream.

Parameters

name	the name of the attribute.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const std::string &	prefix,
		const int &	value
	)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters

name	the name of the attribute.
prefix	an XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.) See other versions of this method for a variant that does not require a prefix.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const XMLTriple &	triple,
		const int &	value
	)

Writes the given attribute and value to this output stream.

Parameters

triple	the attribute, in the form of an XMLTriple.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const unsigned int &	value
	)

Writes the given attribute and value to this output stream.

Parameters

name	the name of the attribute.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const std::string &	name,
		const std::string &	prefix,
		const unsigned int &	value
	)

Writes the given namespace-prefixed attribute value to this output stream.

Parameters

name	the name of the attribute.
prefix	an XML namespace prefix to write in front of the `element` name. (The result has the form `prefix:name`.) See other versions of this method for a variant that does not require a prefix.
value	the value of the attribute.

void XMLOutputStream::writeAttribute	(	const XMLTriple &	triple,
		const unsigned int &	value
	)

Writes the given attribute and value to this output stream.

Parameters

triple	the attribute, in the form of an XMLTriple.
value	the value of the attribute.

void XMLOutputStream::writeComment	(	const std::string &	programName,
		const std::string &	programVersion,
		bool	writeTimestamp = `true`
	)

Writes an XML comment with the name and version of this program.

The XML comment has the following form:

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

See the class constructor for more information about this program comment.

Parameters

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.
writeTimestamp	an optional flag indicating that a timestamp should be written.

void XMLOutputStream::writeXMLDecl ( )

Writes a standard XML declaration to this output stream.

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.

Detailed Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation