Ceylan::XML::XMLParser Class Reference

XML parser, which can read and write from and to XML file. More...

#include <CeylanXMLParser.h>

Inheritance diagram for Ceylan::XML::XMLParser:
Inheritance graph
[legend]
Collaboration diagram for Ceylan::XML::XMLParser:
Collaboration graph
[legend]

List of all members.

Public Types

enum  LowerThanSequence {
  Declaration, Comment, OpeningMarkup, ClosingMarkup,
  UnexpectedElement
}
 

All sequences that begin with a '<'.

More...
typedef Ceylan::Tree
< Ceylan::XML::XMLElement
XMLTree
enum  TextOutputFormat { rawText, html }
 

Defines what text output formats for TextDisplayable instances are available.

More...

Public Member Functions

 XMLParser (const std::string &filename)
 XML parser, which reads a file and generates from it a tree in memory.
virtual ~XMLParser () throw ()
 Virtual destructor.
virtual bool hasXMLTree () const
 Returns whether this parser has an available XML tree.
virtual XMLTreegetXMLTree () const
 Returns the internal XML tree.
virtual void setXMLTree (XMLTree &newTree)
 Sets the internal XML tree to the specified one.
virtual void saveToFile (const std::string &filename="") const
 Saves the internal tree into an XML file, whose filename was specified in the constructor.
virtual void loadFromFile ()
 Loads from an XML file, whose filename was specified in the constructor, a new internal XML tree.
virtual const std::string toString (Ceylan::VerbosityLevels level=Ceylan::high) const
 Returns a user-friendly description of the state of this object.

Static Public Member Functions

static LowerThanSequence InterpretLowerThanSequence (System::InputStream &input, Ceylan::Uint8 &readChar)
 Reads a character from input stream, whereas previous read character is supposed to be '<', and interprets the kind of sequence it begins.
static std::string DescribeLowerThanSequence (LowerThanSequence sequence)
 Returns a string describing the specified sequence.
static void InterpretXMLDeclaration (System::InputStream &input)
 Reads from specified input stream a full XML declaration (ex: [<?]xml version="1.0".
static void ParseAttributeSequence (const std::string &toBeParsed, AttributeMap &attributeMap)
 Reads from specified string a sequence of attributes (ex: version="1.0"), and store them in specified map.
static const std::string ToString (std::list< TextDisplayable * > displayables, Ceylan::VerbosityLevels level=Ceylan::high)
 Returns a user-friendly description of this list of pointers to text displayable instances.
static TextOutputFormat GetOutputFormat ()
 Returns the current overall text format to be used by TextDisplayable instances.
static void SetOutputFormat (TextOutputFormat newOutputFormat)
 Sets the current overall text format to be used by TextDisplayable instances.

Static Public Attributes

static std::string DefaultEncoding = Latin1WithEuroEncoding
 Default XML encoding is ISO-8859-15 (Latin-1 with euro).

Protected Member Functions

virtual void handleNextElement (System::InputStream &input, std::stack< std::string > &markupStack, XMLTree *currentNode, Ceylan::Uint8 &remainder)
 Reads from specified input stream until a text, an opening or a closing markup is found, manages it and continue recursively until the first open markup is closed: the XML document is then fully parsed.

Protected Attributes

std::string _filename
 The filename of the file where the XML document can be serialized or deserialized.
XMLTree_parsedTree
 The tree corresponding to an XML document.
std::string _encoding
 The current encoding for the XML document.

Static Protected Attributes

static TextOutputFormat _OutputFormat = rawText
 The text format to be used currently by TextDisplayable instances.

Private Member Functions

 XMLParser (const XMLParser &source)
 Copy constructor made private to ensure that it will never be called.
XMLParseroperator= (const XMLParser &source)
 Assignment operator made private to ensure that it will never be called.

Detailed Description

XML parser, which can read and write from and to XML file.

From a file, a tree in memory is generated, and reciprocally a tree can be saved into a XML file.

This light-weight parser works a little like DOM: it reads the full XML document before generating its counterpart in memory.

No validation nor XML schema managed.

Definition at line 104 of file CeylanXMLParser.h.


Member Typedef Documentation

Definition at line 112 of file CeylanXMLParser.h.


Member Enumeration Documentation

All sequences that begin with a '<'.

Enumerator:
Declaration 

XML declaration, for example: '<?xml version="1.0"?>'.

Comment 

XML comment, for example: ''.

OpeningMarkup 

XML opening Markup, for example: '

'.

ClosingMarkup 

XML closing Markup, for example: '

'.

UnexpectedElement 

Unexpected XML element:

Definition at line 257 of file CeylanXMLParser.h.

Defines what text output formats for TextDisplayable instances are available.

Enumerator:
rawText 
html 

Definition at line 124 of file CeylanTextDisplayable.h.


Constructor & Destructor Documentation

XMLParser::XMLParser ( const std::string &  filename  )  [explicit]

XML parser, which reads a file and generates from it a tree in memory.

This tree can be traversed easily to extract relevant informations from it.

Parameters:
filename the file whose content is formatted in XML. Depending on which methods will be called, the filename will be used to save an internal tree to the corresponding file, or to load an internal tree from an already existing file with that filename.

Note that therefore no tree is available when this parser is created.

See also:
loadFromFile

Definition at line 98 of file CeylanXMLParser.cc.

XMLParser::~XMLParser (  )  throw () [virtual]

Virtual destructor.

Definition at line 108 of file CeylanXMLParser.cc.

References _parsedTree.

Ceylan::XML::XMLParser::XMLParser ( const XMLParser source  )  [private]

Copy constructor made private to ensure that it will never be called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Note:
Made to avoid unwanted hidden clone of the Singleton.

Member Function Documentation

std::string XMLParser::DescribeLowerThanSequence ( LowerThanSequence  sequence  )  [static]

Returns a string describing the specified sequence.

Parameters:
the sequence type to describe.

Definition at line 309 of file CeylanXMLParser.cc.

References ClosingMarkup, Comment, Declaration, OpeningMarkup, and UnexpectedElement.

Referenced by handleNextElement(), and loadFromFile().

TextDisplayable::TextOutputFormat TextDisplayable::GetOutputFormat (  )  [static, inherited]
XMLParser::XMLTree & XMLParser::getXMLTree (  )  const [virtual]

Returns the internal XML tree.

Exceptions:
XMLParserException if there is no available tree.
See also:
hasXMLTree
Note:
The returned reference points to the internal tree, which is still owned by this parser.

Definition at line 127 of file CeylanXMLParser.cc.

References _parsedTree.

void XMLParser::handleNextElement ( System::InputStream input,
std::stack< std::string > &  markupStack,
XMLTree currentNode,
Ceylan::Uint8 remainder 
) [protected, virtual]

Reads from specified input stream until a text, an opening or a closing markup is found, manages it and continue recursively until the first open markup is closed: the XML document is then fully parsed.

Parameters:
input the stream from which XML data is to be read.
markupStack an internal stack used to determine the relationships between tree nodes.
currentNode the current node being considered. Either this markup is an opening one, and it will lead to add a son to current node, or it is a closing one, that will lead the new current node to be the father of this current node.
Returns:
true if the document is fully parsed, i.e. if the root markup hit its closing mark.

Definition at line 559 of file CeylanXMLParser.cc.

References _parsedTree, Ceylan::Tree< Content >::addSon(), ClosingMarkup, DescribeLowerThanSequence(), DISPLAY_DEBUG_XML, Ceylan::encodeToHTML(), generalUtils::false, Ceylan::XML::XMLMarkup::getAttributes(), Ceylan::Tree< Content >::getFather(), Ceylan::XML::HigherThan, InterpretLowerThanSequence(), Ceylan::isWhitespace(), Ceylan::XML::LowerThan, OpeningMarkup, ParseAttributeSequence(), Ceylan::System::InputStream::readUint8(), setXMLTree(), Ceylan::System::InputStream::skipWhitespaces(), Ceylan::XML::Slash, Ceylan::Tree< Content >::toString(), Ceylan::XML::XMLMarkup::toString(), Ceylan::toString(), and generalUtils::true.

Referenced by loadFromFile().

bool XMLParser::hasXMLTree (  )  const [virtual]

Returns whether this parser has an available XML tree.

Returns:
true iff there is an available XML tree.

Definition at line 118 of file CeylanXMLParser.cc.

References _parsedTree.

XMLParser::LowerThanSequence XMLParser::InterpretLowerThanSequence ( System::InputStream input,
Ceylan::Uint8 readChar 
) [static]

Reads a character from input stream, whereas previous read character is supposed to be '<', and interprets the kind of sequence it begins.

Parameters:
input the stream to read from.
readChar the variable in which the read variable will be put once interpreted (one too many read).
Returns:
the identifier of the interpreted sequence.
Exceptions:
InputStreamException if the operation failed.

Definition at line 273 of file CeylanXMLParser.cc.

References ClosingMarkup, Comment, Declaration, Ceylan::XML::ExclamationMark, Ceylan::isLetter(), OpeningMarkup, Ceylan::XML::QuestionMark, Ceylan::System::InputStream::readUint8(), Ceylan::XML::Slash, and UnexpectedElement.

Referenced by handleNextElement(), and loadFromFile().

void XMLParser::InterpretXMLDeclaration ( System::InputStream input  )  [static]

Reads from specified input stream a full XML declaration (ex: [<?]xml version="1.0".

..?>), whereas previous read characters are supposed to be '<?', interprets the declaration, skips next whitespace and put the first character read after in specified char.

Parameters:
input the stream to read from.
Exceptions:
InputStreamException if an I/O operation failed, or XMLParserException if an incorrect declaration is found.

Definition at line 346 of file CeylanXMLParser.cc.

References DISPLAY_DEBUG_XML, Ceylan::formatStringMap(), Ceylan::XML::HigherThan, Ceylan::XML::Latin1WithEuroEncoding, ParseAttributeSequence(), Ceylan::XML::QuestionMark, Ceylan::System::InputStream::readUint8(), and Ceylan::toString().

Referenced by loadFromFile().

void XMLParser::loadFromFile (  )  [virtual]

Loads from an XML file, whose filename was specified in the constructor, a new internal XML tree.

Note:
Any already existing tree will be deleted first.

The parser does its best to be robust and overcome incorrect XML syntaxes.

Definition at line 197 of file CeylanXMLParser.cc.

References _filename, _parsedTree, Declaration, DescribeLowerThanSequence(), dataUtils::e, Ceylan::Holder< Held >::get(), handleNextElement(), InterpretLowerThanSequence(), InterpretXMLDeclaration(), Ceylan::XML::LowerThan, Ceylan::Exception::toString(), and Ceylan::toString().

XMLParser& Ceylan::XML::XMLParser::operator= ( const XMLParser source  )  [private]

Assignment operator made private to ensure that it will never be called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void XMLParser::ParseAttributeSequence ( const std::string &  toBeParsed,
AttributeMap attributeMap 
) [static]

Reads from specified string a sequence of attributes (ex: version="1.0"), and store them in specified map.

Parameters:
toBeParsed the string to read the attributes from.
attributeMap the map in which the read attributes (name/value pairs) will be stored once interpreted.
Exceptions:
XMLParserException if an incorrect syntax is found.

Definition at line 420 of file CeylanXMLParser.cc.

References DISPLAY_DEBUG_XML, Ceylan::XML::DoubleQuote, Ceylan::XML::Equal, Ceylan::isLetter(), Ceylan::isWhitespace(), and Ceylan::toString().

Referenced by handleNextElement(), and InterpretXMLDeclaration().

void XMLParser::saveToFile ( const std::string &  filename = ""  )  const [virtual]

Saves the internal tree into an XML file, whose filename was specified in the constructor.

It becomes the new default filename.

Parameters:
filename the file where the XML tree should be saved. If an empty string is specified, then the filename given to the constructor is used instead.
Note:
If the file is already existing, its content will be lost and replaced by this new content.

Definition at line 151 of file CeylanXMLParser.cc.

References _encoding, _filename, _parsedTree, Ceylan::Tree< Content >::accept(), Ceylan::System::File::close(), dataUtils::e, Ceylan::Exception::toString(), and Ceylan::System::File::write().

void TextDisplayable::SetOutputFormat ( TextOutputFormat  newOutputFormat  )  [static, inherited]

Sets the current overall text format to be used by TextDisplayable instances.

Parameters:
newOutputFormat the new output format.

Definition at line 72 of file CeylanTextDisplayable.cc.

References Ceylan::TextDisplayable::_OutputFormat.

Referenced by Ceylan::Log::LogHolder::LogHolder().

void XMLParser::setXMLTree ( XMLTree newTree  )  [virtual]

Sets the internal XML tree to the specified one.

If there was already an XML tree available, it is deleted before the new one is set.

Parameters:
newTree the new XML tree for this parser.
Note:
The parser takes ownership of the specified tree.

Definition at line 139 of file CeylanXMLParser.cc.

References _parsedTree.

Referenced by handleNextElement().

const std::string TextDisplayable::ToString ( std::list< TextDisplayable * >  displayables,
Ceylan::VerbosityLevels  level = Ceylan::high 
) [static, inherited]

Returns a user-friendly description of this list of pointers to text displayable instances.

Parameters:
displayables a list of pointers to TextDisplayable instances/
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
toString, Ceylan::VerbosityLevels

Definition at line 45 of file CeylanTextDisplayable.cc.

References Ceylan::formatStringList().

const string XMLParser::toString ( Ceylan::VerbosityLevels  level = Ceylan::high  )  const [virtual]

Returns a user-friendly description of the state of this object.

Parameters:
level the requested verbosity level.
Note:
Text output format is determined from overall settings.
See also:
TextDisplayable

Implements Ceylan::TextDisplayable.

Definition at line 534 of file CeylanXMLParser.cc.

References _filename, _parsedTree, Ceylan::low, and Ceylan::Tree< Content >::toString().


Member Data Documentation

std::string Ceylan::XML::XMLParser::_encoding [protected]

The current encoding for the XML document.

Example: ISO-8859-15.

Definition at line 403 of file CeylanXMLParser.h.

Referenced by saveToFile().

std::string Ceylan::XML::XMLParser::_filename [protected]

The filename of the file where the XML document can be serialized or deserialized.

Definition at line 388 of file CeylanXMLParser.h.

Referenced by loadFromFile(), saveToFile(), and toString().

TextDisplayable::TextOutputFormat TextDisplayable::_OutputFormat = rawText [static, protected, inherited]

The text format to be used currently by TextDisplayable instances.

Note:
Defaults to raw text.

Definition at line 158 of file CeylanTextDisplayable.h.

Referenced by Ceylan::TextDisplayable::GetOutputFormat(), and Ceylan::TextDisplayable::SetOutputFormat().

The tree corresponding to an XML document.

Definition at line 393 of file CeylanXMLParser.h.

Referenced by getXMLTree(), handleNextElement(), hasXMLTree(), loadFromFile(), saveToFile(), setXMLTree(), toString(), and ~XMLParser().

Default XML encoding is ISO-8859-15 (Latin-1 with euro).

Definition at line 251 of file CeylanXMLParser.h.


The documentation for this class was generated from the following files:
Generated on Mon Nov 29 13:43:24 2010 for Ceylan by  doxygen 1.6.3