FemtoXML v. 0.96 1. About 1.1 License 1.2 Authors 1.3 Limitations 1.4 Implementation and structure 2 Compiling and linking 2.1 Building the library 2.2 Linking with the library 3. Function Reference 3.1 Types 3.2 Document Functions 3.3 Element functions 4. Examples 1. About FemtoXML is a small XML DOM parser written i C to suite the author's personal needs for XML parsing. There is also a wrapper for C++ kept up to date with the C library called FemtoXML_CPP. It's sufficiently fast for most applications. It loads a fairly advanced XML file, ~25k lines 1.6MB, in just below 0.2 seconds on a 1.67 GHz Intel core. This when compiled with GCC 4.1.3 using O3 optimizations. The same file then consumes about 5 MB RAM as a DOM structure, with an additional 1.6 MB during loading. For the latest version of FemtoXML check its website at http://nurd.se/~noname/femtoxml/ 1.1 License Gnu Public License v. 3, see license.txt for more details. 1.2 Authors Fredrik Hultin email: noname@ the same domain as the website 1.3 Limitations Although fairly competent, FemtoXML doesn't implement namespaces or DTDs. Namespaces are ignored but DTD/DOCTYPES and declarations are parsed and added to the DOM structure as FMXL_TYPE_DOCTYPE and FXML_TYPE_DECLARATION respectively. Limitations to string length, document depth etc. can be set in the file femtoxmli.h (note the "i") before compiling the library. Default limits: Type Limit Name String length 65536 chars FXML_MAXSTRLEN Document depth 65536 elements FXML_MAXDEPTH Document breadth 65536 elements FXML_MAXBREADTH Number of attributes 65536 attr. FXML_MAXATTRIBS Message length 512 chars FXML_MAX_MESSAGELEN See the comments in femtoxmli.h file for more information. 1.4 Implementation and structure The project uses a fairly standard directory structure. The source goes in src/ and the headers in include/. 2. Compiling and linking To build the project you could either build it as a library using the provided cmake project file, or embed femtoxml into your project. FemtoXML has no external dependencies part from the standard c library. 2.1 Building the library To compile the library using the provided cmake project file, create a directory anywhere on your system where you want to build femtoxml, eg. /tmp/build. mkdir /tmp/build cd /tmp/build Run cmake with the path you downloaded and extracted femtoxml to. cmake ~/downloads/femtoxml-XX Then run make while still in the temporary build directory you created. make Once the compilation finishes (which it will in about 2 seconds if your system isn't painfully slow), run make install as root to install the library. sudo make install I did add some initial support for building distribution packages, like Debian .deb-files, in the cmake project file but at the time of writing this is a new and experimental feature of cmake. Consult the cmake documentation if you want to try this out. 2.2 Linking with the library To link FemtoXML with your project you can use the pkg-config files cmake should have installed on your system. To get the needed cflags and ldflags use pkg-config --cflags femtoxml pkg-config --libs femtoxml As an example, if you have a file called myxmlparser.c, you can compile and link that with gcc and femtoxml using the command gcc `pkg-config --cflags femtoxml` `pkg-config --libs femtoxml` myxmlparser.c -o myxmlparser 3. Function Reference 3.1 Types Element types FXML_TYPE_ROOT, FXML_TYPE_TEXT, FXML_TYPE_ELEMENT, FXML_TYPE_ATTRIBUTE, FXML_TYPE_ATTRIBUTE_VAL, FXML_TYPE_COMMENT, FXML_TYPE_DECLARATION, FXML_TYPE_DOCTYPE, FXML_TYPE_ANY, FXML_TYPE_NONE Message types FXML_MSG_ERROR, FXML_MSG_WARNING, FXML_MSG_INFO, FXML_MSG_DEBUG Boolean values FALSE = 0 TRUE = 1 3.2 Document Functions --------------------------------------------------- fxml_document* fxml_newDocument() --------------------------------------------------- Creates a new, empty fxml_document. Returns A pointer to the new element. --------------------------------------------------- void fxml_freeDocument(fxml_document* document) --------------------------------------------------- Frees a document structure from memory. document The document to free. --------------------------------------------------- fxml_document* fxml_load(const char* fileName) --------------------------------------------------- Loads and parses an XML file from the file system. fileName A file to load. Returns A new document structure or NULL on complete failure. --------------------------------------------------- fxml_document* fxml_loadBuffer(const unsigned char* buffer, long len) --------------------------------------------------- Parses a memory buffer. buffer A buffer to parse. len The length of the buffer Returns A new document structure or NULL on complete failure 3.3 Element functions --------------------------------------------------- fxml_element* fxml_newElement(int type) --------------------------------------------------- Returns a pointer to a new, empty fxml_element. type The element type, see element types for more information. Returns The new element. --------------------------------------------------- void fxml_freeElement(fxml_element* element) --------------------------------------------------- Frees an element structure from RAM. element The element to free --------------------------------------------------- fxml_element* fxml_addAttribute(fxml_element* element, const char* name, const char* val) --------------------------------------------------- Adds an attribute to an element. element The element you want the attribute added to name The name of the attribute val The value of the attribute, or NULL for none. Returns A pointer to the new attribute --------------------------------------------------- fxml_element* fxml_addElement(fxml_element* element, const char* name) --------------------------------------------------- Adds a sub-element to a given element. element The element you want the subelement added to name The name of the new element Returns A pointer to the subelement. --------------------------------------------------- fxml_element* fxml_addText(fxml_element* element, const char* text) --------------------------------------------------- Adds text to a given element. text element The element you want the text added to text The text to add to the element. Returns A pointer to the new text. --------------------------------------------------- fxml_element* fxml_addDeclaration(fxml_element* element, const char* name) --------------------------------------------------- Adds a document declaration to the given element. element The element you want the text added to. name The name of the declaration. Returns A pointer to the declaration. --------------------------------------------------- fxml_element* fxml_addComment(fxml_element* element, const char* text) --------------------------------------------------- Adds a comment to the given element. element The element you want the comment added to. text The text you want in the comment. Returns A pointer to the comment. --------------------------------------------------- fxml_element* fxml_addDoctype(fxml_element* doctype, const char* name) --------------------------------------------------- Adds a doctype to the given element. element The element you want the doctype added to. name The name you want the doctype to have. Returns A pointer to the doctype. --------------------------------------------------- fxml_element* fxml_get(fxml_element* root, const char* val, int type, int index) --------------------------------------------------- Get a specific element from within another sub-element meeting the search criteria. Where the first "val" would be index 0, the second index 1 etc. if type is FXML_TYPE_ANY. root The element you want the sub-element from. val The value (name) of the element you want to get, or NULL for any. type The type of element you want to get, see element types (FXML_TYPE_ANY for any). index the index of the element you want to get (0 for the first). Returns A pointer to the specified element, or NULL if the search failed. --------------------------------------------------- int fxml_count(fxml_element* element, const char* val, int type) --------------------------------------------------- Count the number of elements meeting the search criteria. Would return 3 if type FXML_TYPE_ANY and val is "val". element The element you want to search within. val The value you want to count. --------------------------------------------------- void fxml_setVal(fxml_element* element, const char* val) --------------------------------------------------- Sets the given element to a given value. Note that the value is the name. to element A pointer to the element you want to set the value of. --------------------------------------------------- void fxml_print(fxml_element* element) --------------------------------------------------- Prints a given element and all of its sub-elements as XML to stdout. element The element to print. --------------------------------------------------- int fxml_save(fxml_document* document, const char* fileName) --------------------------------------------------- Saves the given document as an XML file. document The document to save. fileName The filename to save the document to. Returns 0 / FALSE if the save fails or, 1 / TRUE if the save succeeds. --------------------------------------------------- void fxml_printSimple(fxml_element* element) --------------------------------------------------- Prints a simple representation of the data structure of an element and its sub-elements to the screen for debugging. element The root element. --------------------------------------------------- int fxml_getNextElement(fxml_element** element) --------------------------------------------------- Sets the given element-pointer-pointer to a pointer to the next element in the list after the given element. Good for looping through a list of elements like such: fxml_element* element = document->elements; do{ /* This happens once for each element in the list with "element" pointing to the current element */ }while(fxml_getNextElement(&element)); Note that you shouldn't give fxml_getNextElement something like &document->elements or &element->next directly, since then it would re-point that pointer, effectively destroying the linked list that composes the XML document. Also note that this function isn't really needed for normal operation and is mostly used internally by the library, which is the reason for its arguably "hackish" nature. element The first element Returns 0 / FALSE if the current element has no next element or 1 / TRUE if it has. --------------------------------------------------- const char* fxml_getTypeName(unsigned int type) --------------------------------------------------- Returns a string containing the name of a given element type. type One of the element types described in the types section. Returns A corresponding string to a element type ("Rootnode", "Text", "Element", etc.) or "Unknown" if an invalid type is given. --------------------------------------------------- void fxml_ePrint(int type, const char *format, ...) --------------------------------------------------- Prints a message printf-style to the error message callback (which defaults to stdout). int i; for(i = 0; i < 200; i++){ fxml_ePrintf(FXML_MSG_WARNING, "Get off my property! I've already warned you %i times before!", i); } type One of the message types described in the types section. format, ... printf-style macro --------------------------------------------------- void fxml_setCallback(fxml_callback_fn newCb, void* data) --------------------------------------------------- Sets a custom message callback. The message callback is called every time FemtoXML wants to communicate anything, e.g. an error or a warning. void myCallback(fxml_msg* msg, void* data){ printf("Message from FemtoXML: %s (%d): %s\n", msg->typeName, msg->type, msg->msg); } ... fxml_setCallback(myCallback, NULL); newCb A pointer to your custom message handler, or NULL to silence FemtoXML completely. data Some custom data you want sent along to the callback when it's called, or NULL. 4. Examples See the examples-directory in the femtoxml project root.