Reads and writes XML files. More...

Collaboration diagram for Burger::FileXML:

[legend]

Classes
class	Attribute
	XML Attribute key / value pair. More...

class	CData
	Untouched text object intended for application parsing. More...

class	Comment
	Comment text object. More...

class	Declaration
	XML Declaration object. More...

class	Element
	XML Element object. More...

class	Generic
	Base class for XML file objects. More...

class	RawText
	Raw text object. More...

class	Root
	Linked list root object. More...

Public Member Functions
	FileXML ()
	Initialize an XML file parser.

	~FileXML ()
	Dispose of an XML file parser.

uint_t	Init (const char *pFilename)
	Initialize the records with a file on disk.

uint_t	Init (Filename *pFilename)
	Initialize the records with a file on disk.

uint_t	Init (InputMemoryStream *pInput)
	Initialize the records with an InputMemoryStream.

void	Shutdown (void)
	Dispose of the contents of the structure.

uint_t	Save (OutputMemoryStream *pOutput) const
	Save an XML file.

uint_t	GetUTF8ByteMark (void) const
	Get the flag for writing a UTF8 byte mark.

void	SetUTF8ByteMark (uint_t bUTF8ByteMark)
	Set the flag for writing a UTF8 byte mark.

Declaration *	FindDeclaration (uint_t bAlwaysCreate=0)
	Find the XML declaration.

Declaration *	AddDeclaration (float fVersion=1.0f, const char *pEncoding=0, uint_t bStandalone=2)
	Add an XML declaration record.

void	DeleteDeclaration (void)
	Delete the XML declaration record(s)

Root *	GetRoot (void)
	Return the root object.

const Root *	GetRoot (void) const
	Return the const root object.

const Element *	FindElement (const char *pElementName) const
	Find a named XML Element.

Element *	FindElement (const char *pElementName, uint_t bAlwaysCreate=0)
	Find a named XML Element.

Element *	AddElement (const char *pElementName)
	Add a new Element record.

void	DeleteElement (const char *pElementName)
	Delete an Element record.

void	DeleteElements (const char *pElementName)
	Delete all Element records with this name.

Element *	GetFirstElement (void) const
	Return the pointer to the first Element object.

Generic *	GetFirstItem (void) const
	Return the pointer to the first object.

Static Public Member Functions
static FileXML *	New (void)
	Allocate and initialize a FileXML.

static FileXML *	New (const char *pFilename, uint_t bAlwaysCreate=0)
	Create a new XML file class and initialize it with entries from a text file on disk.

static FileXML *	New (Filename *pFilename, uint_t bAlwaysCreate=0)
	Create a new XML file class and initialize it with entries from a text file on disk.

static FileXML *	New (InputMemoryStream *pInput, uint_t bAlwaysCreate=0)
	Create a new XML file class and initialize it with entries from a text file in a memory stream.

static uint_t	ReadXMLName (String pOutput, InputMemoryStream pInput)
	Extract an XML label from an input stream.

static uint_t	ReadXMLText (String pOutput, InputMemoryStream pInput)
	Extract a XML text from an input stream.

static uint_t	SaveXMLString (OutputMemoryStream pOutput, const char pInput)
	Output a string in XML encoding.

static uint_t	DecodeXMLString (String *pInput)
	Decode a string using XML encoding.

Private Member Functions
	FileXML (const FileXML &)=delete

FileXML &	operator= (const FileXML &)=delete

	FileXML (FileXML &&)=delete

FileXML &	operator= (FileXML &&)=delete

Private Attributes
Root	m_Root
	Root entry for a list of XML objects.

uint_t	m_bUTF8ByteMark
	TRUE if the UTF-8 byte mark should be emitted on write.

Detailed Description

Reads and writes XML files.

This class will read and write out XML text files

<?xml version="1.0" ?>
<!-- This is a sample of the contents -->
<!-- of a legal XML file -->
 
<!-- Section without a name, access by passing "" as the section name -->
<Data>1</Data>
<String>Hello there</String>
 
<!-- Section, access with the string "Foobar" (It's case insensitive) -->
<FOOBAR attribute="55">
 <Data>2</Data>
 <Hi>Hi</Hi>
</FOOBAR>
<!-- Another section with duplicate names -->
<foobar2>
 <Data>2</Data>
 <Float>3.52</Float>
</foobar2>

To read the above XML file, here's some sample code.

FileXML FooFile;
if (!FooFile.LoadFile("9:foo.xml")) {
 FileXML::Element *pElement = FooFile.FindElement("FOOBAR");
 if (pElement) {
 uint_t uData = pElement->ElementGetWord("Data",0,0,255);
 const char *pHi = pElement->ElementGetString("Hi","Not found");
 uint_t uAttribute = pElement->AttributeGetWord("attribute",0);
 }
 pElement = LoadFile.FindElement("Data");
 uint_t uData2 = pElement->GetWord(0,0,255);
}

See also: Burger::FileINI

Constructor & Destructor Documentation

◆ FileXML() [1/3]

Burger::FileXML::FileXML ( const FileXML & )

privatedelete

◆ FileXML() [2/3]

Burger::FileXML::FileXML ( FileXML && )

privatedelete

◆ FileXML() [3/3]

Burger::FileXML::FileXML ( void )

Initialize an XML file parser.

XML Files default with Byte Order Marks disabled.

◆ ~FileXML()

Burger::FileXML::~FileXML ( )

Dispose of an XML file parser.

Release all objects.

Calling Shutdown() performs this action manually.

See also: Shutdown(void)

Member Function Documentation

◆ AddDeclaration()

Burger::FileXML::Declaration *BURGER_API Burger::FileXML::AddDeclaration	(	float	fVersion = 1.0f,
		const char *	pEncoding = 0,
		uint_t	bStandalone = 2 )

Add an XML declaration record.

Traverse the linked list for an XML declaration and if one exists, update it. Otherwise, create a new record and place it as the first record in the XML file

Returns: Pointer to an XML declaration or NULL if not found

See also: FindDeclaration() or DeleteDeclaration()

◆ AddElement()

BURGER_INLINE Element * Burger::FileXML::AddElement ( const char * pElementName )

inline

Add a new Element record.

Create a new Element and place it as the last record in the XML file.

Note: XML allows multiple Elements with the same name. This function will not check if any preexisting Element records possess the same name.

Parameters

pElementName Pointer to a "C" string to the element to search for.

Returns: Pointer to an XML Element or NULL if out of memory

See also: FindElement(const char *,uint_t) or DeleteElement()

◆ DecodeXMLString()

uint_t BURGER_API Burger::FileXML::DecodeXMLString ( String * pInput )

static

Decode a string using XML encoding.

XML files use certain characters for the file format. To use these characters as text, they need to be encoded. This function will take a text string encoded in XML format and decode it to a UTF-8 string.

ASCII	Code
&	&
'	'
"	"
>	>
<	<
\n
美	美

Parameters

pInput Pointer to a String to convert

Returns: Zero if no errors occurred in decoding, non-zero if there was an issue with the string.

See also: SaveXMLString()

◆ DeleteDeclaration()

BURGER_INLINE void Burger::FileXML::DeleteDeclaration ( void )

inline

Delete the XML declaration record(s)

Traverse the linked list for a XML declaration(s) and dispose of them.

See also: FindDeclaration() or AddDeclaration()

◆ DeleteElement()

BURGER_INLINE void Burger::FileXML::DeleteElement ( const char * pElementName )

inline

Delete an Element record.

Traverse the linked list for the first Element with the supplied name and dispose of it. It will stop after the first deletion. If there are multiple records with the same name, the duplicates will remain.

Parameters

pElementName Pointer to a "C" string to the element to search for.

See also: DeleteElements(const char *), FindElement(const char *,uint_t) or AddElement(const char *)

◆ DeleteElements()

BURGER_INLINE void Burger::FileXML::DeleteElements ( const char * pElementName )

inline

Delete all Element records with this name.

Traverse the linked list for the all Element records with the supplied name and dispose of them.

Parameters

pElementName Pointer to a "C" string to the element to search for.

See also: DeleteElement(const char *), FindElement(const char *,uint_t) or AddElement(const char *)

◆ FindDeclaration()

Burger::FileXML::Declaration *BURGER_API Burger::FileXML::FindDeclaration ( uint_t bAlwaysCreate = 0 )

Find the XML declaration.

Traverse the linked list for an XML declaration. Return NULL if the record wasn't found and bAlwaysCreate is zero. If bAlwaysCreate is not zero and the record didn't exist, create one.

Parameters

bAlwaysCreate TRUE to create the section if one didn't already exist

Returns: Pointer to an XML declaration or NULL if not found

See also: DeleteDeclaration() or AddDeclaration()

◆ FindElement() [1/2]

BURGER_INLINE const Element * Burger::FileXML::FindElement ( const char * pElementName ) const

inline

Find a named XML Element.

Traverse the linked list for an XML Element record with the matching name using a case sensitive search. Return NULL if the record wasn't found.

Parameters

pElementName Pointer to a "C" string to the element to search for.

Returns: Pointer to an XML Element or NULL if not found

See also: DeleteElement() or AddElement()

◆ FindElement() [2/2]

BURGER_INLINE Element * Burger::FileXML::FindElement	(	const char *	pElementName,
		uint_t	bAlwaysCreate = 0 )

inline

Find a named XML Element.

Traverse the linked list for an XML Element record with the matching name using a case sensitive search. Return NULL if the record wasn't found and bAlwaysCreate is zero. If bAlwaysCreate is not zero and the record didn't exist, create one.

Parameters

pElementName	Pointer to a "C" string to the element to search for.
bAlwaysCreate	TRUE to create the section if one didn't already exist

Returns: Pointer to an XML Element or NULL if not found

See also: DeleteElement() or AddElement()

◆ GetFirstElement()

BURGER_INLINE Element Burger::FileXML::GetFirstElement ( void ) const

inline

Return the pointer to the first Element object.

Scan the XML file for the first Element object at the root level. If an Element is found return the pointer to the Element object. Return NULL if there are no Element objects.

Returns: NULL if there are no Element objects or the first Element object pointer

See also: GetFirstItem(void) const

◆ GetFirstItem()

BURGER_INLINE Generic Burger::FileXML::GetFirstItem ( void ) const

inline

Return the pointer to the first object.

Return the first object in the XML file. If the file is empty, return NULL

Returns: NULL if there are no objects or a valid Generic pointer

See also: GetFirstElement(void) const

◆ GetRoot() [1/2]

BURGER_INLINE Root * Burger::FileXML::GetRoot ( void )

inline

Return the root object.

Return the root object that contains all objects in an XML file for manual parsing.

Returns: Pointer to the root XML object.

See also: GetRoot(void) const

◆ GetRoot() [2/2]

BURGER_INLINE const Root * Burger::FileXML::GetRoot ( void ) const

inline

Return the const root object.

Return the root object that contains all objects in an XML file for manual parsing.

Returns: Pointer to the root XML object.

See also: GetRoot(void)

◆ GetUTF8ByteMark()

BURGER_INLINE uint_t Burger::FileXML::GetUTF8ByteMark ( void ) const

inline

Get the flag for writing a UTF8 byte mark.

If this flag is non-zero, the file read in (Or to be written) had a three byte UTF8 Byte Order Mark.

Returns: Zero on if no Byte Order Mark was found or will be written, non zero on if so.

See also: SetUTF8ByteMark(uint_t) or Save(OutputMemoryStream *) const

◆ Init() [1/3]

uint_t BURGER_API Burger::FileXML::Init ( const char * pFilename )

Initialize the records with a file on disk.

Purge all records from the class and load in new data from a file on disk using a Burgerlib formatted filename.

Parameters

pFilename Pointer to a "C" string of a valid Burgerlib filename

Returns: Zero on success, or non-zero on failure

See also: Init(InputMemoryStream *) or Init(const char *)

◆ Init() [2/3]

uint_t BURGER_API Burger::FileXML::Init ( Filename * pFilename )

Initialize the records with a file on disk.

Purge all records from the class and load in new data from a file on disk.

Parameters

pFilename Pointer to a Filename structure

Returns: Zero on success, or non-zero on failure

See also: Init(InputMemoryStream *) or Init(const char *)

◆ Init() [3/3]

uint_t BURGER_API Burger::FileXML::Init ( InputMemoryStream * pInput )

Initialize the records with an InputMemoryStream.

Purge all records from the class and load in new data from a memory stream

Parameters

pInput Pointer to an image of the XML text file in memory

Returns: Zero on success, or non-zero on failure

See also: Init(Filename *) or Init(const char *)

◆ New() [1/4]

Burger::FileXML *BURGER_API Burger::FileXML::New	(	const char *	pFilename,
		uint_t	bAlwaysCreate = 0 )

static

Create a new XML file class and initialize it with entries from a text file on disk.

Open the file and read in the entries into a newly allocated FileXML structure.

Return NULL if the file cannot be opened and the bAlwaysCreate flag is zero

Parameters

pFilename	Pointer to a "C" string of a valid Burgerlib filename
bAlwaysCreate	TRUE if the file can't be opened, return an empty record instead

Returns: A pointer to an empty FileXML structure or NULL if out of memory

See also: New(InputMemoryStream *,uint_t), New(void) or New(Filename *,uint_t)

◆ New() [2/4]

Burger::FileXML *BURGER_API Burger::FileXML::New	(	Filename *	pFilename,
		uint_t	bAlwaysCreate = 0 )

static

Create a new XML file class and initialize it with entries from a text file on disk.

Open the file and read in the entries into a newly allocated FileXML structure.

Return NULL if the file cannot be opened and the bAlwaysCreate flag is zero

Parameters

pFilename	Pointer to a Filename record
bAlwaysCreate	TRUE if the file can't be opened, return an empty record instead

Returns: A pointer to an empty FileXML structure or NULL if out of memory

See also: New(InputMemoryStream *,uint_t), New(void) or New(const char *,uint_t)

◆ New() [3/4]

Burger::FileXML *BURGER_API Burger::FileXML::New	(	InputMemoryStream *	pInput,
		uint_t	bAlwaysCreate = 0 )

static

Create a new XML file class and initialize it with entries from a text file in a memory stream.

Read in the entries from the InputMemoryStream into a newly allocated FileXML structure.

Return NULL if the text stream cannot be parsed and the bAlwaysCreate flag is zero

Note: In the event of a parse failure, if bAlwaysCreate is TRUE, return the FileXML record with all the objects that successfully parsed (An incomplete parsing)

Parameters

pInput	Pointer to a InputMemoryStream record that has the text file image
bAlwaysCreate	TRUE if the file can't be parsed, return an empty record instead

Returns: A pointer to an empty FileXML structure or NULL if out of memory

See also: New(Filename *,uint_t), New(void) or New(const char *,uint_t)

◆ New() [4/4]

Burger::FileXML *BURGER_API Burger::FileXML::New ( void )

static

Allocate and initialize a FileXML.

Returns: A pointer to an empty FileXML structure or NULL if out of memory

See also: New(InputMemoryStream *,uint_t), New(const char *,uint_t) or New(Filename *,uint_t)

◆ operator=() [1/2]

FileXML & Burger::FileXML::operator= ( const FileXML & )

privatedelete

◆ operator=() [2/2]

FileXML & Burger::FileXML::operator= ( FileXML && )

privatedelete

◆ ReadXMLName()

uint_t BURGER_API Burger::FileXML::ReadXMLName	(	String *	pOutput,
		InputMemoryStream *	pInput )

static

Extract an XML label from an input stream.

Using XML rules, extract a string from the input stream and store it in the output string.

The first character must be a letter, an underscore or a high ASCII character, followed by alphanumeric, high ASCII, underscores, '-', '.' and ':'

Parameters

pOutput	Pointer to a String to contain the output
pInput	Pointer to an input stream that's pointing to the start of the label

◆ ReadXMLText()

uint_t BURGER_API Burger::FileXML::ReadXMLText	(	String *	pOutput,
		InputMemoryStream *	pInput )

static

Extract a XML text from an input stream.

Extract a quoted string from the input stream.

Parameters

pOutput	Pointer to a String to contain the output
pInput	Pointer to an input stream that's pointing to the start of the label

◆ Save()

uint_t BURGER_API Burger::FileXML::Save ( OutputMemoryStream * pOutput ) const

Save an XML file.

Serialize the data contained in the entire class as an XML text file.

Note: If any text encoding other than UTF8 is used, then ensure that the Byte Order Mark is disabled so other parsers won't get confused.

Parameters

pOutput Output string to store the UTF-8 file image of the data

Returns: Zero on success, non zero on error

◆ SaveXMLString()

uint_t BURGER_API Burger::FileXML::SaveXMLString	(	OutputMemoryStream *	pOutput,
		const char *	pInput )

static

Output a string in XML encoding.

XML files use certain characters for the file format. To use these characters as text, they need to be encoded. This function will take a text string and output it in XML format.

ASCII	Code
&	&
'	'
"	"
>	>
<	<

Parameters

pOutput	Pointer to a String to contain the output
pInput	Pointer to an input stream that's pointing to the start of the label

Returns: Zero if no errors, non-zero for a save error

See also: DecodeXMLString()

◆ SetUTF8ByteMark()

BURGER_INLINE void Burger::FileXML::SetUTF8ByteMark ( uint_t bUTF8ByteMark )

inline

Set the flag for writing a UTF8 byte mark.

If this flag is non-zero, the file written out will have a three byte UTF8 Byte Order Mark first.

Parameters

bUTF8ByteMark Zero on if no Byte Order Mark will be written, non zero on if so.

See also: GetUTF8ByteMark(void) const or Save(OutputMemoryStream *) const

◆ Shutdown()

void BURGER_API Burger::FileXML::Shutdown ( void )

Dispose of the contents of the structure.

Every record is released from memory and the Byte Order Mark flag is cleared

Member Data Documentation

◆ m_bUTF8ByteMark

uint_t Burger::FileXML::m_bUTF8ByteMark

private

TRUE if the UTF-8 byte mark should be emitted on write.

◆ m_Root

Root Burger::FileXML::m_Root

private

Root entry for a list of XML objects.

Classes

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ FileXML() [1/3]

◆ FileXML() [2/3]

◆ FileXML() [3/3]

◆ ~FileXML()

Member Function Documentation

◆ AddDeclaration()

◆ AddElement()

◆ DecodeXMLString()

◆ DeleteDeclaration()

◆ DeleteElement()

◆ DeleteElements()

◆ FindDeclaration()

◆ FindElement() [1/2]

◆ FindElement() [2/2]

◆ GetFirstElement()

◆ GetFirstItem()

◆ GetRoot() [1/2]

◆ GetRoot() [2/2]

◆ GetUTF8ByteMark()

◆ Init() [1/3]

◆ Init() [2/3]

◆ Init() [3/3]

◆ New() [1/4]

◆ New() [2/4]

◆ New() [3/4]

◆ New() [4/4]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ ReadXMLName()

◆ ReadXMLText()

◆ Save()

◆ SaveXMLString()

◆ SetUTF8ByteMark()

◆ Shutdown()

Member Data Documentation

◆ m_bUTF8ByteMark

◆ m_Root