FmXmlFile: Libfm Reference Manual

## FmXmlFile FmXmlFile — Simple XML parser. |

## Functions

gboolean | (*FmXmlFileHandler) ()
GList * | fm_xml_file_finish_parse ()
gint | fm_xml_file_get_current_line ()
const char * | fm_xml_file_get_dtd ()
const char * | fm_xml_file_get_tag_name ()
gboolean | fm_xml_file_insert_before ()
gboolean | fm_xml_file_insert_first ()
gboolean | fm_xml_file_item_append_child ()
void | fm_xml_file_item_append_text ()
gboolean | fm_xml_file_item_destroy ()
FmXmlFileItem * | fm_xml_file_item_find_child ()
GList * | fm_xml_file_item_get_children ()
const char * | fm_xml_file_item_get_comment ()
const char * | fm_xml_file_item_get_data ()
FmXmlFileItem * | fm_xml_file_item_get_parent ()
FmXmlFileTag | fm_xml_file_item_get_tag ()
const char * | fm_xml_file_item_get_tag_name ()
FmXmlFileItem * | fm_xml_file_item_new ()
gboolean | fm_xml_file_item_set_attribute ()
void | fm_xml_file_item_set_comment ()
FmXmlFile * | fm_xml_file_new ()
gboolean | fm_xml_file_parse_data ()
void | fm_xml_file_set_dtd ()
FmXmlFileTag | fm_xml_file_set_handler ()
char * | fm_xml_file_to_data ()

## Types and Values

#define | FM_XML_FILE_TAG_NOT_HANDLED
#define | FM_XML_FILE_TEXT
#define | FM_XML_FILE_TYPE
| FmXmlFile
| FmXmlFileClass
| FmXmlFileItem
typedef | FmXmlFileTag

## Object Hierarchy

        GObject
        ╰── FmXmlFile

## Description

`include` : libfm/fm-extra.h

The FmXmlFile represents content of some XML file in form that can be altered and saved later.

This parser has some simplifications on XML parsing:

- Only UTF-8 encoding is supported

- No user-defined entities, those should be converted externally

- Processing instructions, comments and the doctype declaration are parsed but are not interpreted in any way The markup format does support:

- Elements

- Attributes

- 5 standard entities: &amp; &lt; &gt; &quot; &apos;

- Character references

- Sections marked as CDATA

The application should respect `g_type_init()` if this parser is used without usage of libfm.

## Functions

### FmXmlFileHandler ()

    gboolean
    (*FmXmlFileHandler) (FmXmlFileItem *item,
                         GList *children,
                         char * const *attribute_names,
                         char * const *attribute_values,
                         guint n_attributes,
                         gint line,
                         gint pos,
                         GError **error,
                         gpointer user_data);

Callback for processing some element in XML file. It will be called at closing tag.

#### Parameters

item | XML element being parsed |
children | elements found in `item` . | [element-type FmXmlFileItem]
attribute_names | attributes names list for `item` |
attribute_values | attributes values list for `item` |
n_attributes | list length of `attribute_names` and `attribute_values` |
line | current line number in the file (starting from 1) |
pos | current pos number in the file (starting from 0) |
error | location to save error. | [allow-none][out]
user_data | data passed to `fm_xml_file_parse_data()` |

#### Returns

`TRUE` if no errors were found by handler.

Since: 1.2.0

### fm_xml_file_finish_parse ()

    GList *
    fm_xml_file_finish_parse (FmXmlFile *file,
                              GError **error);

Ends parsing of data and retrieves final status. If XML was invalid then returns `NULL` and sets `error` appropriately. This function can be called more than once.

See also: `fm_xml_file_parse_data()`. See also: `fm_xml_file_item_get_children()`.

#### Parameters

file | the parser container |
error | location to save error. | [allow-none][out]

#### Returns

contents of XML.

[transfer container][element-type FmXmlFileItem]

Since: 1.2.0

### fm_xml_file_get_current_line ()

    gint
    fm_xml_file_get_current_line (FmXmlFile *file,
                                  gint *pos);

Retrieves the line where parser has stopped.

#### Parameters

file | the parser container |
pos | location to save line position. | [allow-none][out]

#### Returns

line num (starting from 1).

Since: 1.2.0

### fm_xml_file_get_dtd ()

    const char *
    fm_xml_file_get_dtd (FmXmlFile *file);

Retrieves DTD description for XML data in the container. Returned data are owned by `file` and should not be modified by caller.

#### Parameters

file | the parser container |

#### Returns

DTD description.

[transfer none]

Since: 1.2.0

### fm_xml_file_get_tag_name ()

    const char *
    fm_xml_file_get_tag_name (FmXmlFile *file,
                              FmXmlFileTag tag);

Retrieves tag for its id. Returned data are owned by `file` and should not be modified by caller.

#### Parameters

file | the parser container |
tag | the tag id to inspect |

#### Returns

tag string representation.

[transfer none]

Since: 1.2.0

### fm_xml_file_insert_before ()

    gboolean
    fm_xml_file_insert_before (FmXmlFileItem *item,
                               FmXmlFileItem *new_item);

Inserts `new_item` before `item` that is already in XML structure. If `new_item` is already in the XML structure then it will be moved to the new place instead. Behavior after moving between defferent containers is undefined.

#### Parameters

item | item to insert before it |
new_item | new item to insert |

#### Returns

`TRUE` in case of success.

Since: 1.2.0

### fm_xml_file_insert_first ()

    gboolean
    fm_xml_file_insert_first (FmXmlFile *file,
                              FmXmlFileItem *new_item);

Inserts `new_item` as very first element of XML data in container.

#### Parameters

file | the parser container |
new_item | new item to insert |

#### Returns

`TRUE` in case of success.

Since: 1.2.0

### fm_xml_file_item_append_child ()

    gboolean
    fm_xml_file_item_append_child (FmXmlFileItem *item,
                                   FmXmlFileItem *child);

Appends `child` after last element contained in `item` . If the `child` already was in the XML structure then it will be moved to the new place instead. Behavior after moving between different containers is undefined.

#### Parameters

item | item to append child |
child | the child item to append |

#### Returns

`FALSE` if `child` is busy thus cannot be moved.

Since: 1.2.0

### fm_xml_file_item_append_text ()

    void
    fm_xml_file_item_append_text (FmXmlFileItem *item,
                                  const char *text,
                                  gssize text_size,
                                  gboolean cdata);

Appends `text` after last element contained in `item` .

#### Parameters

item | item to append text |
text | text to append |
text_size | length of text in bytes, or -1 if the text is nul-terminated |
cdata | `TRUE` if `text` should be saved as CDATA array |

Since: 1.2.0

### fm_xml_file_item_destroy ()

    gboolean
    fm_xml_file_item_destroy (FmXmlFileItem *item);

Removes element and its children from its parent, and frees all data.

#### Parameters

item | element to destroy |

#### Returns

`FALSE` if `item` is busy thus cannot be destroyed.

Since: 1.2.0

### fm_xml_file_item_find_child ()

    FmXmlFileItem *
    fm_xml_file_item_find_child (FmXmlFileItem *item,
                                 FmXmlFileTag tag);

Searches for first child of `item` which have child with tag id `tag` . Returned data are owned by file and should not be freed by caller.

#### Parameters

item | the file element to inspect |
tag | tag id to search among children |

#### Returns

found child or `NULL` if no such child was found.

[transfer none]

Since: 1.2.0

### fm_xml_file_item_get_children ()

    GList *
    fm_xml_file_item_get_children (FmXmlFileItem *item);

Retrieves list of children for `item` that are known to the parser. Returned list should be freed by `g_list_free()` after usage.

Note: any text between opening tag and closing tag such as

    1
    2
    3
    4
    is presented as a child of special type #FM_XML_FILE_TEXT and can be
    retrieved from that child, not from the item representing <Tag>.

    See also: fm_xml_file_item_get_data().

#### Parameters

item | the file element to inspect |

#### Returns

children list.

[transfer container][element-type FmXmlFileItem]

Since: 1.2.0

### fm_xml_file_item_get_comment ()

    const char *
    fm_xml_file_item_get_comment (FmXmlFileItem *item);

If an element `item` has a comment ahead of it then retrieves that comment. The returned data are owned by `item` and should not be freed nor otherwise altered by caller.

#### Parameters

item | the file element to inspect |

#### Returns

comment or `NULL` if no comment is set.

[transfer none]

Since: 1.2.0

### fm_xml_file_item_get_data ()

    const char *
    fm_xml_file_item_get_data (FmXmlFileItem *item,
                               gsize *text_size);

Retrieves text data from `item` of type FM_XML_FILE_TEXT. Returned data are owned by file and should not be freed nor altered.

#### Parameters

item | the file element to inspect |
text_size | location to save data size. | [allow-none][out]

#### Returns

text data or `NULL` if `item` isn't text data.

[transfer none]

Since: 1.2.0

### fm_xml_file_item_get_parent ()

    FmXmlFileItem *
    fm_xml_file_item_get_parent (FmXmlFileItem *item);

Retrieves parent element of `item` if the `item` has one. Returned data are owned by file and should not be freed by caller.

#### Parameters

item | the file element to inspect |

#### Returns

parent element or `NULL` if element has no parent.

[transfer none]

Since: 1.2.0

### fm_xml_file_item_get_tag ()

    FmXmlFileTag
    fm_xml_file_item_get_tag (FmXmlFileItem *item);

Retrieves tag id of `item` .

#### Parameters

item | the file element to inspect |

#### Returns

tag id.

Since: 1.2.0

### fm_xml_file_item_get_tag_name ()

    const char *
    fm_xml_file_item_get_tag_name (FmXmlFileItem *item);

Retrieves tag for its id. Returned data are owned by `item` and should not be modified by caller.

#### Parameters

item | the file element to inspect |

#### Returns

tag string representation or `NULL` if `item` is text.

[transfer none]

Since: 1.2.0

### fm_xml_file_item_new ()

    FmXmlFileItem *
    fm_xml_file_item_new (FmXmlFileTag tag);

Creates new unattached XML item.

#### Parameters

tag | tag id for new item |

#### Returns

newly allocated FmXmlFileItem.

[transfer full]

Since: 1.2.0

### fm_xml_file_item_set_attribute ()

    gboolean
    fm_xml_file_item_set_attribute (FmXmlFileItem *item,
                                    const char *name,
                                    const char *value);

Changes data for the attribute of some `item` with new `value` . If such attribute wasn't set then adds it for the `item` . If `value` is `NULL` then the attribute will be unset from the `item` .

#### Parameters

item | element to update |
name | attribute name |
value | attribute data. | [allow-none]

#### Returns

`TRUE` if attribute was set successfully.

Since: 1.2.0

### fm_xml_file_item_set_comment ()

    void
    fm_xml_file_item_set_comment (FmXmlFileItem *item,
                                  const char *comment);

Changes comment that is prepended to `item` .

#### Parameters

item | element to set |
comment | new comment. | [allow-none]

Since: 1.2.0

### fm_xml_file_new ()

    FmXmlFile *
    fm_xml_file_new (FmXmlFile *sibling);

Creates new empty FmXmlFile container. If `sibling` is not `NULL` then new container will have callbacks identical to set in `sibling` . Use `sibling` parameter if you need to work with few XML files that share the same schema or if you need to use the same tag ids for more than one file.

#### Parameters

sibling | container to copy handlers data. | [allow-none]

#### Returns

newly created object.

[transfer full]

Since: 1.2.0

### fm_xml_file_parse_data ()

    gboolean
    fm_xml_file_parse_data (FmXmlFile *file,
                            const char *text,
                            gsize size,
                            GError **error,
                            gpointer user_data);

Parses next chunk of `text` data. Parsing stops at end of data or at any error. In latter case `error` will be set appropriately.

See also: `fm_xml_file_finish_parse()`.

#### Parameters

file | the parser container |
text | data to parse |
size | size of `text` |
error | location to save error. | [allow-none][out]
user_data | data to pass to handlers |

#### Returns

`FALSE` if parsing failed.

Since: 1.2.0

### fm_xml_file_set_dtd ()

    void
    fm_xml_file_set_dtd (FmXmlFile *file,
                         const char *dtd,
                         GError **error);

Changes DTD description for XML data in the container.

#### Parameters

file | the parser container |
dtd | DTD description for XML data |
error | location to save error. | [allow-none][out]

Since: 1.2.0

### fm_xml_file_set_handler ()

    FmXmlFileTag
    fm_xml_file_set_handler (FmXmlFile *file,
                             const char *tag,
                             FmXmlFileHandler handler,
                             gboolean in_line,
                             GError **error);

Sets `handler` for `file` to be called on parse when `tag` is found in XML data. This function will fail if some handler for `tag` was aready set, in this case `error` will be set appropriately.

#### Parameters

file | the parser container |
tag | tag to use `handler` for |
handler | callback for `tag` |
in_line | `TRUE` if tag should not receive new line by `fm_xml_file_to_data()` |
error | location to save error. | [allow-none][out]

#### Returns

id for the `tag` .

Since: 1.2.0

### fm_xml_file_to_data ()

    char *
    fm_xml_file_to_data (FmXmlFile *file,
                         gsize *text_size,
                         GError **error);

Prepares string representation (XML text) for the data that are in the container. Returned data should be freed with `g_free()` after usage.

#### Parameters

file | the parser container |
text_size | location to save size of returned data. | [allow-none][out]
error | location to save error. | [allow-none][out]

#### Returns

XML text representing data in `file` .

[transfer full]

Since: 1.2.0

## Types and Values

### FM_XML_FILE_TAG_NOT_HANDLED

    #define FM_XML_FILE_TAG_NOT_HANDLED 0

Value of FmXmlFileTag which means this element has no handler installed.

### FM_XML_FILE_TEXT

    #define FM_XML_FILE_TEXT (FmXmlFileTag)-1

Value of FmXmlFileTag which means this element has parsed character data.

### FM_XML_FILE_TYPE

    #define FM_XML_FILE_TYPE           (fm_xml_file_get_type())

### FmXmlFile

    typedef struct _FmXmlFile FmXmlFile;

### FmXmlFileClass

    typedef struct _FmXmlFileClass FmXmlFileClass;

### FmXmlFileItem

    typedef struct _FmXmlFileItem FmXmlFileItem;

### FmXmlFileTag

    typedef guint                       FmXmlFileTag;