Functions

src/roxml.c File Reference

source for libroxml.so More...

#include "roxml-internal.h"

Go to the source code of this file.

Functions

void ROXML_API roxml_release (void *data)
 memory cleanning function
char *ROXML_API roxml_get_content (node_t *n, char *buffer, int bufsize, int *size)
 content getter function
char *ROXML_API roxml_get_name (node_t *n, char *buffer, int size)
 name getter function
int ROXML_API roxml_get_text_nb (node_t *n)
 text node number getter function
node_t *ROXML_API roxml_get_text (node_t *n, int nth)
 text content getter function
int ROXML_API roxml_get_attr_nb (node_t *n)
 number of attribute getter function
node_t *ROXML_API roxml_get_attr (node_t *n, char *name, int nth)
 attribute getter function
void ROXML_API roxml_close (node_t *n)
 unload function
int ROXML_API roxml_get_chld_nb (node_t *n)
 chlds number getter function
node_t *ROXML_API roxml_get_chld (node_t *n, char *name, int nth)
 chld getter function
node_t *ROXML_API roxml_get_parent (node_t *n)
 parent getter function
int ROXML_API roxml_get_type (node_t *n)
 node type function
int ROXML_API roxml_get_node_position (node_t *n)
 node get position function
node_t *ROXML_API roxml_load_doc (char *filename)
 load function for files
node_t *ROXML_API roxml_load_buf (char *buffer)
 load function for buffers
node_t **ROXML_API roxml_xpath (node_t *n, char *path, int *nb_ans)
 exec path function
void ROXML_API roxml_del_node (node_t *n)
 node deletion function
void ROXML_API roxml_commit_changes (node_t *n, char *dest, char **buffer, int human)
 sync function
node_troxml_add_node (node_t *parent, int position, int type, char *name, char *value)
 add a node to the tree

Detailed Description

source for libroxml.so

This is the source file for lib libroxml.so

Author:
blunderer <blunderer@blunderer.org>
Date:
23 Dec 2008

Copyright (C) 2009 blunderer

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Definition in file roxml.c.


Function Documentation

roxml_add_node ( node_t parent,
int  position,
int  type,
char *  name,
char *  value 
)

add a node to the tree

this function add a new node to the tree. This will not update de buffer or file, only the RAM loaded tree

Parameters:
parent the parent node
position the position as a child of parent (0 for auto position at the end of children list)
type the type of node between ROXML_ATTR_NODE, ROXML_STD_NODE, ROXML_TXT_NODE, ROXML_PI_NODE, ROXML_CMT_NODE
name the name of the node (for ROXML_ATTR_NODE and ROXML_STD_NODE only)
value the text content (for ROXML_STD_NODE, ROXML_TXT_NODE, ROXML_CMT_NODE, ROXML_PI_NODE) or the attribute value (ROXML_ATTR_NODE)
Returns:
the new node
See also:
roxml_commit_changes
roxml_del_node

paramaters name and value depending on node type:

  • ROXML_STD_NODE take at least a node name. the paramter value is optional and represents the text content.
  • ROXML_TXT_NODE ignore the node name. the paramter value represents the text content.
  • ROXML_CMT_NODE ignore the node name. the paramter value represents the comment.
  • ROXML_PI_NODE ignore the node name. the paramter value represents the content of processing-instruction node.
  • ROXML_ATTR_NODE take an attribute name. and the attribute value as given by parameter value.

some examples to obtain this xml result file

<root>
 <!-- sample XML file -->
 <item id="42">
  <price> 
   24 
  </price>
 </item>
</root>
 #include <roxml.h>

 int main(void)
 {
        node_t * root = roxml_add_node(NULL, 0, ROXML_STD_NODE, "xml", NULL);
        node_t * tmp = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample XML file");
        tmp = roxml_add_node(root, 0, ROXML_STD_NODE, "item", NULL);
        roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
        tmp = roxml_add_node(tmp, 0, ROXML_STD_NODE, "price", "24");
        roxml_commit_changes(root, "/tmp/test.xml", NULL, 1);
        return 0;
 }

Or also:

 #include <roxml.h>

 int main(void)
 {
        node_t * root = roxml_add_node(NULL, 0, ROXML_STD_NODE, "xml", NULL);
        node_t * tmp = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample XML file");
        tmp = roxml_add_node(root, 0, ROXML_STD_NODE, "item", NULL);
        roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
        tmp = roxml_add_node(tmp, 0, ROXML_STD_NODE, "price", NULL);
        tmp = roxml_add_node(tmp, 0, ROXML_TXT_NODE, NULL, "24");
        roxml_commit_changes(root, "/tmp/test.xml", NULL, 1);
        return 0;
 }

Definition at line 558 of file roxml.c.

void ROXML_API roxml_close ( node_t n  ) 

unload function

This function clear a document and all the corresponding nodes It release all memory allocated during roxml_load_doc or roxml_load_file. All nodes from the tree are not available anymore.

Parameters:
n is any node of the tree to be cleaned
Returns:
void
See also:
roxml_load_doc
roxml_load_buf

Definition at line 356 of file roxml.c.

roxml_commit_changes ( node_t n,
char *  dest,
char **  buffer,
int  human 
)

sync function

this function sync changes to the given buffer or file in human or one-line format The tree will be processed starting with the root node 'n' and following with all its children. The tree will be dumped to a file if 'dest' is not null and contains a valid path. The tree will be dumped to a buffer if 'buffer' is not null the buffer is allocated by the library and a pointer to it will be stored into 'buffer'.

Parameters:
n the root node of the tree to write
dest the path to a file to write tree to
buffer the adress of a buffer where tre will be written
human 0 for one-line tree, or 1 for human format (using tabs, newlines...)

One should do:

 #include <roxml.h>

 int main(void)
 {
        node_t * root = roxml_add_node(NULL, 0, ROXML_STD_NODE, "xml", NULL);
        node_t * tmp = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample XML file");
        tmp = roxml_add_node(root, 0, ROXML_STD_NODE, "item", NULL);
        roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
        tmp = roxml_add_node(tmp, 0, ROXML_STD_NODE, "price", "24");
        roxml_commit_changes(root, "/tmp/test.xml", NULL, 1);
        return 0;
 }

to generate the following xml bloc:

<root>
 <!-- sample XML file -->
 <item id="42">
  <price> 
   24 
  </price>
 </item>
</root>

or also

 #include <roxml.h>

 int main(void)
 {
        node_t * root = roxml_add_node(NULL, 0, ROXML_STD_NODE, "xml", NULL);
        node_t * tmp = roxml_add_node(root, 0, ROXML_CMT_NODE, NULL, "sample XML file");
        tmp = roxml_add_node(root, 0, ROXML_STD_NODE, "item", NULL);
        roxml_add_node(tmp, 0, ROXML_ATTR_NODE, "id", "42");
        tmp = roxml_add_node(tmp, 0, ROXML_STD_NODE, "price", "24");
        roxml_commit_changes(root, "/tmp/test.xml", NULL, 0);
        return 0;
 }

to generate the following xml bloc:

<root><!-- sample XML file --><item id="42"><price>24</price></item></root>

Definition at line 538 of file roxml.c.

roxml_del_node ( node_t n  ) 

node deletion function

this function delete a node from the tree. The node is not really deleted from the file or buffer until the roxml_commit_changes is called.

Parameters:
n the node to delete
Returns:

Definition at line 521 of file roxml.c.

char *ROXML_API roxml_get_attr ( node_t n,
char *  name,
int  nth 
)

attribute getter function

This function get the nth attribute of a node. User should roxml_release the returned buffer when no longer needed.

Parameters:
n is one node of the tree
name is the name of the child to get
nth the id of attribute to read
Returns:
the attribute corresponding to name or id (if both are set, name is used)

example: given the following xml file

<xml>
 <product id="42" class="item"/>
</xml>
 #include <stdio.h>
 #include <roxml.h>

 int main(void)
 {
        node_t * root = roxml_load_doc("/tmp/doc.xml");
        node_t * item1 = roxml_get_chld(root, NULL, 0);
        node_t * item2 = roxml_get_chld(item1, NULL, 0);

        node_t * attr_by_name = roxml_get_attr(item2, "id", 0);
        node_t * attr_by_nth = roxml_get_attr(item2, NULL, 0);

        // here attr_by_name == attr_by_nth
        if(attr_by_name == attr_by_nth) {
                printf("Nodes are equal\n");
        }

        roxml_close(root);
        return 0;
 }

Definition at line 324 of file roxml.c.

int ROXML_API roxml_get_attr_nb ( node_t n  ) 

number of attribute getter function

This function returns the number of attributes for a given node

Parameters:
n is one node of the tree
Returns:
the number of attributes in node

Definition at line 309 of file roxml.c.

node_t *ROXML_API roxml_get_chld ( node_t n,
char *  name,
int  nth 
)

chld getter function

This function returns a given chld of a node etheir by name, or the nth child.

Parameters:
n is one node of the tree
name is the name of the child to get
nth is the id of the chld to get
Returns:
the chld corresponding to name or id (if both are set, name is used)
See also:
roxml_get_chld_nb

example: given the following xml file

<xml>
 <item1/>
 <item2/>
 <item3/>
</xml>
 #include <stdio.h>
 #include <roxml.h>

 int main(void)
 {
        node_t * root = roxml_load_doc("/tmp/doc.xml");
        
        node_t * child_by_name = roxml_get_chld(root, "item2", 0);
        node_t * child_by_nth = roxml_get_chld(root, NULL, 2);

        // here child_by_name == child_by_nth
        if(child_by_name == child_by_nth) {
                printf("Nodes are equal\n");
        } 

        roxml_close(root);
        return 0;
 }

Definition at line 392 of file roxml.c.

int ROXML_API roxml_get_chld_nb ( node_t n  ) 

chlds number getter function

This function return the number of chlidren for a given node

Parameters:
n is one node of the tree
Returns:
the number of chlildren

Definition at line 376 of file roxml.c.

char *ROXML_API roxml_get_content ( node_t n,
char *  buffer,
int  bufsize,
int *  size 
)

content getter function

This function returns a pointer with the concatenation of text content of a node (children are NOT included as text).; if the returned pointer is NULL then the node was empty. returned string should be freed using roxml_release when not used anymore

Parameters:
n is one node of the tree
buffer is the buffer where result will be written or NULL for internal allocation
bufsize the size if using custom buffer
size the actual size of result. if buffer was not NULL and size == buf_size, then given buffer was too small
Returns:
the text content
See also:
roxml_release

Definition at line 104 of file roxml.c.

char *ROXML_API roxml_get_name ( node_t n,
char *  buffer,
int  size 
)

name getter function

This function return the name of the node or fill the current buffer with it if not NULL. if name is NULL, the function will allocate a buffer that user should free using roxml_release when no longer needed. Be carreful as if your buffer is too short for the returned string, it will be truncated

Parameters:
n is one node of the tree
buffer a buffer pointer or NULL if has to be auto allocated
size the size of buffer pointed by buffer if not NULL
Returns:
the name of the node (return our buffer pointer if it wasn't NULL)
See also:
roxml_release

Definition at line 195 of file roxml.c.

roxml_get_node_position ( node_t n  ) 

node get position function

This function tells the index of a node between all its siblings homonyns.

Parameters:
n is the node to test
Returns:
the postion between 1 and N

Definition at line 434 of file roxml.c.

node_t *ROXML_API roxml_get_parent ( node_t n  ) 

parent getter function

This function returns the parent of a given node

Parameters:
n is one node of the tree
Returns:
the parent node

Definition at line 419 of file roxml.c.

roxml_get_text ( node_t n,
int  nth 
)

text content getter function

this function return the text content of a node as a TEXT nodes the content of the text node can be read using the roxml_get_content function

Parameters:
n the node that contains text
nth the nth text node to retrieve
Returns:
the text node or NULL
See also:
roxml_get_text_nb
roxml_get_content

example: given this xml file:

<xml>
  This is
  <item/>
  an example
  <item/>
  of text nodes
</xml>
 #include <stdio.h>
 #include <roxml.h>

 int main(void)
 {
        int len;
        node_t * root = roxml_load_doc("/tmp/doc.xml");
        node_t * item = roxml_get_chld(root, NULL, 0);

        node_t * text = roxml_get_text(item, 0);
        char * text_content = roxml_get_content(text, NULL, 0, &len);
        // HERE text_content is equal to "This is"
        printf("text_content = '%s'\n", text_content);

        text = roxml_get_text(item, 1);
        text_content = roxml_get_content(text, NULL, 0, &len);
        // HERE text_content is equal to "an example"
        printf("text_content = '%s'\n", text_content);

        text = roxml_get_text(item, 2);
        text_content = roxml_get_content(text, NULL, 0, &len);
        // HERE text_content is equal to "of text nodes"
        printf("text_content = '%s'\n", text_content);

        roxml_close(item);
        return 0;
 }

Definition at line 288 of file roxml.c.

roxml_get_text_nb ( node_t n  ) 

text node number getter function

this function return the number of text nodes in a standard node

Parameters:
n the node to search into
Returns:
the number of text node
See also:
roxml_get_text

Definition at line 273 of file roxml.c.

int roxml_get_type ( node_t n  ) 

node type function

node type getter function

This function tells if a node is an ROXML_ATTR_NODE, ROXML_TXT_NODE, ROXML_PI_NODE, ROXML_CMT_NODE or ROXML_STD_NODE.

Parameters:
n is the node to test
Returns:
the node type

this function return the node type : ROXML_ARG ROXML_VAL

Parameters:
n the node to return type for
Returns:
the node type

Definition at line 429 of file roxml.c.

node_t *ROXML_API roxml_load_buf ( char *  buffer  ) 

load function for buffers

This function load a document by parsing all the corresponding nodes. The document must be contained inside the char * buffer given in parameter and remain valid until the roxml_close() function is called

Parameters:
buffer the XML buffer to load
Returns:
the root node or NULL
See also:
roxml_close
roxml_load_doc

Definition at line 473 of file roxml.c.

node_t *ROXML_API roxml_load_doc ( char *  filename  ) 

load function for files

This function load a file document by parsing all the corresponding nodes

Parameters:
filename the XML document to load
Returns:
the root node or NULL
See also:
roxml_close
roxml_load_buf

Definition at line 461 of file roxml.c.

roxml_release ( void *  data  ) 

memory cleanning function

This function release the memory pointed by pointer just like free would but for memory allocated with roxml_malloc. Freeing a NULL pointer won't do anything. roxml_release also allow you to remove all previously allocated datas by using RELEASE_ALL as argument. You can also safely use RELEASE_LAST argument that will release the previously allocated var within the current thread (making this function thread safe). if using roxml_release on a variable non roxml_mallocated, nothing will happen

Parameters:
data the pointer to delete or NULL or RELEASE_ALL or RELEASE_LAST
Returns:
void

Definition at line 27 of file roxml.c.

roxml_xpath ( node_t n,
char *  path,
int *  nb_ans 
)

exec path function

This function return a node set (table of nodes) corresponding to a given xpath. resulting node table should be roxml_release when not used anymore

Parameters:
n is one node of the tree
path the xpath to use
nb_ans the number of results
Returns:
the node table or NULL

handled xpath are

===Relative xpath:===
 * _"n0"_

 ===Absolute xpath:===
 * _"/n0"_

 ===Special nodes:===
 * _"`*`"_
 * _"node()"_
 * _"text()"_
 * _"comment()"_
 * _"processing-instruction()"_

 ===Conditions:===
 * Attribute string value: _"/n0`[`@a=value]"_
 * Attribute int value: _"/n0`[`@a=value]"_
 * Attribute int value: _"/n0`[`@a!=value]"_
 * Attribute int value: _"/n0`[`@a<value]"_
 * Attribute int value: _"/n0`[`@a>value]"_
 * Attribute int value: _"/n0`[`@a<=value]"_
 * Attribute int value: _"/n0`[`@a>=value]"_
 * Node position: _"/n0`[`first()]"_
 * Node position: _"/n0`[`first()+2]"_
 * Node position: _"/n0`[`last()]"_
 * Node position: _"/n0`[`last()-3]"_
 * Node position: _"/n0`[`position() = 0]"_
 * Node position: _"/n0`[`position() != 0]"_
 * Node position: _"/n0`[`position() > 1]"_
 * Node position: _"/n0`[`position() < 2]"_
 * Node position: _"/n0`[`position() >= 1]"_
 * Node position: _"/n0`[`position() <= 2]"_
 * Node position: _"/n0`[`2]"_
 * Other xpath: _"/n0`[`n1/@attr]"_

 ===Shorten xpath for:===
 * Children: _"/n0/n1/n2"_
 * Attributes: _"/n0/n1/@a"_
 * Descendent or self::node(): _"/n0//n5"_
 * Parent: _"/n0/n1/../n1"_
 * Self: _"/n0/n1/."_

 ===Full xpath for:===
 * Nodes: _"/n0/n1/child::a"_
 * Attributes: _"/n0/n1/attribute::a"_
 * Descendent or self: _"/n0/descendant-or-self::n5"_
 * Parent: _"/child::n0/child::n1/parent::/n1"_
 * Self: _"/child::n0/child::n1/self::"_
 * Preceding: _"preceding::n1"_
 * Following: _"following::n1"_
 * Ancestor: _"ancestor::n2"_
 * Ancestor-or-self: _"ancestor-or-self::n2"_

Definition at line 482 of file roxml.c.