Simple_XML

Data Structures | Typedefs | Enumerations | Functions
Simple_XML
Eina » Tools

Simplistic relaxed SAX-like XML parser. More...

## Data Structures
struct | _Eina_Simple_XML_Attribute
struct | _Eina_Simple_XML_Node
struct | _Eina_Simple_XML_Node_Tag
struct | _Eina_Simple_XML_Node_Data

## Typedefs
typedef struct _Eina_Simple_XML_Node | Eina_Simple_XML_Node
typedef struct _Eina_Simple_XML_Node_Tag | Eina_Simple_XML_Node_Root
typedef struct _Eina_Simple_XML_Node_Tag | Eina_Simple_XML_Node_Tag
typedef struct _Eina_Simple_XML_Node_Data | Eina_Simple_XML_Node_Data
typedef struct _Eina_Simple_XML_Node_Data | Eina_Simple_XML_Node_CData
typedef struct _Eina_Simple_XML_Node_Data | Eina_Simple_XML_Node_Processing
typedef struct _Eina_Simple_XML_Node_Data | Eina_Simple_XML_Node_Doctype
typedef struct _Eina_Simple_XML_Node_Data | Eina_Simple_XML_Node_Doctype_Child
typedef struct _Eina_Simple_XML_Node_Data | Eina_Simple_XML_Node_Comment
typedef struct _Eina_Simple_XML_Attribute | Eina_Simple_XML_Attribute
typedef enum _Eina_Simple_XML_Node_Type | Eina_Simple_XML_Node_Type
typedef enum _Eina_Simple_XML_Type | Eina_Simple_XML_Type
typedef Eina_Bool(* | Eina_Simple_XML_Cb) (void *data, Eina_Simple_XML_Type type, const char *content, unsigned offset, unsigned length)
typedef Eina_Bool(* | Eina_Simple_XML_Attribute_Cb) (void *data, const char *key, const char *value)

## Enumerations
enum | _Eina_Simple_XML_Node_Type { EINA_SIMPLE_XML_NODE_ROOT = 0, EINA_SIMPLE_XML_NODE_TAG, EINA_SIMPLE_XML_NODE_DATA, EINA_SIMPLE_XML_NODE_CDATA, EINA_SIMPLE_XML_NODE_PROCESSING, EINA_SIMPLE_XML_NODE_DOCTYPE, EINA_SIMPLE_XML_NODE_COMMENT, EINA_SIMPLE_XML_NODE_DOCTYPE_CHILD }
enum | _Eina_Simple_XML_Type { EINA_SIMPLE_XML_OPEN = 0, EINA_SIMPLE_XML_OPEN_EMPTY, EINA_SIMPLE_XML_CLOSE, EINA_SIMPLE_XML_DATA, EINA_SIMPLE_XML_CDATA, EINA_SIMPLE_XML_ERROR, EINA_SIMPLE_XML_PROCESSING, EINA_SIMPLE_XML_DOCTYPE, EINA_SIMPLE_XML_COMMENT, EINA_SIMPLE_XML_IGNORED, EINA_SIMPLE_XML_DOCTYPE_CHILD }
| a simple XML type. More...

## Functions
Eina_Bool | eina_simple_xml_parse (const char *buf, unsigned buflen, Eina_Bool strip, Eina_Simple_XML_Cb func, const void *data)
| Parse a section of XML string text. More...
const char * | eina_simple_xml_tag_attributes_find (const char *buf, unsigned buflen)
| Given the contents of a tag, find where the attributes start. More...
Eina_Bool | eina_simple_xml_attributes_parse (const char *buf, unsigned buflen, Eina_Simple_XML_Attribute_Cb func, const void *data)
| Given a buffer with xml attributes, parse them to key=value pairs. More...
Eina_Bool | eina_simple_xml_attribute_w3c_parse (const char *buf, Eina_Simple_XML_Attribute_Cb func, const void *data)
| Given a buffer with the xml value of an attributes, parse them to key:value pairs. More...
Eina_Simple_XML_Attribute * | eina_simple_xml_attribute_new (Eina_Simple_XML_Node_Tag *parent, const char *key, const char *value)
| Create (and append) new attribute to tag. More...
void | eina_simple_xml_attribute_free (Eina_Simple_XML_Attribute *attr)
| Remove attribute from parent and delete it. More...
Eina_Simple_XML_Node_Tag * | eina_simple_xml_node_tag_new (Eina_Simple_XML_Node_Tag *parent, const char *name)
| Create new tag. More...
void | eina_simple_xml_node_tag_free (Eina_Simple_XML_Node_Tag *tag)
| Remove tag from parent and delete it. More...
Eina_Simple_XML_Node_Data * | eina_simple_xml_node_data_new (Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length)
| Create new data. More...
void | eina_simple_xml_node_data_free (Eina_Simple_XML_Node_Data *node)
| Remove data from parent and delete it. More...
Eina_Simple_XML_Node_CData * | eina_simple_xml_node_cdata_new (Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length)
| Create new cdata. More...
void | eina_simple_xml_node_cdata_free (Eina_Simple_XML_Node_Data *node)
| Remove cdata from parent and delete it. More...
Eina_Simple_XML_Node_Doctype_Child * | eina_simple_xml_node_doctype_child_new (Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length)
| Create new doctype child. More...
void | eina_simple_xml_node_doctype_child_free (Eina_Simple_XML_Node_Data *node)
| Remove doctype child from parent and delete it. More...
Eina_Simple_XML_Node_Processing * | eina_simple_xml_node_processing_new (Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length)
| Create new processing. More...
void | eina_simple_xml_node_processing_free (Eina_Simple_XML_Node_Data *node)
| Remove processing from parent and delete it. More...
Eina_Simple_XML_Node_Doctype * | eina_simple_xml_node_doctype_new (Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length)
| Create new doctype. More...
void | eina_simple_xml_node_doctype_free (Eina_Simple_XML_Node_Data *node)
| Remove doctype from parent and delete it. More...
Eina_Simple_XML_Node_Comment * | eina_simple_xml_node_comment_new (Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length)
| Create new comment. More...
void | eina_simple_xml_node_comment_free (Eina_Simple_XML_Node_Data *node)
| Remove comment from parent and delete it. More...
Eina_Simple_XML_Node_Root * | eina_simple_xml_node_load (const char *buf, unsigned buflen, Eina_Bool strip)
| Load a XML node tree based on the given string. More...
void | eina_simple_xml_node_root_free (Eina_Simple_XML_Node_Root *root)
| Free node tree build with eina_simple_xml_node_load() More...
char * | eina_simple_xml_node_dump (Eina_Simple_XML_Node *node, const char *indent)
| Converts the node tree under the given element to a XML string. More...

## Detailed Description

Simplistic relaxed SAX-like XML parser.

This parser is far from being compliant with XML standard, but will do for most XMLs out there. If you know that your format is simple and will not vary in future with strange corner cases, then you can use it safely.

The parser is SAX like, that is, it will tokenize contents and call you back so you can take some action. No contents are allocated during this parser work and it's not recursive, so you can use it with a very large document without worries.

It will not validate the document anyhow, neither it will create a tree hierarchy. That's up to you.

Accordingly to XML, open tags may contain attributes. This parser will not tokenize this. If you want you can use eina_simple_xml_tag_attributes_find() and then eina_simple_xml_attributes_parse().

For more information, see this example.

## Typedef Documentation

## ◆ Eina_Simple_XML_Node_Doctype_Child

typedef struct _Eina_Simple_XML_Node_Data Eina_Simple_XML_Node_Doctype_Child

Since
  1.8

## Enumeration Type Documentation

## ◆ _Eina_Simple_XML_Node_Type

enum _Eina_Simple_XML_Node_Type

Enumerator
EINA_SIMPLE_XML_NODE_DOCTYPE_CHILD | Since 1.8

## ◆ _Eina_Simple_XML_Type

enum _Eina_Simple_XML_Type

a simple XML type.

Enumerator
EINA_SIMPLE_XML_OPEN | <tag attribute="value">
EINA_SIMPLE_XML_OPEN_EMPTY | <tag attribute="value" />
EINA_SIMPLE_XML_CLOSE | </tag>
EINA_SIMPLE_XML_DATA | tag text data
EINA_SIMPLE_XML_CDATA | <![CDATA[something]]>
EINA_SIMPLE_XML_ERROR | error contents
EINA_SIMPLE_XML_PROCESSING | <?xml ... ?> <?php .. ?>
EINA_SIMPLE_XML_DOCTYPE | <!DOCTYPE html
EINA_SIMPLE_XML_COMMENT | <!– something –>
EINA_SIMPLE_XML_IGNORED | whatever is ignored by parser, like whitespace
EINA_SIMPLE_XML_DOCTYPE_CHILD | <!DOCTYPE_CHILD Since 1.8

## Function Documentation

## ◆ eina_simple_xml_parse()

Eina_Bool eina_simple_xml_parse | ( | const char * | buf,
|  | unsigned | buflen,
|  | Eina_Bool | strip,
|  | Eina_Simple_XML_Cb | func,
|  | const void * | data
| ) |  |

Parse a section of XML string text.

Parameters

  buf | the input string. May not contain \0 terminator.
  buflen | the input string size.
  strip | whenever this parser should strip leading and trailing whitespace. These whitespace will still be issued, but as type EINA_SIMPLE_XML_IGNORED.
  func | what to call back while parse to do some action. The first parameter is the given user data, the second is the token type, the third is the pointer to content start (it's not a NULL terminated string!), the forth is where this content is located inside buf (does not include tag start, for instance "<!DOCTYPE value>" the offset points at "value"), the fifth is the size of the content. Whenever this function return EINA_FALSE the parser will abort.
  data | what to give as context to func.

Returns
  EINA_TRUE on success or EINA_FALSE if it was aborted by user or parsing error.

## ◆ eina_simple_xml_tag_attributes_find()

const char* eina_simple_xml_tag_attributes_find | ( | const char * | buf,
|  | unsigned | buflen
| ) |  |

Given the contents of a tag, find where the attributes start.

Parameters

  buf | the input string. May not contain \0 terminator.
  buflen | the input string size.

Returns
  pointer to the start of attributes, it can be used to feed eina_simple_xml_attributes_parse(). `NULL` is returned if no attributes were found.

The tag contents is returned by eina_simple_xml_parse() when type is EINA_SIMPLE_XML_OPEN or EINA_SIMPLE_XML_OPEN_EMPTY.

## ◆ eina_simple_xml_attributes_parse()

Eina_Bool eina_simple_xml_attributes_parse | ( | const char * | buf,
|  | unsigned | buflen,
|  | Eina_Simple_XML_Attribute_Cb | func,
|  | const void * | data
| ) |  |

Given a buffer with xml attributes, parse them to key=value pairs.

Parameters

  buf | the input string. May not contain \0 terminator.
  buflen | the input string size.
  func | what to call back while parse to do some action. The first parameter is the given user data, the second is the key (null-terminated) and the last is the value (null terminated). These strings should not be modified and reference is just valid until the function return.
  data | data to pass to the callback function.

Returns
  EINA_TRUE on success or EINA_FALSE if it was aborted by user or parsing error.

## ◆ eina_simple_xml_attribute_w3c_parse()

Eina_Bool eina_simple_xml_attribute_w3c_parse | ( | const char * | buf,
|  | Eina_Simple_XML_Attribute_Cb | func,
|  | const void * | data
| ) |  |

Given a buffer with the xml value of an attributes, parse them to key:value pairs.

Parameters

  buf | the input string. Need to contain \0 terminator.
  func | what to call back while parse to do some action. The first parameter is the given user data, the second is the key (null-terminated) and the last is the value (null terminated). These strings should not be modified and reference is just valid until the function return.
  data | data to pass to the callback function.

Returns
  EINA_TRUE on success or EINA_FALSE if it was aborted by user or parsing error.

Since
  1.14

## ◆ eina_simple_xml_attribute_new()

Eina_Simple_XML_Attribute* eina_simple_xml_attribute_new | ( | Eina_Simple_XML_Node_Tag * | parent,
|  | const char * | key,
|  | const char * | value
| ) |  |

Create (and append) new attribute to tag.

Parameters

  parent | if provided, will be set in the resulting structure as well as the attribute will be appended to attributes list.
  key | Null-terminated string. Must not be `NULL`.
  value | Null-terminated string. If `NULL`, the empty string will be used.

Returns
  Newly allocated memory or `NULL` on error. This memory should be released with eina_simple_xml_attribute_free() or indirectly with eina_simple_xml_node_tag_free().

References eina_inlist_append(), EINA_INLIST_GET, EINA_MAGIC_SET, eina_mempool_malloc(), eina_stringshare_add(), ERR, and efl::eo::parent.

## ◆ eina_simple_xml_attribute_free()

void eina_simple_xml_attribute_free | ( | Eina_Simple_XML_Attribute * | attr | ) |

Remove attribute from parent and delete it.

Parameters

  attr | attribute to release memory.

References EINA_INLIST_GET, eina_inlist_remove(), EINA_MAGIC_NONE, EINA_MAGIC_SET, eina_mempool_free(), and eina_stringshare_del().

## ◆ eina_simple_xml_node_tag_new()

Eina_Simple_XML_Node_Tag* eina_simple_xml_node_tag_new | ( | Eina_Simple_XML_Node_Tag * | parent,
|  | const char * | name
| ) |  |

Create new tag.

If parent is provided, it is automatically appended.

Parameters

  parent | if provided, will be set in the resulting structure as well as the tag will be appended to children list.
  name | Null-terminated string. Must not be `NULL`.

Returns
  Newly allocated memory or `NULL` on error. This memory should be released with eina_simple_xml_node_tag_free() or indirectly with eina_simple_xml_node_tag_free() of the parent.

References EINA_MAGIC_SET, eina_mempool_malloc(), and ERR.

## ◆ eina_simple_xml_node_tag_free()

void eina_simple_xml_node_tag_free | ( | Eina_Simple_XML_Node_Tag * | tag | ) |

Remove tag from parent and delete it.

Parameters

  tag | to release memory.

## ◆ eina_simple_xml_node_data_new()

Eina_Simple_XML_Node_Data* eina_simple_xml_node_data_new | ( | Eina_Simple_XML_Node_Tag * | parent,
|  | const char * | contents,
|  | size_t | length
| ) |  |

Create new data.

If parent is provided, it is automatically appended.

Parameters

  parent | if provided, will be set in the resulting structure as well as the data will be appended to children list.
  contents | String to be used. Must not be `NULL`.
  length | size in bytes of contents.

Returns
  Newly allocated memory or NULL on error. This memory should be released with eina_simple_xml_node_data_free() or indirectly with eina_simple_xml_node_tag_free() of the parent.

## ◆ eina_simple_xml_node_data_free()

void eina_simple_xml_node_data_free | ( | Eina_Simple_XML_Node_Data * | node | ) |

Remove data from parent and delete it.

Parameters

  node | to release memory.

## ◆ eina_simple_xml_node_cdata_new()

Eina_Simple_XML_Node_CData* eina_simple_xml_node_cdata_new | ( | Eina_Simple_XML_Node_Tag * | parent,
|  | const char * | contents,
|  | size_t | length
| ) |  |

Create new cdata.

If parent is provided, it is automatically appended.

Parameters

  parent | if provided, will be set in the resulting structure as well as the cdata will be appended to children list.
  contents | String to be used. Must not be `NULL`.
  length | size in bytes of content.

Returns
  Newly allocated memory or `NULL` on error. This memory should be released with eina_simple_xml_node_cdata_free() or indirectly with eina_simple_xml_node_tag_free() of the parent.

## ◆ eina_simple_xml_node_cdata_free()

void eina_simple_xml_node_cdata_free | ( | Eina_Simple_XML_Node_Data * | node | ) |

Remove cdata from parent and delete it.

Parameters

  node | to release memory.

## ◆ eina_simple_xml_node_doctype_child_new()

Eina_Simple_XML_Node_Doctype_Child* eina_simple_xml_node_doctype_child_new | ( | Eina_Simple_XML_Node_Tag * | parent,
|  | const char * | contents,
|  | size_t | length
| ) |  |

Create new doctype child.

If parent is provided, it is automatically appended.

Parameters

  parent | if provided, will be set in the resulting structure as well as the doctype child will be appended to children list.
  contents | String to be used. Must not be `NULL`.
  length | size in bytes of content.

Returns
  Newly allocated memory or `NULL` on error. This memory should be released with eina_simple_xml_node_doctype_child_free() or indirectly with eina_simple_xml_node_tag_free() of the parent.

Since
  1.8

References EINA_SIMPLE_XML_NODE_DOCTYPE_CHILD.

## ◆ eina_simple_xml_node_doctype_child_free()

void eina_simple_xml_node_doctype_child_free | ( | Eina_Simple_XML_Node_Data * | node | ) |

Remove doctype child from parent and delete it.

Parameters

  node | to release memory.

Since
  1.8

References EINA_SIMPLE_XML_NODE_DOCTYPE_CHILD, and ERR.

## ◆ eina_simple_xml_node_processing_new()

Eina_Simple_XML_Node_Processing* eina_simple_xml_node_processing_new | ( | Eina_Simple_XML_Node_Tag * | parent,
|  | const char * | contents,
|  | size_t | length
| ) |  |

Create new processing.

If parent is provided, it is automatically appended.

Parameters

  parent | if provided, will be set in the resulting structure as well as the processing will be appended to children list.
  contents | String to be used. Must not be `NULL`.
  length | size in bytes of contents.

Returns
  Newly allocated memory or `NULL` on error. This memory should be released with eina_simple_xml_node_processing_free() or indirectly with eina_simple_xml_node_tag_free() of the parent.

## ◆ eina_simple_xml_node_processing_free()

void eina_simple_xml_node_processing_free | ( | Eina_Simple_XML_Node_Data * | node | ) |

Remove processing from parent and delete it.

Parameters

  node | processing to release memory.

## ◆ eina_simple_xml_node_doctype_new()

Eina_Simple_XML_Node_Doctype* eina_simple_xml_node_doctype_new | ( | Eina_Simple_XML_Node_Tag * | parent,
|  | const char * | contents,
|  | size_t | length
| ) |  |

Create new doctype.

If parent is provided, it is automatically appended.

Parameters

  parent | if provided, will be set in the resulting structure as well as the doctype will be appended to children list.
  contents | String to be used. Must not be `NULL`.
  length | size in bytes of contents.

Returns
  Newly allocated memory or `NULL` on error. This memory should be released with eina_simple_xml_node_doctype_free() or indirectly with eina_simple_xml_node_tag_free() of the parent.

## ◆ eina_simple_xml_node_doctype_free()

void eina_simple_xml_node_doctype_free | ( | Eina_Simple_XML_Node_Data * | node | ) |

Remove doctype from parent and delete it.

Parameters

  node | doctype to release memory.

## ◆ eina_simple_xml_node_comment_new()

Eina_Simple_XML_Node_Comment* eina_simple_xml_node_comment_new | ( | Eina_Simple_XML_Node_Tag * | parent,
|  | const char * | contents,
|  | size_t | length
| ) |  |

Create new comment.

If parent is provided, it is automatically appended.

Parameters

  parent | if provided, will be set in the resulting structure as well as the comment will be appended to children list.
  contents | String to be used. Must not be `NULL`.
  length | size in bytes of contents.

Returns
  Newly allocated memory or `NULL` on error. This memory should be released with eina_simple_xml_node_comment_free() or indirectly with eina_simple_xml_node_tag_free() of the parent.

## ◆ eina_simple_xml_node_comment_free()

void eina_simple_xml_node_comment_free | ( | Eina_Simple_XML_Node_Data * | node | ) |

Remove comment from parent and delete it.

Parameters

  node | comment to release memory.

## ◆ eina_simple_xml_node_load()

Eina_Simple_XML_Node_Root* eina_simple_xml_node_load | ( | const char * | buf,
|  | unsigned | buflen,
|  | Eina_Bool | strip
| ) |  |

Load a XML node tree based on the given string.

Parameters

  buf | the input string. May not contain \0 terminator.
  buflen | the input string size.
  strip | whenever this parser should strip leading and trailing whitespace.

Returns
  Document root with children tags, or `NULL` on errors. Document with errors may return partial tree instead of `NULL`, we'll do our best to avoid returning nothing.

References EINA_MAGIC_SET, and eina_mempool_malloc().

## ◆ eina_simple_xml_node_root_free()

void eina_simple_xml_node_root_free | ( | Eina_Simple_XML_Node_Root * | root | ) |

Free node tree build with eina_simple_xml_node_load()

Parameters

  root | memory returned by eina_simple_xml_node_load()

## ◆ eina_simple_xml_node_dump()

char* eina_simple_xml_node_dump | ( | Eina_Simple_XML_Node * | node,
|  | const char * | indent
| ) |  |

Converts the node tree under the given element to a XML string.

Parameters

  node | the base node to convert.
  indent | Indentation string, or `NULL` to disable it.

Returns
  `NULL` on errors or a newly allocated string on success.

References eina_strbuf_free(), eina_strbuf_new(), and eina_strbuf_string_steal().