Inheritance diagram for libsbml.XMLOutputStream:

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:

1 size = 3.2;

2 id = 'id';

Then, the element and the attributes can be written to the standard output stream (provided as cout in the libSBML language bindings) as follows:

 from libsbml import *
 
 size = 3.2;
 id = 'id';
 
 # Create an XMLOutputStream object that will write to the standard
 # output stream, which is provide in libSBML's Python language
 # interface as the object 'libsbml.cout'.  Since we imported * from
 # the libsbml module, we can simply refer to it as 'cout' here:
 
 output_stream = XMLOutputStream(cout)
 
 # Create the start element, write the attributes, and close the
 # element.  The output is written immediately by each method.
 
 output_stream.startElement('testElement')
 output_stream.writeAttribute('size', size)
 output_stream.writeAttribute('id', id)
 output_stream.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
def	__init__ (self, args)
	Creates a new XMLOutputStream that wraps the given `stream`. More...

def	downIndent (self)
	Decreases the indentation level for this XMLOutputStream. More...

def	endElement (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	getLibraryName ()

def	getLibraryVersion ()

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

def	getWriteComment ()

def	getWriteTimestamp ()

def	setAutoIndent (self, indent)
	Turns automatic indentation on or off for this XMLOutputStream. More...

def	setLibraryName (libraryName)
	sets the name of the library writing the XML More...

def	setLibraryVersion (libraryVersion)
	sets the name of the library writing the output More...

def	setSBMLNamespaces (self, sbmlns)
	Sets the SBMLNamespaces object associated with this output stream. More...

def	setWriteComment (writeComment)

def	setWriteTimestamp (writeTimestamp)

def	startElement (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	startEndElement (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

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

def	writeAttribute (self, args)
	This method has multiple variants; they differ in the arguments they accept. More...

def	writeComment (self, programName, programVersion, writeTimestamp=True)
	Writes an XML comment with the name and version of this program. More...

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

Constructor & Destructor Documentation

def libsbml.XMLOutputStream.__init__	(	self,
		args
	)

Creates a new XMLOutputStream that wraps the given stream.

__init__(ostream stream, string encoding, bool writeXMLDecl, string programName, string programVersion)   XMLOutputStream
__init__(ostream stream, string encoding, bool writeXMLDecl, string programName)   XMLOutputStream
__init__(ostream stream, string encoding, bool writeXMLDecl)   XMLOutputStream
__init__(ostream stream, string encoding)   XMLOutputStream
__init__(ostream stream)   XMLOutputStream

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.

LibSBML tries to produce human-readable XML output by automatically indenting the bodies of elements. 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.

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.

Documentation note:: The native C++ implementation of this method defines a default argument value. In the documentation generated for different libSBML language bindings, you may or may not see corresponding arguments in the method declarations. For example, in Java and C#, a default argument is handled by declaring two separate methods, with one of them having the argument and the other one lacking the argument. However, the libSBML documentation will be identical for both methods. Consequently, if you are reading this and do not see an argument even though one is described, please look for descriptions of other variants of this method near where this one appears in the documentation.

Member Function Documentation

def libsbml.XMLOutputStream.downIndent ( self )

Decreases the indentation level for this XMLOutputStream.

downIndent()

LibSBML tries to produce human-readable XML output by automatically indenting the bodies of elements. 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()

def libsbml.XMLOutputStream.endElement	(	self,
		args
	)

This method has multiple variants; they differ in the arguments they accept.

endElement(string name, string prefix)
endElement(string name)
endElement(XMLTriple triple, bool text)
endElement(XMLTriple triple)

Each variant is described separately below.

Method variant with the following signature:

endElement(string name, 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`.)

Note: Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.

Method variant with the following signature:

endElement(XMLTriple triple, bool text = false)

Writes the given element to the stream.

Parameters

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

Note: Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.

def libsbml.XMLOutputStream.getLibraryName ( )

getLibraryName()   string

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

def libsbml.XMLOutputStream.getLibraryVersion ( )

getLibraryVersion()   string

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

def libsbml.XMLOutputStream.getSBMLNamespaces ( self )

Returns the SBMLNamespaces object attached to this output stream.

getSBMLNamespaces()   SBMLNamespaces

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

def libsbml.XMLOutputStream.getWriteComment ( )

getWriteComment()   bool

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

def libsbml.XMLOutputStream.getWriteTimestamp ( )

getWriteTimestamp()   bool

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

def libsbml.XMLOutputStream.setAutoIndent	(	self,
		indent
	)

Turns automatic indentation on or off for this XMLOutputStream.

setAutoIndent(bool indent)

Parameters

indent if True, automatic indentation is turned on.

def libsbml.XMLOutputStream.setLibraryName ( libraryName )

sets the name of the library writing the XML

Parameters

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

setLibraryName(string libraryName)

def libsbml.XMLOutputStream.setLibraryVersion ( libraryVersion )

sets the name of the library writing the output

Parameters

libraryVersion the version information as string.

setLibraryVersion(string libraryVersion)

def libsbml.XMLOutputStream.setSBMLNamespaces	(	self,
		sbmlns
	)

Sets the SBMLNamespaces object associated with this output stream.

setSBMLNamespaces(SBMLNamespaces sbmlns)

Parameters

sbmlns the namespace object.

def libsbml.XMLOutputStream.setWriteComment ( writeComment )

setWriteComment(bool writeComment)

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.

def libsbml.XMLOutputStream.setWriteTimestamp ( writeTimestamp )

setWriteTimestamp(bool writeTimestamp)

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.

def libsbml.XMLOutputStream.startElement	(	self,
		args
	)

This method has multiple variants; they differ in the arguments they accept.

startElement(string name, string prefix)
startElement(string name)
startElement(XMLTriple triple)

Each variant is described separately below.

Method variant with the following signature:

startElement(XMLTriple triple)

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

Parameters

triple the start element to write.

Method variant with the following signature:

startElement(string name, 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`.)

Note: Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.

def libsbml.XMLOutputStream.startEndElement	(	self,
		args
	)

This method has multiple variants; they differ in the arguments they accept.

startEndElement(string name, string prefix)
startEndElement(string name)
startEndElement(XMLTriple triple)

Each variant is described separately below.

Method variant with the following signature:

startEndElement(XMLTriple triple)

Writes the given start element to this output stream.

Parameters

triple the XML element to write.

Method variant with the following signature:

startEndElement(string name, 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`.)

Note: Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.

def libsbml.XMLOutputStream.upIndent ( self )

Increases the indentation level for this XMLOutputStream.

upIndent()

LibSBML tries to produce human-readable XML output by automatically indenting the bodies of elements. 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()

def libsbml.XMLOutputStream.writeAttribute	(	self,
		args
	)

This method has multiple variants; they differ in the arguments they accept.

writeAttribute(string name, string value)
writeAttribute(string name, string prefix, string value)
writeAttribute(XMLTriple triple, string value)
writeAttribute(string name, long  value)
writeAttribute(string name, string prefix, long  value)
writeAttribute(XMLTriple triple, long  value)
writeAttribute(string name, bool  value)
writeAttribute(string name, string prefix, bool  value)
writeAttribute(XMLTriple triple, bool  value)
writeAttribute(string name, float  value)
writeAttribute(string name, string prefix, float  value)
writeAttribute(XMLTriple triple, float  value)
writeAttribute(string name, bool  value)
writeAttribute(string name, string prefix, bool  value)
writeAttribute(XMLTriple triple, bool  value)
writeAttribute(string name, bool  value)
writeAttribute(string name, string prefix, bool  value)
writeAttribute(XMLTriple triple, bool  value)
writeAttribute(string name, string prefix, unsigned bool  value)

Each variant is described separately below.

Method variant with the following signature:

writeAttribute(XMLTriple triple, 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.

Method variant with the following signature:

writeAttribute(string name, string prefix, 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.

Method variant with the following signature:

writeAttribute(string name, string prefix, 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.

Method variant with the following signature:

writeAttribute(XMLTriple triple, 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.

Method variant with the following signature:

writeAttribute(string name, 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.

Method variant with the following signature:

writeAttribute(XMLTriple triple, 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.

Method variant with the following signature:

writeAttribute(XMLTriple triple, 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.

Method variant with the following signature:

writeAttribute(string name, 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.

Method variant with the following signature:

writeAttribute(string name, 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.

Method variant with the following signature:

writeAttribute(string name, 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.

Method variant with the following signature:

writeAttribute(string name, string prefix, 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.

Method variant with the following signature:

writeAttribute(string name, string prefix, 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.

Method variant with the following signature:

writeAttribute(string name, string prefix, 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.

Method variant with the following signature:

writeAttribute(XMLTriple triple, 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.

Method variant with the following signature:

writeAttribute(string name, 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.

Method variant with the following signature:

writeAttribute(XMLTriple triple, 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.

Method variant with the following signature:

writeAttribute(string name, 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.

Method variant with the following signature:

writeAttribute(XMLTriple triple, 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.

Method variant with the following signature:

writeAttribute(string name, 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.

Method variant with the following signature:

writeAttribute(string name, string prefix, 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.

Method variant with the following signature:

writeAttribute(string name, string prefix, 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.

def libsbml.XMLOutputStream.writeComment	(	self,
		programName,
		programVersion,
		writeTimestamp = `True`
	)

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

writeComment(string programName, string programVersion, bool writeTimestamp)
writeComment(string programName, string programVersion)

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.

Note: Owing to the way that language interfaces are created in libSBML, this documentation may show methods that define default values for parameters with text that has the form parameter = value. This is not to be intepreted as a Python keyword argument; the use of a parameter name followed by an equals sign followed by a value is only meant to indicate a default value if the argument is not provided at all. It is not a keyword in the Python sense.

def libsbml.XMLOutputStream.writeXMLDecl ( self )

Writes a standard XML declaration to this output stream.

writeXMLDecl()

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

Constructor & Destructor Documentation

Member Function Documentation