XMLLoadSave Class Reference

XMLLoadSave adds functions for XML format serialization, although if you write binary LoadSave functions as well, you can do either. More...

#include <XMLLoadSave.h>

Inheritance diagram for XMLLoadSave:

[legend]

Detailed Description

XMLLoadSave adds functions for XML format serialization, although if you write binary LoadSave functions as well, you can do either.

Definition at line 20 of file XMLLoadSave.h.

List of all members.

Classes
class	AutoInit
	allows automatic (de)initialization of libxml when the first or last XMLLoadSave class is created or destroyed More...
class	bad_format
	an exception to be thrown when a bad XML file is parsed, allows file position information to be passed to the user More...
Public Member Functions
	XMLLoadSave ()
	constructor
	XMLLoadSave (const XMLLoadSave &xls)
	copy constructor
XMLLoadSave &	operator= (const XMLLoadSave &xls)
	assignment operator
virtual	~XMLLoadSave ()
	destructor
virtual void	loadXML (xmlNode *node)=0
	This is called when the subclass needs to update its values from those values in the parse tree.
virtual void	saveXML (xmlNode *node) const =0
	This is called when XMLLoadSave needs to have the subclass update values in the tree currently in memory -- may already be filled out by previous contents.
virtual unsigned int	getBinSize () const
	Calculates space needed to save - if you can't precisely add up the size, just make sure to overestimate and things will still work.
virtual unsigned int	loadBuffer (const char buf[], unsigned int len, const char *filename=NULL)
	Load from a saved buffer in memory.
virtual unsigned int	saveBuffer (char buf[], unsigned int len) const
	Save to a given buffer in memory.
virtual unsigned int	loadFile (const char *filename)
	initiate opening of the specified file and loading/saving of all appropriate information.
virtual unsigned int	saveFile (const char *filename) const
	initiate opening of the specified file and loading/saving of all appropriate information.
virtual unsigned int	loadFileStream (FILE f, const char filename=NULL)
	Used recursively on member objects once a file is already open - DON'T CLOSE the file in your overridden functions.
virtual unsigned int	saveFileStream (FILE *f) const
	Used recursively on member objects once a file is already open - DON'T CLOSE the file in your overridden functions.
virtual unsigned int	loadStream (std::istream &is, bool asFragment=false)
	loads from a std::istream, optionally cleaning up stream to allow additional loads if asFragment is true
virtual unsigned int	saveStream (std::ostream &os, bool asFragment) const
	saves to a std::ostream, optionally skipping xml document header if asFragment is true
virtual unsigned int	saveStream (std::ostream &os) const
	Writes into a std::ostream, does not flush.
virtual void	clearParseTree ()
	resets the parse tree currently in memory so that a future save will write a "fresh" copy from scratch.
virtual void	setParseTree (xmlDoc *doc) const
	assigns a parse tree which you have obtained from some other source
virtual xmlDoc *	getParseTree () const
	returns the current parse tree, either from a previous Load, Save, or setParseTree()
virtual xmlDoc *	stealParseTree (xmlDoc *newdoc=NULL) const
	sets the object's parse tree to NULL and returns the former tree, which is then caller's responisibility
virtual void	readParseTree ()
	calls loadXML with the root of the current parse tree
virtual void	writeParseTree () const
	calls saveXML with the root of the current parse tree
virtual void	setCompression (int level)
	allows you to set the compression level used by libxml2 -- this corresponds to the compression level setting of zlib, i.e. 0-9
virtual int	getCompression () const
	returns the current compression level setting used by libxml2 (via zlib)
Protected Member Functions
virtual xmlNode *	FindRootXMLElement (xmlDoc *doc) const
	returns the root element of the xml document
void	reportError (const std::string &context, const bad_format &err) const
	cleans up after an error occurs and sends a message to cerr
Static Protected Member Functions
static int	fileReadCallback (void f, char buf, int len)
	called by libxml2 when it's ready for more data to be read from the source (in this case, a file)
static int	fileCloseCallback (void *f)
	called by libxml2 when it's done reading data
static xmlNode *	skipToElement (xmlNode *cur)
	returns the next element following cur
static xmlNode *	skipToElement (xmlNode *cur, std::string &comment)
	returns the next element following cur; comment is set to the concatination of any comments is encountered in the interim
Protected Attributes
xmlDoc *	xmldocument
	the cached xml parse tree -- contains additional formatting information such as white space and comments
int	compressionLevel
	the current compression level, or level to be used for the next save
bool	autoFormat
	if true, the saved document will use automatic indenting and formatting
class XMLLoadSave::AutoInit	libxmlInit
	allows automatic (de)initialization of libxml when the first or last XMLLoadSave class is created or destroyed

Constructor & Destructor Documentation

XMLLoadSave::XMLLoadSave ( )

constructor

Definition at line 179 of file XMLLoadSave.cc.

XMLLoadSave::XMLLoadSave ( const XMLLoadSave & xls )

copy constructor

Definition at line 183 of file XMLLoadSave.cc.

XMLLoadSave::~XMLLoadSave ( ) [virtual]

destructor

Definition at line 198 of file XMLLoadSave.cc.

Member Function Documentation

void XMLLoadSave::clearParseTree ( ) [virtual]

resets the parse tree currently in memory so that a future save will write a "fresh" copy from scratch.

You may also want to call this in order to save memory after a Load so that the parse tree information isn't retained in memory if you don't care about retaining the file formatting

Definition at line 695 of file XMLLoadSave.cc.

Referenced by operator=(), and ~XMLLoadSave().

int XMLLoadSave::fileCloseCallback ( void * f ) [static, protected]

called by libxml2 when it's done reading data

Definition at line 756 of file XMLLoadSave.cc.

Referenced by loadFileStream().

int XMLLoadSave::fileReadCallback	(	void *	f,
		char *	buf,
		int	len
	)			`[static, protected]`

called by libxml2 when it's ready for more data to be read from the source (in this case, a file)

Definition at line 753 of file XMLLoadSave.cc.

Referenced by loadFileStream().

xmlNode * XMLLoadSave::FindRootXMLElement ( xmlDoc * doc ) const [protected, virtual]

returns the root element of the xml document

Reimplemented in plist::ObjectBase.

Definition at line 741 of file XMLLoadSave.cc.

Referenced by getBinSize(), loadBuffer(), loadFile(), loadFileStream(), loadStream(), readParseTree(), saveBuffer(), saveFile(), saveFileStream(), saveStream(), and writeParseTree().

unsigned int XMLLoadSave::getBinSize ( ) const [virtual]

Calculates space needed to save - if you can't precisely add up the size, just make sure to overestimate and things will still work.

getBinSize is used for reserving buffers during serialization, but does not necessarily determine the actual size of what is written -- the return value of saveBuffer() specifies that after the data actually has been written. If getBinSize overestimates, the extra memory allocation is only temporary, no extra filler bytes are actually stored.

Returns:: number of bytes read/written, 0 if error (or empty)

Implements LoadSave.

Reimplemented in DataEvent< T, TID >, EventBase, KoduEventBase, KoduGiveEvent, KoduSayEvent, LocomotionEvent, LookoutPointAtEvent, LookoutIREvent, PitchEvent, TextMsgEvent, TimerEvent, VisionObjectEvent, and DataEvent< T >.

Definition at line 220 of file XMLLoadSave.cc.

virtual int XMLLoadSave::getCompression ( ) const [virtual]

returns the current compression level setting used by libxml2 (via zlib)

Definition at line 100 of file XMLLoadSave.h.

virtual xmlDoc* XMLLoadSave::getParseTree ( ) const [virtual]

returns the current parse tree, either from a previous Load, Save, or setParseTree()

Definition at line 87 of file XMLLoadSave.h.

unsigned int XMLLoadSave::loadBuffer	(	const char	buf[],
		unsigned int	len,
		const char *	filename = `NULL`
	)			`[virtual]`

Load from a saved buffer in memory.

Parameters:

	buf	pointer to the memory where you should begin loading
	len	length of buf available (this isn't necessarily all yours, there might be other things following your data)

Returns:: the number of bytes actually used

Implements LoadSave.

Reimplemented in EventBase, and Config.

Definition at line 240 of file XMLLoadSave.cc.

unsigned int XMLLoadSave::loadFile ( const char * filename ) [virtual]

initiate opening of the specified file and loading/saving of all appropriate information.

Parameters:

filename

the file to load/save

Returns:: number of bytes read/written, 0 if error (or empty)

Reimplemented from LoadSave.

Reimplemented in EventBase, KoduConfig, and Config.

Definition at line 340 of file XMLLoadSave.cc.

Referenced by GaitedFootstepMC::GaitedFootstepMC(), Kinematics::init(), CameraData::loadCameraData(), LoadWalkControl::selectedFile(), ConfigurationEditor::LoadSettings::selectedFile(), GaitedFootstepMC::setGait(), and XWalkMC::XWalkMC().

unsigned int XMLLoadSave::loadFileStream	(	FILE *	f,
		const char *	filename = `NULL`
	)			`[virtual]`

Used recursively on member objects once a file is already open - DON'T CLOSE the file in your overridden functions.

Parameters:

f

a pointer to the file to load

Returns:: number of bytes read, 0 if error (or empty)

Reimplemented from LoadSave.

Reimplemented in EventBase, and Config.

Definition at line 451 of file XMLLoadSave.cc.

unsigned int XMLLoadSave::loadStream	(	std::istream &	is,
		bool	asFragment = `false`
	)			`[virtual]`

loads from a std::istream, optionally cleaning up stream to allow additional loads if asFragment is true

Definition at line 600 of file XMLLoadSave.cc.

virtual void XMLLoadSave::loadXML ( xmlNode * node ) [pure virtual]

This is called when the subclass needs to update its values from those values in the parse tree.

node is the current node in the tree -- it may be the root, but it may also be a subnode within the tree if a recursive structure is used

Referenced by loadBuffer(), loadFile(), loadFileStream(), loadStream(), and readParseTree().

XMLLoadSave & XMLLoadSave::operator= ( const XMLLoadSave & xls )

assignment operator

Definition at line 187 of file XMLLoadSave.cc.

void XMLLoadSave::readParseTree ( ) [virtual]

calls loadXML with the root of the current parse tree

Definition at line 710 of file XMLLoadSave.cc.

Referenced by GaitedFootsteps::setGait().

void XMLLoadSave::reportError	(	const std::string &	context,
		const bad_format &	err
	)			const `[protected]`

cleans up after an error occurs and sends a message to cerr

Definition at line 202 of file XMLLoadSave.cc.

Referenced by getBinSize(), loadBuffer(), loadFile(), loadFileStream(), loadStream(), readParseTree(), saveBuffer(), saveFile(), saveFileStream(), saveStream(), and writeParseTree().

unsigned int XMLLoadSave::saveBuffer	(	char	buf[],
		unsigned int	len
	)			const `[virtual]`

Save to a given buffer in memory.

Parameters:

	buf	pointer to the memory where you should begin writing
	len	length of buf available. (this isn't necessarily all yours, constrain yourself to what you returned in getBinSize() )

Returns:: the number of bytes actually used

Implements LoadSave.

Reimplemented in EventBase.

Definition at line 284 of file XMLLoadSave.cc.

unsigned int XMLLoadSave::saveFile ( const char * filename ) const [virtual]

initiate opening of the specified file and loading/saving of all appropriate information.

Parameters:

filename

the file to load/save

Returns:: number of bytes read/written, 0 if error (or empty)

Reimplemented from LoadSave.

Reimplemented in EventBase.

Definition at line 387 of file XMLLoadSave.cc.

Referenced by CameraData::saveCameraData(), ConfigurationEditor::SaveSettings::selectedFile(), and SaveWalkControl::takeInput().

unsigned int XMLLoadSave::saveFileStream ( FILE * f ) const [virtual]

Used recursively on member objects once a file is already open - DON'T CLOSE the file in your overridden functions.

Parameters:

f

a pointer to the file to save

Returns:: number of bytes written, 0 if error (or empty)

Reimplemented from LoadSave.

Reimplemented in EventBase.

Definition at line 487 of file XMLLoadSave.cc.

virtual unsigned int XMLLoadSave::saveStream ( std::ostream & os ) const [virtual]

Writes into a std::ostream, does not flush.

Reimplemented from LoadSave.

Definition at line 71 of file XMLLoadSave.h.

Referenced by saveStream().

unsigned int XMLLoadSave::saveStream	(	std::ostream &	os,
		bool	asFragment
	)			const `[virtual]`

saves to a std::ostream, optionally skipping xml document header if asFragment is true

Definition at line 650 of file XMLLoadSave.cc.

virtual void XMLLoadSave::saveXML ( xmlNode * node ) const [pure virtual]

This is called when XMLLoadSave needs to have the subclass update values in the tree currently in memory -- may already be filled out by previous contents.

node is the current node in the tree -- it may be the root, but it may also be a subnode within the tree if a recursive structure is used

Referenced by getBinSize(), saveBuffer(), saveFile(), saveFileStream(), saveStream(), and writeParseTree().

void XMLLoadSave::setCompression ( int level ) [virtual]

allows you to set the compression level used by libxml2 -- this corresponds to the compression level setting of zlib, i.e. 0-9

Definition at line 735 of file XMLLoadSave.cc.

void XMLLoadSave::setParseTree ( xmlDoc * doc ) const [virtual]

assigns a parse tree which you have obtained from some other source

This doesn't update the contents of the subclass's values. The values in doc will be overwritten by those in the subclass on the next Save. If you wish to have the subclass's values updated from doc, call readParseTree() after calling this.

Reimplemented in plist::ObjectBase.

Definition at line 699 of file XMLLoadSave.cc.

Referenced by getBinSize(), operator=(), saveBuffer(), saveFile(), saveFileStream(), saveStream(), and writeParseTree().

xmlNode * XMLLoadSave::skipToElement	(	xmlNode *	cur,
		std::string &	comment
	)			`[static, protected]`

returns the next element following cur; comment is set to the concatination of any comments is encountered in the interim

You should call this with node->next, otherwise you'll just keep getting the same node back again

Definition at line 766 of file XMLLoadSave.cc.

xmlNode * XMLLoadSave::skipToElement ( xmlNode * cur ) [static, protected]

returns the next element following cur

You should call this with node->next, otherwise you'll just keep getting the same node back again

Definition at line 760 of file XMLLoadSave.cc.

Referenced by VisionObjectEvent::loadXML(), TimerEvent::loadXML(), TextMsgEvent::loadXML(), plist::ArrayBase::loadXML(), plist::DictionaryBase::loadXML(), PitchEvent::loadXML(), LookoutIREvent::loadXML(), LookoutPointAtEvent::loadXML(), LocomotionEvent::loadXML(), DataEvent< T, TID >::loadXML(), KinematicJointLoader::loadXMLNode(), plist::DictionaryBase::saveOverXMLNode(), VisionObjectEvent::saveXML(), TimerEvent::saveXML(), TextMsgEvent::saveXML(), plist::ArrayBase::saveXML(), plist::DictionaryBase::saveXML(), PitchEvent::saveXML(), LookoutIREvent::saveXML(), LookoutPointAtEvent::saveXML(), LocomotionEvent::saveXML(), and DataEvent< T, TID >::saveXML().

xmlDoc * XMLLoadSave::stealParseTree ( xmlDoc * newdoc = NULL ) const [virtual]

sets the object's parse tree to NULL and returns the former tree, which is then caller's responisibility

Definition at line 705 of file XMLLoadSave.cc.

Referenced by GaitedFootsteps::setGait().

void XMLLoadSave::writeParseTree ( ) const [virtual]

calls saveXML with the root of the current parse tree

Definition at line 722 of file XMLLoadSave.cc.

Member Data Documentation

bool XMLLoadSave::autoFormat [protected]

if true, the saved document will use automatic indenting and formatting

Definition at line 129 of file XMLLoadSave.h.

Referenced by plist::Collection::Collection(), getBinSize(), operator=(), saveBuffer(), saveFile(), saveFileStream(), and saveStream().

int XMLLoadSave::compressionLevel [protected]

the current compression level, or level to be used for the next save

Definition at line 126 of file XMLLoadSave.h.

Referenced by getBinSize(), getCompression(), operator=(), saveBuffer(), saveFile(), saveFileStream(), saveStream(), setCompression(), and writeParseTree().

class XMLLoadSave::AutoInit XMLLoadSave::libxmlInit [protected]

allows automatic (de)initialization of libxml when the first or last XMLLoadSave class is created or destroyed

allows tracking of libxml usage so the library can be initialized and destructed automatically

xmlDoc* XMLLoadSave::xmldocument [mutable, protected]

the cached xml parse tree -- contains additional formatting information such as white space and comments

Definition at line 123 of file XMLLoadSave.h.

Referenced by clearParseTree(), getBinSize(), getParseTree(), loadBuffer(), loadFile(), loadFileStream(), loadStream(), operator=(), readParseTree(), saveBuffer(), saveFile(), saveFileStream(), saveStream(), setCompression(), setParseTree(), plist::ObjectBase::setParseTree(), stealParseTree(), and writeParseTree().

The documentation for this class was generated from the following files:

XMLLoadSave Class Reference

Detailed Description

Classes

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation