FmXmlFile

FmXmlFile — Simple XML parser.

Synopsis

#define             FM_XML_FILE_TAG_NOT_HANDLED
#define             FM_XML_FILE_TEXT
#define             FM_XML_FILE_TYPE
                    FmXmlFile;
                    FmXmlFileClass;
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);
                    FmXmlFileItem;
typedef             FmXmlFileTag;
GList *             fm_xml_file_finish_parse            (FmXmlFile *file,
                                                         GError **error);
gint                fm_xml_file_get_current_line        (FmXmlFile *file,
                                                         gint *pos);
const char *        fm_xml_file_get_dtd                 (FmXmlFile *file);
const char *        fm_xml_file_get_tag_name            (FmXmlFile *file,
                                                         FmXmlFileTag tag);
gboolean            fm_xml_file_insert_before           (FmXmlFileItem *item,
                                                         FmXmlFileItem *new_item);
gboolean            fm_xml_file_insert_first            (FmXmlFile *file,
                                                         FmXmlFileItem *new_item);
gboolean            fm_xml_file_item_append_child       (FmXmlFileItem *item,
                                                         FmXmlFileItem *child);
void                fm_xml_file_item_append_text        (FmXmlFileItem *item,
                                                         const char *text,
                                                         gssize text_size,
                                                         gboolean cdata);
gboolean            fm_xml_file_item_destroy            (FmXmlFileItem *item);
FmXmlFileItem *     fm_xml_file_item_find_child         (FmXmlFileItem *item,
                                                         FmXmlFileTag tag);
GList *             fm_xml_file_item_get_children       (FmXmlFileItem *item);
const char *        fm_xml_file_item_get_comment        (FmXmlFileItem *item);
const char *        fm_xml_file_item_get_data           (FmXmlFileItem *item,
                                                         gsize *text_size);
FmXmlFileItem *     fm_xml_file_item_get_parent         (FmXmlFileItem *item);
FmXmlFileTag        fm_xml_file_item_get_tag            (FmXmlFileItem *item);
const char *        fm_xml_file_item_get_tag_name       (FmXmlFileItem *item);
FmXmlFileItem *     fm_xml_file_item_new                (FmXmlFileTag tag);
gboolean            fm_xml_file_item_set_attribute      (FmXmlFileItem *item,
                                                         const char *name,
                                                         const char *value);
void                fm_xml_file_item_set_comment        (FmXmlFileItem *item,
                                                         const char *comment);
FmXmlFile *         fm_xml_file_new                     (FmXmlFile *sibling);
gboolean            fm_xml_file_parse_data              (FmXmlFile *file,
                                                         const char *text,
                                                         gsize size,
                                                         GError **error,
                                                         gpointer user_data);
void                fm_xml_file_set_dtd                 (FmXmlFile *file,
                                                         const char *dtd,
                                                         GError **error);
FmXmlFileTag        fm_xml_file_set_handler             (FmXmlFile *file,
                                                         const char *tag,
                                                         FmXmlFileHandler handler,
                                                         gboolean in_line,
                                                         GError **error);
char *              fm_xml_file_to_data                 (FmXmlFile *file,
                                                         gsize *text_size,
                                                         GError **error);

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: & < > " ' * Character references * Sections marked as CDATA

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

Details

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;

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.

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


FmXmlFileItem

typedef struct _FmXmlFileItem FmXmlFileItem;

FmXmlFileTag

typedef guint                       FmXmlFileTag;

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().

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.

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.

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.

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.

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.

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.

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.

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.

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.

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