The Micro C++ Library
micxx::XMLFormatter Class Reference

The XMLFormatter class provides a simple XML formatter by implementing the Formatter interface. More...

#include <micxx.hxx>

Inherits micxx::traits::Formatter.

List of all members.

Public Member Functions

 XMLFormatter ()
 Create a new XMLFormatter.
virtual void clear ()
 Reset the internal kept state.
virtual void endElement ()
 Close the current element by inserting a closing tag.
virtual void flush (std::ostream &stream)
 Flush the internal buffer represented by getBuffer() to the stream and clear its contents.
virtual std::string & getBuffer ()
 The underlying target buffer where the formatted output is stored until it is explicitly flushed.
virtual const std::string & getBuffer () const
 The const version of getBuffer().
virtual void startElement (const std::string &name)
 Start a new element by inserting an opening tag.
virtual void text (const std::string &text)
 Format text str (necessary output escaping is done appropriately).
virtual void text (const char *chars)
 Format text chars (necessary output escaping is done appropriately).
virtual void text (long long value)
 Format value as text (necessary output escaping is done appropriately).
virtual void text (unsigned long long value)
 Format value as text (necessary output escaping is done appropriately).
virtual void text (const SYSTEMTIME &time)
 Format systemTime as text (necessary output escaping is done appropriately).
virtual Formatter & operator<< (const std::string &plainText)
 Format plainText as verbatim text content (no output escaping should be performed in any way)
virtual Formatter & operator<< (const char *plainChars)
 Format plainChars as verbatim text content (no output escaping should be performed in any way)
virtual void setIndentation (bool value)
 Enable or disable indentation.
virtual void setIndentationChar (char value)
 Set the indentation character.
virtual void setTabWidth (unsigned value)
 Set the number of spaces that should be inserted for every XMLFormatter::CHAR_TAB.

Static Public Attributes

static const unsigned DEFAULT_TAB_WIDTH = 4
static const char CHAR_TAB = '\t'
static const char CHAR_NEWLINE = '\n'
static const char CHAR_CARRIAGE_RETURN = '\r'
static const char CHAR_SPACE = ' '
static const char CHAR_LT = '<'
static const char CHAR_GT = '>'
static const char CHAR_BACK_SLASH = '/'

Protected Member Functions

void emitStartTagOpen ()
 Emit a starting open tag.
void emitStartTagClosed ()
 Emit a closing open tag.

Protected Attributes

std::stack< std::string > elementNames
 The Stack of element names.
std::stack< unsigned > elementStates
 The Stack of element states.
unsigned documentState
 The document state.
bool indentation
 Indentation is enabled or disabled.
char indentationChar
 The character used for indentation. Either XMLFormatter::CHAR_TAB or XMLFormatter::CHAR_SPACE.
unsigned tabWidth
 The number of XMLFormatter::CHAR_SPACE that should be inserted for each XMLFormatter::CHAR_TAB if identation is enabled.

Static Protected Attributes

static const unsigned EMITTED_START_TAG_OPEN = 0x01
 A start tag open <elementName for the current element has already been emitted.
static const unsigned EMITTED_START_TAG_CLOSED = 0x02
 A start tag close <elementName ... > for the current element has already been emitted.
static const unsigned EMITTED_TEXT = 0x04
 A start tag and some text has already been emitted for the current element.
static const unsigned EMITTED_NESTED_ELEMENT = 0x08
 At least one nested element has been emitted for the current element.
static const unsigned EMITTED_DOCUMENT = 0x10
 At least anything from the document has been emitted.

Detailed Description

The XMLFormatter class provides a simple XML formatter by implementing the Formatter interface.

Using an XMLFormatter the following example

 void foo(micxx::traits::Formatter * formatter)
 {
     micxx::XMLFormatter * xmlFormatter = dynamic_cast<micxx::XMLFormatter*>(formatter);
     if (xmlFormatter)
     {
         xmlFormatter->setIndentation(true);
         xmlFormatter->setIndentationChar(XMLFormatter::CHAR_SPACE);
         xmlFormatter->setTabWidth(2);
     }
     formatter->startElement("A");
     formatter->text("Text");
     formatter->startElement("B");   // nested element within A
     formatter->text("Nested Text");
     formatter->endElement();        // close nested element B
     formatter->startElement("C");
     formatter->endElement();        // empty element C
     formatter->endElement();        // close element A
     formatter->flush(cout);
 }

would be formatted like

 <A>Text
   <B>Nested Text</B>
   <C/>
 </A>
Author:
Norbert Klose
Date:
May, 2007

Constructor & Destructor Documentation

micxx::XMLFormatter::XMLFormatter ( )

Create a new XMLFormatter.


Member Function Documentation

virtual void micxx::XMLFormatter::clear ( ) [virtual]

Reset the internal kept state.

Implements micxx::traits::Formatter.

void micxx::XMLFormatter::emitStartTagClosed ( ) [protected]

Emit a closing open tag.

If not already done for the current element, emit a closing open tag like <elementName...> and update the state of the current element accordingly.

void micxx::XMLFormatter::emitStartTagOpen ( ) [protected]

Emit a starting open tag.

If not already done for the current element, emit a starting open tag like <elementName and update the state of the current element accordingly.

virtual void micxx::XMLFormatter::endElement ( ) [virtual]

Close the current element by inserting a closing tag.

Note:
Depending on the contents (state) of the current element, either
  • an empty element is inserted, if no content at all has been inserted into the current element, or
  • a closing element with no explicit CHAR_NEWLINE inserted, if no nested element has been inserted into the current element, or
  • a closing tag on a new line, if at least one nested element has been inserted into the current element.
The current element is represented by the top of

Implements micxx::traits::Formatter.

virtual void micxx::XMLFormatter::flush ( std::ostream &  stream) [virtual]

Flush the internal buffer represented by getBuffer() to the stream and clear its contents.

Implements micxx::traits::Formatter.

virtual std::string& micxx::XMLFormatter::getBuffer ( ) [virtual]

The underlying target buffer where the formatted output is stored until it is explicitly flushed.

virtual const std::string& micxx::XMLFormatter::getBuffer ( ) const [virtual]

The const version of getBuffer().

virtual Formatter& micxx::XMLFormatter::operator<< ( const std::string &  plainText) [virtual]

Format plainText as verbatim text content (no output escaping should be performed in any way)

Implements micxx::traits::Formatter.

virtual Formatter& micxx::XMLFormatter::operator<< ( const char *  plainChars) [virtual]

Format plainChars as verbatim text content (no output escaping should be performed in any way)

Implements micxx::traits::Formatter.

virtual void micxx::XMLFormatter::setIndentation ( bool  value) [virtual]

Enable or disable indentation.

If indentation is enabled, nested elements are indented either with

  • nested depth tab characters or
  • with nested depth multiplied by tab width spaces.

The nested depth is represented by the size of XMLFormatter::elementNames minus 1. If indentation is disabled, all start and end tags are written on a new line. If an element does not contain any nested elements there is no explicit newline character inserted before the end tag.

Note:
Indentation is disabled by default.
Parameters:
valueIf true, indentation is enabled, otherwise indentation is disabled.
virtual void micxx::XMLFormatter::setIndentationChar ( char  value) [virtual]

Set the indentation character.

Parameters:
valueEither XMLFormatter::CHAR_TAB or XMLFormatter::CHAR_SPACE.
virtual void micxx::XMLFormatter::setTabWidth ( unsigned  value) [virtual]

Set the number of spaces that should be inserted for every XMLFormatter::CHAR_TAB.

The tab width has only an effect, if indentation is enabled and if indentation character is set to XMLFormatter::CHAR_SPACE.

Note:
The tab width is XMLFormatter::DEFAULT_TAB_WIDTH by default.
Parameters:
valueThe number of spaces that will be inserted for every XMLFormatter::CHAR_TAB. Must be greater than 1.
virtual void micxx::XMLFormatter::startElement ( const std::string &  name) [virtual]

Start a new element by inserting an opening tag.

Note:
The start tag is not inserted directly. Instead it is emitted only if demanded by other insertions.

Implements micxx::traits::Formatter.

virtual void micxx::XMLFormatter::text ( unsigned long long  value) [virtual]

Format value as text (necessary output escaping is done appropriately).

Implements micxx::traits::Formatter.

virtual void micxx::XMLFormatter::text ( const std::string &  str) [virtual]

Format text str (necessary output escaping is done appropriately).

Implements micxx::traits::Formatter.

virtual void micxx::XMLFormatter::text ( long long  value) [virtual]

Format value as text (necessary output escaping is done appropriately).

Implements micxx::traits::Formatter.

virtual void micxx::XMLFormatter::text ( const SYSTEMTIME systemTime) [virtual]

Format systemTime as text (necessary output escaping is done appropriately).

Implements micxx::traits::Formatter.

virtual void micxx::XMLFormatter::text ( const char *  chars) [virtual]

Format text chars (necessary output escaping is done appropriately).

Implements micxx::traits::Formatter.


Member Data Documentation

const char micxx::XMLFormatter::CHAR_BACK_SLASH = '/' [static]
const char micxx::XMLFormatter::CHAR_CARRIAGE_RETURN = '\r' [static]
const char micxx::XMLFormatter::CHAR_GT = '>' [static]
const char micxx::XMLFormatter::CHAR_LT = '<' [static]
const char micxx::XMLFormatter::CHAR_NEWLINE = '\n' [static]
const char micxx::XMLFormatter::CHAR_SPACE = ' ' [static]
const char micxx::XMLFormatter::CHAR_TAB = '\t' [static]
const unsigned micxx::XMLFormatter::DEFAULT_TAB_WIDTH = 4 [static]
unsigned micxx::XMLFormatter::documentState [protected]

The document state.

std::stack<std::string> micxx::XMLFormatter::elementNames [protected]

The Stack of element names.

The top of XMLFormatter::elementNames represents the current element which is always the innermost element.

std::stack<unsigned> micxx::XMLFormatter::elementStates [protected]

The Stack of element states.

Each entry represents the state of an element on the path from the outermost (maybe the root element) to the innermost or current element.

const unsigned micxx::XMLFormatter::EMITTED_DOCUMENT = 0x10 [static, protected]

At least anything from the document has been emitted.

const unsigned micxx::XMLFormatter::EMITTED_NESTED_ELEMENT = 0x08 [static, protected]

At least one nested element has been emitted for the current element.

const unsigned micxx::XMLFormatter::EMITTED_START_TAG_CLOSED = 0x02 [static, protected]

A start tag close <elementName ... > for the current element has already been emitted.

const unsigned micxx::XMLFormatter::EMITTED_START_TAG_OPEN = 0x01 [static, protected]

A start tag open <elementName for the current element has already been emitted.

const unsigned micxx::XMLFormatter::EMITTED_TEXT = 0x04 [static, protected]

A start tag and some text has already been emitted for the current element.

Indentation is enabled or disabled.

The character used for indentation. Either XMLFormatter::CHAR_TAB or XMLFormatter::CHAR_SPACE.

unsigned micxx::XMLFormatter::tabWidth [protected]

The number of XMLFormatter::CHAR_SPACE that should be inserted for each XMLFormatter::CHAR_TAB if identation is enabled.


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