Top | ![]() |
![]() |
![]() |
![]() |
gboolean | (*FmXmlFileHandler) () |
FmXmlFile * | fm_xml_file_new () |
FmXmlFileTag | fm_xml_file_set_handler () |
gboolean | fm_xml_file_parse_data () |
GList * | fm_xml_file_finish_parse () |
gint | fm_xml_file_get_current_line () |
const char * | fm_xml_file_get_dtd () |
FmXmlFileItem * | fm_xml_file_item_new () |
void | fm_xml_file_item_append_text () |
gboolean | fm_xml_file_item_append_child () |
void | fm_xml_file_item_set_comment () |
gboolean | fm_xml_file_item_set_attribute () |
gboolean | fm_xml_file_item_destroy () |
gboolean | fm_xml_file_insert_before () |
gboolean | fm_xml_file_insert_first () |
void | fm_xml_file_set_dtd () |
char * | fm_xml_file_to_data () |
const char * | fm_xml_file_item_get_comment () |
GList * | fm_xml_file_item_get_children () |
FmXmlFileItem * | fm_xml_file_item_find_child () |
FmXmlFileTag | fm_xml_file_item_get_tag () |
const char * | fm_xml_file_item_get_data () |
FmXmlFileItem * | fm_xml_file_item_get_parent () |
const char * | fm_xml_file_item_get_tag_name () |
const char * | fm_xml_file_get_tag_name () |
#define | FM_XML_FILE_TYPE |
typedef | FmXmlFileTag |
#define | FM_XML_FILE_TAG_NOT_HANDLED |
#define | FM_XML_FILE_TEXT |
FmXmlFileItem |
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.
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 |
[element-type FmXmlFileItem] |
attribute_names |
attributes names list for |
|
attribute_values |
attributes values list for |
|
n_attributes |
list length of |
|
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 |
Since: 1.2.0
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.
Since: 1.2.0
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.
file |
the parser container |
|
tag |
tag to use |
|
handler |
callback for |
|
in_line |
|
|
error |
location to save error. |
[allow-none][out] |
Since: 1.2.0
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()
.
file |
the parser container |
|
text |
data to parse |
|
size |
size of |
|
error |
location to save error. |
[allow-none][out] |
user_data |
data to pass to handlers |
Since: 1.2.0
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()
.
Since: 1.2.0
gint fm_xml_file_get_current_line (FmXmlFile *file
,gint *pos
);
Retrieves the line where parser has stopped.
Since: 1.2.0
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.
Since: 1.2.0
FmXmlFileItem *
fm_xml_file_item_new (FmXmlFileTag tag
);
Creates new unattached XML item.
Since: 1.2.0
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 |
|
Since: 1.2.0
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.
Since: 1.2.0
void fm_xml_file_item_set_comment (FmXmlFileItem *item
,const char *comment
);
Changes comment that is prepended to item
.
Since: 1.2.0
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
.
Since: 1.2.0
gboolean
fm_xml_file_item_destroy (FmXmlFileItem *item
);
Removes element and its children from its parent, and frees all data.
Since: 1.2.0
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.
Since: 1.2.0
gboolean fm_xml_file_insert_first (FmXmlFile *file
,FmXmlFileItem *new_item
);
Inserts new_item
as very first element of XML data in container.
Since: 1.2.0
void fm_xml_file_set_dtd (FmXmlFile *file
,const char *dtd
,GError **error
);
Changes DTD description for XML data in the container.
file |
the parser container |
|
dtd |
DTD description for XML data |
|
error |
location to save error. |
[allow-none][out] |
Since: 1.2.0
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.
file |
the parser container |
|
text_size |
location to save size of returned data. |
[allow-none][out] |
error |
location to save error. |
[allow-none][out] |
Since: 1.2.0
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.
Since: 1.2.0
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(). |
Since: 1.2.0
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.
Since: 1.2.0
FmXmlFileTag
fm_xml_file_item_get_tag (FmXmlFileItem *item
);
Retrieves tag id of item
.
Since: 1.2.0
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.
Since: 1.2.0
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.
Since: 1.2.0
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.
Since: 1.2.0
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.
Since: 1.2.0