XML and libxml

XML and libxml

Synopsis





            GsfXMLIn;
            GsfXMLInDoc;
gboolean    (*GsfXMLInUnknownFunc)          (GsfXMLIn *xin,
                                             xmlChar const *elem,
                                             xmlChar const **attrs);
            GsfXMLInNS;
            GsfXMLInNode;
void        (*GsfXMLInExtDtor)              (GsfXMLIn *xin,
                                             gpointer old_state);
enum        GsfXMLContent;
            GsfXMLBlob;
#define     GSF_XML_IN_NODE_FULL            (parent_id, id, ns, name, has_content, 	\
			     share_children_with_parent, check_ns, start, end, user)
#define     GSF_XML_IN_NODE                 (parent_id, id, ns, name, has_content, start, end)
#define     GSF_XML_IN_NODE_END
#define     GSF_XML_IN_NS                   (id, uri)
GsfXMLInDoc* gsf_xml_in_doc_new             (GsfXMLInNode const *nodes,
                                             GsfXMLInNS const *ns);
void        gsf_xml_in_doc_free             (GsfXMLInDoc *doc);
gboolean    gsf_xml_in_doc_parse            (GsfXMLInDoc *doc,
                                             GsfInput *input,
                                             gpointer user_state);
void        gsf_xml_in_doc_set_unknown_handler
                                            (GsfXMLInDoc *doc,
                                             GsfXMLInUnknownFunc handler);
void        gsf_xml_in_push_state           (GsfXMLIn *xin,
                                             GsfXMLInDoc const *doc,
                                             gpointer new_state,
                                             GsfXMLInExtDtor dtor,
                                             xmlChar const **attrs);
gboolean    gsf_xml_in_namecmp              (GsfXMLIn const *xin,
                                             char const *str,
                                             unsigned int ns_id,
                                             char const *name);
charconst  * gsf_xml_in_check_ns            (GsfXMLIn const *xin,
                                             char const *str,
                                             unsigned int ns_id);

            GsfXMLOut;
GsfXMLOut*  gsf_xml_out_new                 (GsfOutput *output);
void        gsf_xml_out_set_doc_type        (GsfXMLOut *xml,
                                             char const *type);
void        gsf_xml_out_start_element       (GsfXMLOut *xml,
                                             char const *id);
charconst * gsf_xml_out_end_element         (GsfXMLOut *xml);
void        gsf_xml_out_add_cstr            (GsfXMLOut *xml,
                                             char const *id,
                                             char const *val_utf8);
void        gsf_xml_out_add_cstr_unchecked  (GsfXMLOut *xml,
                                             char const *id,
                                             char const *val_utf8);
void        gsf_xml_out_add_bool            (GsfXMLOut *xml,
                                             char const *id,
                                             gboolean val);
void        gsf_xml_out_add_int             (GsfXMLOut *xml,
                                             char const *id,
                                             int val);
void        gsf_xml_out_add_uint            (GsfXMLOut *xml,
                                             char const *id,
                                             unsigned int val);
void        gsf_xml_out_add_float           (GsfXMLOut *xml,
                                             char const *id,
                                             double val,
                                             int precision);
void        gsf_xml_out_add_enum            (GsfXMLOut *xml,
                                             char const *id,
                                             GType etype,
                                             gint val);
void        gsf_xml_out_add_color           (GsfXMLOut *xml,
                                             char const *id,
                                             unsigned int r,
                                             unsigned int g,
                                             unsigned int b);
void        gsf_xml_out_add_base64          (GsfXMLOut *xml,
                                             char const *id,
                                             guint8 const *data,
                                             unsigned int len);
void        gsf_xml_out_add_gvalue          (GsfXMLOut *xml,
                                             char const *id,
                                             GValue const *val);
void        gsf_xml_out_simple_element      (GsfXMLOut *xml,
                                             char const *id,
                                             char const *content);
void        gsf_xml_out_simple_float_element
                                            (GsfXMLOut *xml,
                                             char const *id,
                                             double val,
                                             int precision);
void        gsf_xml_out_simple_int_element  (GsfXMLOut *xml,
                                             char const *id,
                                             int val);

xmlParserCtxt* gsf_xml_parser_context       (GsfInput *input);
gboolean    gsf_xml_gvalue_from_str         (GValue *res,
                                             GType t,
                                             char const *str);
int         gsf_xmlDocFormatDump            (GsfOutput *output,
                                             xmlDoc *cur,
                                             char const *encoding,
                                             gboolean format);

Object Hierarchy


  GObject
   +----GsfXMLOut

Properties


  "pretty-print"         gboolean              : Read / Write

Description

Details

GsfXMLIn

typedef struct {
	/* public state : read only */
	gpointer	    user_state;
	GString		   *content;
	GsfXMLInDoc  const *doc;
	GsfXMLInNode const *node;	/* current node (not on the stack) */
	GSList	 	   *node_stack;	/* stack of GsfXMLInNode */
} GsfXMLIn;

GsfXMLInDoc

typedef struct _GsfXMLInDoc GsfXMLInDoc;

GsfXMLInUnknownFunc ()

gboolean    (*GsfXMLInUnknownFunc)          (GsfXMLIn *xin,
                                             xmlChar const *elem,
                                             xmlChar const **attrs);

xin :
elem :
attrs :
Returns :

GsfXMLInNS

typedef struct {
	char const *uri;
	unsigned    ns_id;
} GsfXMLInNS;

GsfXMLInNode

typedef struct {
	char const *id;		/* unique in the entire tree */
	int	    ns_id;
	char const *name;
	char const *parent_id;
	void (*start) (GsfXMLIn *xin, xmlChar const **attrs);
	void (*end)   (GsfXMLIn *xin, GsfXMLBlob *unknown);

	union {
		int	    v_int;
		gboolean    v_bool;
		gpointer    v_blob;
		char const *v_str;
	} user_data;
	GsfXMLContent has_content;

	unsigned int check_children_for_ns : 1;
	unsigned int share_children_with_parent : 1;
} GsfXMLInNode;

GsfXMLInExtDtor ()

void        (*GsfXMLInExtDtor)              (GsfXMLIn *xin,
                                             gpointer old_state);

xin :
old_state :

enum GsfXMLContent

typedef enum {
	GSF_XML_NO_CONTENT = FALSE,
	GSF_XML_CONTENT,
	GSF_XML_SHARED_CONTENT
} GsfXMLContent;

GsfXMLBlob

typedef struct _GsfXMLBlob GsfXMLBlob;

GSF_XML_IN_NODE_FULL()

#define     GSF_XML_IN_NODE_FULL(parent_id, id, ns, name, has_content, 	\
			     share_children_with_parent, check_ns, start, end, user)

parent_id :
id :
ns :
name :
has_content :
share_children_with_parent :
check_ns :
start :
end :
user :

GSF_XML_IN_NODE()

#define     GSF_XML_IN_NODE(parent_id, id, ns, name, has_content, start, end)

parent_id :
id :
ns :
name :
has_content :
start :
end :

GSF_XML_IN_NODE_END

#define     GSF_XML_IN_NODE_END

GSF_XML_IN_NS()

#define     GSF_XML_IN_NS(id, uri)

id :
uri :

gsf_xml_in_doc_new ()

GsfXMLInDoc* gsf_xml_in_doc_new             (GsfXMLInNode const *nodes,
                                             GsfXMLInNS const *ns);

Combine the nodes in the NULL terminated array starting at nodes with the name spaces in the NULL terminated array starting at ns. Prepare the data structures necessary to validate a doument based on that description.

nodes : an array of node descriptors
ns : an array of namespace identifiers
Returns : NULL on error

gsf_xml_in_doc_free ()

void        gsf_xml_in_doc_free             (GsfXMLInDoc *doc);

Free up resources

doc :

gsf_xml_in_doc_parse ()

gboolean    gsf_xml_in_doc_parse            (GsfXMLInDoc *doc,
                                             GsfInput *input,
                                             gpointer user_state);

Read an xml document from input and parse based on the the descriptor in doc

doc :
input :
user_state :
Returns : FALSE on error

gsf_xml_in_doc_set_unknown_handler ()

void        gsf_xml_in_doc_set_unknown_handler
                                            (GsfXMLInDoc *doc,
                                             GsfXMLInUnknownFunc handler);

Call the function handler when an unexpected child node is found

doc : GsfXMLInDoc
handler : The function to call

gsf_xml_in_push_state ()

void        gsf_xml_in_push_state           (GsfXMLIn *xin,
                                             GsfXMLInDoc const *doc,
                                             gpointer new_state,
                                             GsfXMLInExtDtor dtor,
                                             xmlChar const **attrs);

Take the first node from doc as the current node and call it's start handler.

xin : GsfXMLIn
doc : GsfXMLInDoc
new_state :
dtor : GsfXMLInExtDtor
attrs :

gsf_xml_in_namecmp ()

gboolean    gsf_xml_in_namecmp              (GsfXMLIn const *xin,
                                             char const *str,
                                             unsigned int ns_id,
                                             char const *name);

xin : The GsfXMLIn we are reading from.
str : The potentially namespace qualified node name.
ns_id : The name space id to check
name : The target node name
Returns : TRUE if str == ns_id:name according to state.

gsf_xml_in_check_ns ()

charconst  * gsf_xml_in_check_ns            (GsfXMLIn const *xin,
                                             char const *str,
                                             unsigned int ns_id);

According to state is str in the namespace ns_id ?

xin : GsfXMLIn
str :
ns_id :
Returns : a pointer to str after the namespace if successful, otherwise NULL.

GsfXMLOut

typedef struct _GsfXMLOut GsfXMLOut;

gsf_xml_out_new ()

GsfXMLOut*  gsf_xml_out_new                 (GsfOutput *output);

Create an XML output stream.

output : GsfOutput
Returns : GsfXMLOut

gsf_xml_out_set_doc_type ()

void        gsf_xml_out_set_doc_type        (GsfXMLOut *xml,
                                             char const *type);

Store some optional some <!DOCTYPE .. > content

xml : GsfXMLOut
type : the document type declaration

gsf_xml_out_start_element ()

void        gsf_xml_out_start_element       (GsfXMLOut *xml,
                                             char const *id);

Output a start element id, if necessary preceeded by an XML declaration.

xml : GsfXMLOut
id : Element name

gsf_xml_out_end_element ()

charconst * gsf_xml_out_end_element         (GsfXMLOut *xml);

Closes/ends an XML element.

xml : GsfXMLOut
Returns : the element that has been closed.

gsf_xml_out_add_cstr ()

void        gsf_xml_out_add_cstr            (GsfXMLOut *xml,
                                             char const *id,
                                             char const *val_utf8);

dump val_utf8 to an attribute named id or as the nodes content escaping characters as necessary. If val_utf8 is NULL do nothing (no warning, no output)

xml : GsfXMLOut
id : optionally NULL for content
val_utf8 : a utf8 encoded string

gsf_xml_out_add_cstr_unchecked ()

void        gsf_xml_out_add_cstr_unchecked  (GsfXMLOut *xml,
                                             char const *id,
                                             char const *val_utf8);

dump val_utf8 to an attribute named id without checking to see if the content needs escaping. A useful performance enhancement when the application knows that structure of the content well. If val_utf8 is NULL do nothing (no warning, no output)

xml : GsfXMLOut
id : optionally NULL for content
val_utf8 : a utf8 encoded string to export

gsf_xml_out_add_bool ()

void        gsf_xml_out_add_bool            (GsfXMLOut *xml,
                                             char const *id,
                                             gboolean val);

dump boolean value val to an attribute named id or as the nodes content Use '1' or '0' to simplify import

xml : GsfXMLOut
id : optionally NULL for content
val : a boolean

gsf_xml_out_add_int ()

void        gsf_xml_out_add_int             (GsfXMLOut *xml,
                                             char const *id,
                                             int val);

dump integer value val to an attribute named id or as the nodes content

xml : GsfXMLOut
id : optionally NULL for content
val : the value

gsf_xml_out_add_uint ()

void        gsf_xml_out_add_uint            (GsfXMLOut *xml,
                                             char const *id,
                                             unsigned int val);

dump unsigned integer value val to an attribute named id or as the nodes content

xml : GsfXMLOut
id : optionally NULL for content
val : the value

gsf_xml_out_add_float ()

void        gsf_xml_out_add_float           (GsfXMLOut *xml,
                                             char const *id,
                                             double val,
                                             int precision);

dump float value val to an attribute named id or as the nodes content with precision precision. The number will be formattted according to the "C" locale.

xml : GsfXMLOut
id : optionally NULL for content
val : the value
precision : the number of significant digits to use, -1 meaning "enough".

gsf_xml_out_add_enum ()

void        gsf_xml_out_add_enum            (GsfXMLOut *xml,
                                             char const *id,
                                             GType etype,
                                             gint val);

Output the name of value val of enumeration type etype.

xml : GsfXMLOut
id : optionally NULL for content
etype : GType
val : enum element number

gsf_xml_out_add_color ()

void        gsf_xml_out_add_color           (GsfXMLOut *xml,
                                             char const *id,
                                             unsigned int r,
                                             unsigned int g,
                                             unsigned int b);

dump Color r.g.b to an attribute named id or as the nodes content

xml : GsfXMLOut
id : optionally NULL for content
r : Red value
g : Green value
b : Blue value

gsf_xml_out_add_base64 ()

void        gsf_xml_out_add_base64          (GsfXMLOut *xml,
                                             char const *id,
                                             guint8 const *data,
                                             unsigned int len);

dump len bytes in data into the content of node id using base64

xml : GsfXMLOut
id : optionally NULL for content
data : Data to be written
len : Length of data

gsf_xml_out_add_gvalue ()

void        gsf_xml_out_add_gvalue          (GsfXMLOut *xml,
                                             char const *id,
                                             GValue const *val);

Output the value of val as a string. Does NOT store any type information with the string, just thevalue.

xml : GsfXMLOut
id : optionally NULL for content
val : GValue

gsf_xml_out_simple_element ()

void        gsf_xml_out_simple_element      (GsfXMLOut *xml,
                                             char const *id,
                                             char const *content);

Convenience routine to output a simple id element with content content.

xml : GsfXMLOut
id : Element name
content : Content of the element

gsf_xml_out_simple_float_element ()

void        gsf_xml_out_simple_float_element
                                            (GsfXMLOut *xml,
                                             char const *id,
                                             double val,
                                             int precision);

Convenience routine to output an element id with float value val using precision significant digits.

xml : GsfXMLOut
id : Element name
val : Element value
precision : the number of significant digits to use, -1 meaning "enough".

gsf_xml_out_simple_int_element ()

void        gsf_xml_out_simple_int_element  (GsfXMLOut *xml,
                                             char const *id,
                                             int val);

Convenience routine to output an element id with integer value val.

xml : GsfXMLOut
id : Element name
val : Element value

gsf_xml_parser_context ()

xmlParserCtxt* gsf_xml_parser_context       (GsfInput *input);

Create a libxml2 pull style parser context wrapper around gsf input input. This signature will probably change to supply a SAX structure.

Note

This adds a reference to input.

Note

A simple wrapper around a cleaner implementation that will fold in when we add other api changes. Its not worth bumping just for this.

input : GsfInput
Returns : : A parser context or NULL

gsf_xml_gvalue_from_str ()

gboolean    gsf_xml_gvalue_from_str         (GValue *res,
                                             GType t,
                                             char const *str);

Try to parse str as a value of type t into res.

res : Result value
t : Type of data
str : Value string
Returns : : True when parsing of str as a value of type t was succesfull; false otherwise.

gsf_xmlDocFormatDump ()

int         gsf_xmlDocFormatDump            (GsfOutput *output,
                                             xmlDoc *cur,
                                             char const *encoding,
                                             gboolean format);

output :
cur :
encoding :
format :
Returns :

Property Details

The "pretty-print" property

  "pretty-print"         gboolean              : Read / Write

Should the output auto-indent elements to make reading easier.

Default value: TRUE