Detailed Description

An interface to an XML input 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.

XMLInputStream_t is an interface to a file or text string containing XML. It wraps the content to be read, as well as the low-level XML parser to be used and an XMLErrorLog_t to record errors and other issues (if any arise). Internally, the content will be in the form of either a pointer to a file name or a character string; XMLInputStream_t knows the form of the content and acts appropriately. Other libSBML object classes use XMLInputStream_t as their interface for all read operations on the XML data. XMLInputStream_t provides the functionality to extract data in the form of XMLToken_t objects. It logs any errors encountered while reading. It also keeps track of whether a read operation has failed irrecoverably or determines whether it is safe to continue reading.

SBMLNamespaces_t objects can be associated with an XMLInputStream_t; this facilitates logging errors related to reading XML attributes and elements that may only be relevant to particular Level and Version combinations of SBML.

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: XMLOutputStream_t

Public Member Functions
LIBLAX_EXTERN XMLInputStream_t *	XMLInputStream_create (const char content, int isFile, const char library)
	Creates a new empty XMLInputStream_t structure and returns a pointer to it. More...

LIBLAX_EXTERN void	XMLInputStream_free (XMLInputStream_t *stream)
	Destroys this XMLInputStream_t structure. More...

LIBLAX_EXTERN const char *	XMLInputStream_getEncoding (XMLInputStream_t *stream)
	Returns the encoding of the XML stream. More...

LIBLAX_EXTERN XMLErrorLog_t *	XMLInputStream_getErrorLog (XMLInputStream_t *stream)
	Returns the error log associated with the given stream. More...

LIBLAX_EXTERN int	XMLInputStream_isEOF (XMLInputStream_t *stream)
	Returns nonzero if the given stream has reached EOF. More...

LIBLAX_EXTERN int	XMLInputStream_isError (XMLInputStream_t *stream)
	Returns nonzero if the stream has experienced a fatal error. More...

LIBLAX_EXTERN int	XMLInputStream_isGood (XMLInputStream_t *stream)
	Returns nonzero if the given stream is in a good state. More...

LIBLAX_EXTERN XMLToken_t *	XMLInputStream_next (XMLInputStream_t *stream)
	Returns the next token in the given stream. More...

LIBLAX_EXTERN const XMLToken_t *	XMLInputStream_peek (XMLInputStream_t *stream)
	Returns the next token without consuming it. More...

LIBLAX_EXTERN int	XMLInputStream_setErrorLog (XMLInputStream_t stream, XMLErrorLog_t log)
	Sets the XMLErrorLog_t this stream will use to log errors. More...

LIBLAX_EXTERN void	XMLInputStream_skipPastEnd (XMLInputStream_t stream, const XMLToken_t element)
	Consume zero or more tokens up to and including the corresponding end element or EOF. More...

LIBLAX_EXTERN void	XMLInputStream_skipText (XMLInputStream_t *stream)
	Consume zero or more tokens up to but not including the next XML element or EOF. More...

Member Function Documentation

LIBLAX_EXTERN XMLInputStream_t * XMLInputStream_create	(	const char *	content,
		int	isFile,
		const char *	library
	)

Creates a new empty XMLInputStream_t structure and returns a pointer to it.

Parameters

content	the source of the stream.
isFile	a Boolean flag to indicate whether `content` is a file name. If `nonzero` (true), `content` is assumed to be the file from which the XML content is to be read. If `zero` (false), `content` is taken to be a string that is the content to be read.
library	the name of the parser library to use.

Returns: pointer to the XMLInputStream_t structure created.

LIBLAX_EXTERN void XMLInputStream_free ( XMLInputStream_t * stream )

Destroys this XMLInputStream_t structure.

Parameters

stream XMLInputStream_t structure to be freed.

LIBLAX_EXTERN const char * XMLInputStream_getEncoding ( XMLInputStream_t * stream )

Returns the encoding of the XML stream.

The encoding is indicated by the xml declaration at the

beginning of an XML document or data stream. The form of this declaration is

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

Note that the SBML specifications require the use of UTF-8 encoding, so for SBML documents, the value returned by this method will always be the string "UTF-8".

Parameters

stream the XMLInputStream_t structure to examine.

Returns: the encoding of this XMLInputStream_t, as a pointer to a string.

LIBLAX_EXTERN XMLErrorLog_t * XMLInputStream_getErrorLog ( XMLInputStream_t * stream )

Returns the error log associated with the given stream.

Parameters

stream the XMLInputStream_t structure to examine.

Returns: the XMLErrorLog_t object for the stream.

LIBLAX_EXTERN int XMLInputStream_isEOF ( XMLInputStream_t * stream )

Returns nonzero if the given stream has reached EOF.

Parameters

stream the XMLInputStream_t structure to examine.

Returns: 1 (true) if this stream is at its end, 0 (false) otherwise.

LIBLAX_EXTERN int XMLInputStream_isError ( XMLInputStream_t * stream )

Returns nonzero if the stream has experienced a fatal error.

Parameters

stream the XMLInputStream_t structure to examine.

Returns: 1 (true) if a fatal error occurred while reading from this stream, 0 (false) otherwise.

LIBLAX_EXTERN int XMLInputStream_isGood ( XMLInputStream_t * stream )

Returns nonzero if the given stream is in a good state.

The definition of "good state" is that XMLInputStream_isEOF() and XMLInputStream_isError() both return 0 (false).

Parameters

stream the XMLInputStream_t structure to examine.

Returns: 1 (true) if the stream is happy, 0 (false) otherwise.

LIBLAX_EXTERN XMLToken_t * XMLInputStream_next ( XMLInputStream_t * stream )

Returns the next token in the given stream.

The token is consumed in the process.

Parameters

stream the XMLInputStream_t structure to examine.

Returns: the token, as an XMLToken_t structure.

See also: XMLInputStream_peek()

LIBLAX_EXTERN const XMLToken_t * XMLInputStream_peek ( XMLInputStream_t * stream )

Returns the next token without consuming it.

A subsequent call to either XMLInputStream_peek() or XMLInputStream_next() will return the same token.

Parameters

stream the XMLInputStream_t structure to examine.

Returns: the token, as an XMLToken_t structure.

See also: XMLInputStream_get()

LIBLAX_EXTERN int XMLInputStream_setErrorLog	(	XMLInputStream_t *	stream,
		XMLErrorLog_t *	log
	)

Sets the XMLErrorLog_t this stream will use to log errors.

Parameters

stream	XMLInputStream_t structure to act on.
log	the XMLErrorLog_t structure to attach to the `stream`.

Returns

integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. The possible values returned by this function are:

LIBLAX_EXTERN void XMLInputStream_skipPastEnd	(	XMLInputStream_t *	stream,
		const XMLToken_t *	element
	)

Consume zero or more tokens up to and including the corresponding end element or EOF.

Parameters

stream	the XMLInputStream_t to act on.
element	the element whose end will be sought in the input stream.

LIBLAX_EXTERN void XMLInputStream_skipText ( XMLInputStream_t * stream )

Consume zero or more tokens up to but not including the next XML element or EOF.

Parameters

stream the XMLInputStream_t structure to act on.

Detailed Description

Public Member Functions

Member Function Documentation