xmlparser.h

   1 #ifndef _XMLPARSER_H
   2 #define _XMLPARSER_H
   3 #include "myarray.h"
   4 #include "mystring.h"
   5
   6 /// A value representing the boolean \a false.
   7 #define FALSE 0
   8 /// A value representing the boolean \a true.
   9 #define TRUE !FALSE
  10
  11 /**
  12  * Struct to hold all the information regarding an XML tag.
  13  */
  14 typedef struct XmlTag {
  15      /// name of the tag.
  16     MString             name;
  17      /// list containing all the children of the tag.
  18     MArray              children;
  19      /// value of the tag.
  20     MString             value;
  21      /// parent of the tag.
  22     struct XmlTag       *parent;
  23 } *XmlTag;
  24
  25 /**
  26  * Creates a new tag.
  27  * \param parent what will be the parent of the tag. May be NULL.
  28  * \return a new XmlTag with the specified parent.
  29  */
  30 XmlTag xml_tag_new(XmlTag parent);
  31
  32 /**
  33  * Frees the memory associated with the tag.
  34  * This will free all the memory associated with the tag. So all its members will also be freed.
  35  * However, none of its children will be freed. To achieve that, use xml_tree_free().
  36  * \param tag the tag to be freed
  37  * \see xml_tree_free(XmlTag)
  38  */
  39 void xml_tag_free(XmlTag tag);
  40
  41 /**
  42  * Prints a tree of XmlTag's.
  43  * This will print a tree of [XmlTag]s in a rather strange way, here's an example:
  44  * \par Input:
  45  * \verbatim
  46 <test>
  47     <tagone>
  48         somevalue
  49     </tagone>
  50     <tagtwo />
  51 </test>
  52 \endverbatim
  53  *
  54  * \par Output:
  55  * \verbatim
  56 test; children: 2;
  57     tagone; value: somevalue;
  58     tagtwo;
  59 \endverbatim
  60  *
  61  * \param tag the root XmlTag of the tree to be printed
  62  * \note \a tag, being regarded as the root of the tree, will not actually be printed.
  63  */
  64 void xml_tree_print(XmlTag tag);
  65
  66 /**
  67  * Prints an error message, including where the error occurred.
  68  * \param message the message to print
  69  * \param line the line at which the error occurred
  70  * \param col the column at which the error occurred
  71  */
  72 void xml_error(const char *message, unsigned int line, int col);
  73
  74 /**
  75  * Frees an entire tree of XmlTag's.
  76  * This function works recursively, by calling itself for every child of \a root,
  77  * right before calling xml_tag_free(XmlTag) with \a root as its argument.
  78  * \param root the root of the tree to be freed.
  79  * \see xml_tag_free(XmlTag)
  80  */
  81 void xml_tree_free(XmlTag root);
  82
  83 /**
  84  * Parses the file at \a path_to_file.
  85  * \param path_to_file a string that will be used as the path to the file to be parsed
  86  * \return the root XmlTag of the parsed file, or NULL if an error occurred.
  87  */
  88 XmlTag xml_parse(char *path_to_file);
  89
  90 /**
  91  * This global variable will hold the error status ID as defined in XML_STATUS_ENUM after an error occurs.
  92  */
  93 int XML_STATUS;
  94
  95 /**
  96  * List of error IDs.
  97  */
  98 enum XML_STATUS_ENUM {
  99     /// No error.
 100     XML_OK,
 101     /// A tag has been left unclosed after parsing the entire file.
 102     XML_UNCLOSED_TAGS,
 103     /**
 104      * A value has been encountered without having any open tags.
 105      * \par Example:
 106 \verbatim
 107 some value <-- this value isn't in any tag.
 108 <tag>
 109 </tag>
 110 some value <-- this value isn't in any tag.
 111 \endverbatim
 112      */
 113     XML_VALUE_NO_PARENT,
 114     /**
 115      * An invalid character has been encountered. It could be a < when we're defining a tag.
 116      * \par Example:
 117      * \verbatim
 118 <tagname<bla> <-- This tag has a <!
 119 \endverbatim
 120      */
 121     XML_INVALID_CHAR,
 122     /** A tag has been closed that wasn't actually the current open tag.
 123      * \par Example:
 124      * \verbatim
 125 <one>
 126 <two>
 127 </one> <-- one is not the currently opened tag. two is.
 128 </two>
 129 \endverbatim
 130      */
 131     XML_INVALID_CLOSING,
 132     /// A tag has been opened without a name.
 133     XML_UNNAMED_TAG,
 134     /// An I/O error has occurred.
 135     XML_FILE_ERROR
 136 };
 137 #endif