aboutsummaryrefslogtreecommitdiff
path: root/common/xmlparser.h
diff options
context:
space:
mode:
authorVicent Marti2008-07-30 14:08:07 +0000
committerVicent Marti2008-07-30 14:08:07 +0000
commitf930bbac59c6216169d6cc8b4926792ae4b0e976 (patch)
tree41387d3ef84ff8b47f240f417a0a3da4cc197873 /common/xmlparser.h
parente7959952bbd2256fc83f0ca2f1c0b498e313617e (diff)
downloadscummvm-rg350-f930bbac59c6216169d6cc8b4926792ae4b0e976.tar.gz
scummvm-rg350-f930bbac59c6216169d6cc8b4926792ae4b0e976.tar.bz2
scummvm-rg350-f930bbac59c6216169d6cc8b4926792ae4b0e976.zip
Finished documentation.
svn-id: r33449
Diffstat (limited to 'common/xmlparser.h')
-rw-r--r--common/xmlparser.h89
1 files changed, 72 insertions, 17 deletions
diff --git a/common/xmlparser.h b/common/xmlparser.h
index 221d382a70..8b2d2ee956 100644
--- a/common/xmlparser.h
+++ b/common/xmlparser.h
@@ -55,12 +55,14 @@ namespace Common {
parsing layout of the XML file.
Declaring the XML layout is done with the help of the CUSTOM_XML_PARSER()
- macro: this macro must appear once inside the Custom Parser Class declaration,
- and takes a single parameter, the name of the Custom Parser Class.
+ macro: this macro must appear once inside the Custom Parser Class
+ declaration, and takes a single parameter, the name of the Custom Parser
+ Class.
- The macro must be followed by the actual layout of the XML files to be parsed,
- and closed with the PARSER_END() macro. The layout of XML files is defined by
- the use of 3 helper macros: XML_KEY(), KEY_END() and XML_PROP().
+ The macro must be followed by the actual layout of the XML files to be
+ parsed, and closed with the PARSER_END() macro. The layout of XML files
+ is defined by the use of 3 helper macros: XML_KEY(), KEY_END() and
+ XML_PROP().
Here's a sample of its usage:
@@ -101,9 +103,9 @@ namespace Common {
The XML_KEY() macro takes a single argument, the name of the expected key.
Inside the scope of each key, you may define properties for the given key
- with the XML_PROP() macro, which takes as parameters the name of the property
- and whether it's optional or required. You might also define the contained
- children keys, using the XML_KEY() macro again.
+ with the XML_PROP() macro, which takes as parameters the name of the
+ property and whether it's optional or required. You might also define the
+ contained children keys, using the XML_KEY() macro again.
The scope of a XML key is closed with the KEY_END() macro.
As an example, the following XML layout:
@@ -123,10 +125,55 @@ namespace Common {
<color name = "blue" rgb = "0, 0, 255" optional_param = "565" />
</palette>
- TODO: documentation on callbacks
+ Once a layout has been defined, everytime a XML node (that is, a key and
+ all its properties) has been parsed, a specific callback funcion is called,
+ which should take care of managing the parsed data for the node.
- Note that the XML parser doesn't take into account the actual order of the keys and
- properties in the XML layout definition, only its layout and relationships.
+ Callback functions must be explicitly declared with the following syntax:
+
+ bool parserCallback_KEYNAME(ParserNode *node);
+
+ A callback function is needed for each key that can be parsed, since they
+ are called automatically; the function will receive a pointer to the XML
+ Node that has been parsed. This XML Node has the following properties:
+
+ - It's assured to be expected in the layout of the XML file (i.e.
+ has the proper position and depth in the XML tree).
+
+ - It's assured to contain all the required Properties that have
+ been declared in the XML layout.
+
+ - It's assured to contain NO unexpected properties (i.e. properties
+ which haven't been declared in the XML layout).
+
+ Further validation of the Node's data may be performed inside the callback
+ function. Once the node has been validated and its data has been parsed/
+ managed, the callback function is expected to return true.
+
+ If the data in the XML Node is corrupted or there was a problem when
+ parsing it, the callback function is expected to return false or,
+ preferably, to throw a parserError() using the following syntax:
+
+ return parserError("There was a problem in key '%s'.", arg1, ...);
+
+ Also, note that the XML parser doesn't take into account the actual order
+ of the keys and properties in the XML layout definition, only its layout
+ and relationships.
+
+ Lastly, when defining your own Custom XML Parser, further customization
+ may be accomplished _optionally_ by overloading several virtual functions
+ of the XMLParser class.
+
+ Check the API documentation of the following functions for more info:
+
+ virtual bool closedKeyCallback(ParserNode *node);
+ virtual bool skipComments();
+ virtual bool isValidNameChar(char c);
+ virtual void cleanup();
+
+ Check the sample implementation of the GUI::ThemeParser custom parser
+ for a working sample of a Custom XML Parser.
+
*/
#define XML_KEY(keyName) {\
@@ -215,6 +262,8 @@ public:
virtual ~XMLParser() {
while (!_activeKey.empty())
delete _activeKey.pop();
+
+ delete _XMLkeys;
}
/** Active state for the parser */
@@ -243,6 +292,12 @@ public:
Common::List<XMLKeyProperty> properties;
ChildMap children;
+
+ ~XMLKeyLayout() {
+ properties.clear();
+ children.clear();
+// delete custom;
+ }
} *_XMLkeys;
/** Struct representing a parsed node */
@@ -261,7 +316,7 @@ public:
*
* @param filename Name of the file to load.
*/
- virtual bool loadFile(Common::String filename) {
+ bool loadFile(Common::String filename) {
Common::File *f = new Common::File;
if (!f->open(filename, Common::File::kFileReadMode))
@@ -283,7 +338,7 @@ public:
* i.e. if it can be freed safely after it's
* no longer needed by the parser.
*/
- virtual bool loadBuffer(const byte *buffer, uint32 size, bool disposable = false) {
+ bool loadBuffer(const byte *buffer, uint32 size, bool disposable = false) {
_text.loadStream(new MemoryReadStream(buffer, size, disposable));
_fileName = "Memory Stream";
return true;
@@ -293,7 +348,7 @@ public:
* The actual parsing function.
* Parses the loaded data stream, returns true if successful.
*/
- virtual bool parse();
+ bool parse();
/**
* Returns the active node being parsed (the one on top of
@@ -378,10 +433,8 @@ protected:
/**
* Skips spaces/whitelines etc. Returns true if any spaces were skipped.
- * Overload this if you want to make your parser depend on newlines or
- * whatever.
*/
- virtual bool skipSpaces() {
+ bool skipSpaces() {
if (!isspace(_text[_pos]))
return false;
@@ -492,6 +545,8 @@ protected:
*/
virtual void cleanup() {}
+
+private:
int _pos; /** Current position on the XML buffer. */
XMLStream _text; /** Buffer with the text being parsed */
Common::String _fileName;