XML Nodes

XML Nodes

Synopsis

typedef             CongNodePtr;
CongNodePtr         cong_node_prev                      (CongNodePtr node);
CongNodePtr         cong_node_next                      (CongNodePtr node);
CongNodePtr         cong_node_first_child               (CongNodePtr node);
CongNodePtr         cong_node_parent                    (CongNodePtr node);
gboolean            cong_node_is_element                (CongNodePtr node,
                                                         const gchar *ns_uri,
                                                         const gchar *local_name);
gboolean            cong_node_is_element_from_set       (CongNodePtr node,
                                                         const gchar *ns_uri,
                                                         const gchar **local_name_array,
                                                         guint num_local_names,
                                                         guint *output_index);
xmlNsPtr            cong_node_get_ns                    (CongNodePtr node);
const gchar *       cong_node_get_ns_uri                (CongNodePtr node);
const gchar *       cong_node_get_ns_prefix             (CongNodePtr node);
const gchar *       cong_node_get_local_name            (CongNodePtr node);
gchar *             cong_node_get_qualified_name        (CongNodePtr node);
xmlNsPtr            cong_node_get_ns_for_uri            (CongNodePtr node,
                                                         const gchar *ns_uri);
xmlNsPtr            cong_node_get_ns_for_prefix         (CongNodePtr node,
                                                         const gchar *prefix);
xmlNsPtr            cong_node_get_attr_ns               (CongNodePtr node,
                                                         const char *qualified_name,
                                                         const char **output_name);
gchar *             cong_node_get_path                  (CongNodePtr node);
gchar *             cong_node_debug_description         (CongNodePtr node);
const gchar *       cong_node_type_description          (CongNodeType node_type);
gchar*              cong_node_get_attribute             (CongNodePtr node,
                                                         xmlNsPtr ns_ptr,
                                                         const gchar *local_attribute_name);
gboolean            cong_node_has_attribute             (CongNodePtr node,
                                                         xmlNsPtr ns_ptr,
                                                         const gchar *local_attribute_name);
void                cong_node_self_test                 (CongNodePtr node);
void                cong_node_self_test_recursive       (CongNodePtr node);
void                cong_node_recursive_set_doc         (CongNodePtr node,
                                                         xmlDocPtr xml_doc);
CongNodePtr         cong_node_recursive_dup             (CongNodePtr node);
gboolean            cong_node_is_descendant_of          (CongNodePtr node,
                                                         CongNodePtr potential_ancestor);
gboolean            cong_node_should_recurse            (CongNodePtr node);
#define             CONG_NODE_SELF_TEST                 (node)
int                 cong_node_get_length                (CongNodePtr node);
CongNodePtr         cong_node_new_element               (xmlNsPtr ns,
                                                         const gchar *tagname,
                                                         CongDocument *doc);
CongNodePtr         cong_node_new_element_from_dispspec (CongDispspecElement *element,
                                                         CongDocument *doc);
CongNodePtr         cong_node_new_text                  (const gchar *text,
                                                         CongDocument *doc);
CongNodePtr         cong_node_new_text_len              (const gchar *text,
                                                         int len,
                                                         CongDocument *doc);
CongNodePtr         cong_node_new_comment               (const gchar *comment,
                                                         CongDocument *doc);
void                cong_node_free                      (CongNodePtr node);
gchar *             cong_node_generate_source           (CongNodePtr node);
gchar *             cong_node_generate_child_source     (CongNodePtr node);
gchar *             cong_node_generate_source_from_byte_offset
                                                        (CongNodePtr node,
                                                         int byte_offset);
gchar *             cong_node_generate_source_up_to_byte_offset
                                                        (CongNodePtr node,
                                                         int byte_offset);
gchar *             cong_node_generate_source_between_byte_offsets
                                                        (CongNodePtr node,
                                                         int start_byte_offset,
                                                         int end_byte_offset);
void                cong_node_private_make_orphan       (CongNodePtr node);
void                cong_node_private_add_after         (CongNodePtr node,
                                                         CongNodePtr older_sibling);
void                cong_node_private_add_before        (CongNodePtr node,
                                                         CongNodePtr younger_sibling);
void                cong_node_private_set_parent        (CongNodePtr node,
                                                         CongNodePtr adoptive_parent,
                                                         gboolean add_to_end);
void                cong_node_private_set_text          (CongNodePtr node,
                                                         const gchar *new_content);
void                cong_node_private_set_attribute     (CongNodePtr node,
                                                         xmlNs *ns_ptr,
                                                         const gchar *local_attribute_name,
                                                         const gchar *value);
void                cong_node_private_remove_attribute  (CongNodePtr node,
                                                         xmlNs *ns_ptr,
                                                         const gchar *local_attribute_name);
CongNodePtr         cong_node_get_child_by_name         (CongNodePtr node,
                                                         const gchar *ns_uri,
                                                         const gchar *local_name);
CongNodePtr         cong_node_get_first_text_node_descendant
                                                        (CongNodePtr node);
gboolean            cong_node_should_be_visible_in_editor
                                                        (CongNodePtr node);
gboolean            cong_node_is_valid_cursor_location  (CongNodePtr node);
gboolean            cong_node_supports_byte_offsets     (CongNodePtr node);
gboolean            cong_node_can_be_cut                (CongNodePtr node);
gboolean            cong_node_can_be_copied             (CongNodePtr node);
int                 cong_node_get_ordering              (CongNodePtr n0,
                                                         CongNodePtr n1);
CongNodePtr         cong_node_calc_first_node_in_subtree_satisfying
                                                        (CongNodePtr node,
                                                         CongNodePredicate predicate,
                                                         gpointer user_data);
CongNodePtr         cong_node_calc_final_node_in_subtree_satisfying
                                                        (CongNodePtr node,
                                                         CongNodePredicate predicate,
                                                         gpointer user_data);
CongNodePtr         cong_node_calc_prev_node_satisfying (CongNodePtr node,
                                                         CongNodePredicate predicate,
                                                         gpointer user_data);
CongNodePtr         cong_node_calc_next_node_satisfying (CongNodePtr node,
                                                         CongNodePredicate predicate,
                                                         gpointer user_data);

Description

Details

CongNodePtr

typedef xmlNodePtr CongNodePtr;


cong_node_prev ()

CongNodePtr         cong_node_prev                      (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_next ()

CongNodePtr         cong_node_next                      (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_first_child ()

CongNodePtr         cong_node_first_child               (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_parent ()

CongNodePtr         cong_node_parent                    (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_is_element ()

gboolean            cong_node_is_element                (CongNodePtr node,
                                                         const gchar *ns_uri,
                                                         const gchar *local_name);

Handy method for deciding if you've found a element with the given name, as opposed to text nodes, comments, elements with other names etc.

node :

ns_uri :

local_name :

Returns :

TRUE if the node is an element with the correct name, FALSE otherwise

cong_node_is_element_from_set ()

gboolean            cong_node_is_element_from_set       (CongNodePtr node,
                                                         const gchar *ns_uri,
                                                         const gchar **local_name_array,
                                                         guint num_local_names,
                                                         guint *output_index);

Handy method for deciding if you've found a element with one of the given names in the set, as opposed to text nodes, comments, elements with other names etc.

node :

ns_uri :

URI of the namespace shared by all the element in the search set

local_name_array :

array of element local names within the namespace

num_local_names :

size of search array

output_index :

pointer to write index of result to, or NULL if you don't care

Returns :

TRUE if the node is an element with the correct name, FALSE otherwise

cong_node_get_ns ()

xmlNsPtr            cong_node_get_ns                    (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_get_ns_uri ()

const gchar *       cong_node_get_ns_uri                (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_get_ns_prefix ()

const gchar *       cong_node_get_ns_prefix             (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_get_local_name ()

const gchar *       cong_node_get_local_name            (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_get_qualified_name ()

gchar *             cong_node_get_qualified_name        (CongNodePtr node);

Builds a string of the form "ns_prefix:local_name" for an element inside a namespace or simply "local_name" for the rest.

node :

an XML element

Returns :

a freshly-allocated string which the caller must g_free

cong_node_get_ns_for_uri ()

xmlNsPtr            cong_node_get_ns_for_uri            (CongNodePtr node,
                                                         const gchar *ns_uri);

node :

ns_uri :

Returns :


cong_node_get_ns_for_prefix ()

xmlNsPtr            cong_node_get_ns_for_prefix         (CongNodePtr node,
                                                         const gchar *prefix);

node :

prefix :

Returns :


cong_node_get_attr_ns ()

xmlNsPtr            cong_node_get_attr_ns               (CongNodePtr node,
                                                         const char *qualified_name,
                                                         const char **output_name);

node :

qualified_name :

output_name :

Returns :


cong_node_get_path ()

gchar *             cong_node_get_path                  (CongNodePtr node);

Method for getting an XPath to the node.

node :

an XML node

Returns :

the XPath as a freshly allocated string, which must be freed using g_free

cong_node_debug_description ()

gchar *             cong_node_debug_description         (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_type_description ()

const gchar *       cong_node_type_description          (CongNodeType node_type);

TODO: Write me

node_type :

Returns :


cong_node_get_attribute ()

gchar*              cong_node_get_attribute             (CongNodePtr node,
                                                         xmlNsPtr ns_ptr,
                                                         const gchar *local_attribute_name);

Returns the content of the attribute specified through local_attribute_name and ns_ptr.

node :

XML node which has the attribute.

ns_ptr :

Attribute's namespace, can be NULL (if it is the default namespace it MUST NOT be NULL but the coresponding xmlNs).

local_attribute_name :

Name of the attribute, without namespace prefix.

Returns :

The content of the attribute, to be freed by the caller. Will be NULL if not found in node and no default in DTD available

cong_node_has_attribute ()

gboolean            cong_node_has_attribute             (CongNodePtr node,
                                                         xmlNsPtr ns_ptr,
                                                         const gchar *local_attribute_name);

node :

XML node which has the attribute.

ns_ptr :

Attribute's namespace, can be NULL (if it is the default namespace it MUST NOT be NULL but the coresponding xmlNs).

local_attribute_name :

Name of the attribute, without namespace prefix.

Returns :

Returns TRUE if the attribute specified through local_attribute_name and ns_ptr is found in the node or as default in the DTD.

cong_node_self_test ()

void                cong_node_self_test                 (CongNodePtr node);

TODO: Write me

node :


cong_node_self_test_recursive ()

void                cong_node_self_test_recursive       (CongNodePtr node);

TODO: Write me

node :


cong_node_recursive_set_doc ()

void                cong_node_recursive_set_doc         (CongNodePtr node,
                                                         xmlDocPtr xml_doc);

TODO: Write me

node :

xml_doc :


cong_node_recursive_dup ()

CongNodePtr         cong_node_recursive_dup             (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_is_descendant_of ()

gboolean            cong_node_is_descendant_of          (CongNodePtr node,
                                                         CongNodePtr potential_ancestor);

TODO: Write me

node :

potential_ancestor :

Returns :


cong_node_should_recurse ()

gboolean            cong_node_should_recurse            (CongNodePtr node);

TODO: Write me

node :

Returns :


CONG_NODE_SELF_TEST()

#define             CONG_NODE_SELF_TEST(node)

node :


cong_node_get_length ()

int                 cong_node_get_length                (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_new_element ()

CongNodePtr         cong_node_new_element               (xmlNsPtr ns,
                                                         const gchar *tagname,
                                                         CongDocument *doc);

TODO: Write me

ns :

tagname :

doc :

Returns :


cong_node_new_element_from_dispspec ()

CongNodePtr         cong_node_new_element_from_dispspec (CongDispspecElement *element,
                                                         CongDocument *doc);

TODO: Write me

element :

doc :

Returns :


cong_node_new_text ()

CongNodePtr         cong_node_new_text                  (const gchar *text,
                                                         CongDocument *doc);

TODO: Write me

text :

doc :

Returns :


cong_node_new_text_len ()

CongNodePtr         cong_node_new_text_len              (const gchar *text,
                                                         int len,
                                                         CongDocument *doc);

TODO: Write me

text :

len :

doc :

Returns :


cong_node_new_comment ()

CongNodePtr         cong_node_new_comment               (const gchar *comment,
                                                         CongDocument *doc);

comment :

doc :

Returns :


cong_node_free ()

void                cong_node_free                      (CongNodePtr node);

TODO: Write me

node :


cong_node_generate_source ()

gchar *             cong_node_generate_source           (CongNodePtr node);

Generate XML source for the node

node :

The node for which the XML source is to be generated

Returns :

the XML source for the node as a UTF8 string. The caller is responsible for freeing this with g_free

cong_node_generate_child_source ()

gchar *             cong_node_generate_child_source     (CongNodePtr node);

Generate XML source for the node's children, concatenated together as a UTF8 string. Should handle entity references correctly. The result does not include the XML source for the node itself.

node :

The parent node

Returns :

the XML source for the node's children as a UTF8 string. The caller is responsible for freeing this with g_free

cong_node_generate_source_from_byte_offset ()

gchar *             cong_node_generate_source_from_byte_offset
                                                        (CongNodePtr node,
                                                         int byte_offset);

TODO: Write me

node :

byte_offset :

Returns :


cong_node_generate_source_up_to_byte_offset ()

gchar *             cong_node_generate_source_up_to_byte_offset
                                                        (CongNodePtr node,
                                                         int byte_offset);

TODO: Write me

node :

byte_offset :

Returns :


cong_node_generate_source_between_byte_offsets ()

gchar *             cong_node_generate_source_between_byte_offsets
                                                        (CongNodePtr node,
                                                         int start_byte_offset,
                                                         int end_byte_offset);

TODO: Write me

node :

start_byte_offset :

end_byte_offset :

Returns :


cong_node_private_make_orphan ()

void                cong_node_private_make_orphan       (CongNodePtr node);

TODO: Write me

node :


cong_node_private_add_after ()

void                cong_node_private_add_after         (CongNodePtr node,
                                                         CongNodePtr older_sibling);

TODO: Write me

node :

older_sibling :


cong_node_private_add_before ()

void                cong_node_private_add_before        (CongNodePtr node,
                                                         CongNodePtr younger_sibling);

TODO: Write me

node :

younger_sibling :


cong_node_private_set_parent ()

void                cong_node_private_set_parent        (CongNodePtr node,
                                                         CongNodePtr adoptive_parent,
                                                         gboolean add_to_end);

TODO: Write me

node :

adoptive_parent :

add_to_end :


cong_node_private_set_text ()

void                cong_node_private_set_text          (CongNodePtr node,
                                                         const gchar *new_content);

TODO: Write me

node :

new_content :


cong_node_private_set_attribute ()

void                cong_node_private_set_attribute     (CongNodePtr node,
                                                         xmlNs *ns_ptr,
                                                         const gchar *local_attribute_name,
                                                         const gchar *value);

TODO: Write me

node :

ns_ptr :

local_attribute_name :

value :


cong_node_private_remove_attribute ()

void                cong_node_private_remove_attribute  (CongNodePtr node,
                                                         xmlNs *ns_ptr,
                                                         const gchar *local_attribute_name);

TODO: Write me

node :

ns_ptr :

local_attribute_name :


cong_node_get_child_by_name ()

CongNodePtr         cong_node_get_child_by_name         (CongNodePtr node,
                                                         const gchar *ns_uri,
                                                         const gchar *local_name);

This function searches the children of node looking for elements of the given name.

node :

the parent node

ns_uri :

URI of namespace to search for, or NULL

local_name :

the local name within any namespace of the element to search for

Returns :

the first child element matching the given name, or NULL if there are none

cong_node_get_first_text_node_descendant ()

CongNodePtr         cong_node_get_first_text_node_descendant
                                                        (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_should_be_visible_in_editor ()

gboolean            cong_node_should_be_visible_in_editor
                                                        (CongNodePtr node);

The function determines if the node ought to be visible in the main editor view.

As described in bug 123367, TEXT nodes that are either empty or purely whitespace should only appear in the main editor view if the DTD allows PCDATA at the location in the document. Otherwise the text is probably merely formatting to prettify the source view. *

node :

a node to be tested

Returns :

a gboolean which is TRUE iff the node ought to be visible in the main editor view

cong_node_is_valid_cursor_location ()

gboolean            cong_node_is_valid_cursor_location  (CongNodePtr node);

The function detemines if the node is a suitable location for the cursor.

It currently only tests for TEXT nodes, but will eventually be expanded to allow COMMENT nodes as well.

node :

a node to be tested

Returns :

a gboolean which is TRUE iff it is safe to put the cursor inside this node

cong_node_supports_byte_offsets ()

gboolean            cong_node_supports_byte_offsets     (CongNodePtr node);

The function determines if CongLocation objects that reference this node can have meaningful byte offsets

Only TEXT, COMMENT and CDATA_SECTION nodes can currently have meaningful byte offsets.

node :

a node to be tested

Returns :

a gboolean which is TRUE if CongLocations that reference this node can have a meaningful byte offset

cong_node_can_be_cut ()

gboolean            cong_node_can_be_cut                (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_can_be_copied ()

gboolean            cong_node_can_be_copied             (CongNodePtr node);

TODO: Write me

node :

Returns :


cong_node_get_ordering ()

int                 cong_node_get_ordering              (CongNodePtr n0,
                                                         CongNodePtr n1);

This functions compares the location of two nodes in the xml tree and returns a numeric comparsion representing their locations in a depth-first traversal.

n0 :

first node to be compared

n1 :

second node to be compared

Returns :

negative if n0 is reached before n1, zero if they are the same node, positive if n0 is reached after n1

cong_node_calc_first_node_in_subtree_satisfying ()

CongNodePtr         cong_node_calc_first_node_in_subtree_satisfying
                                                        (CongNodePtr node,
                                                         CongNodePredicate predicate,
                                                         gpointer user_data);

Finds the first node in a depth-first traversal of the subtree below this node that satisfies the predicate.

Note that node is the initial node of the tree (and hence is tested first)

node :

the top of the subtree

predicate :

the CongNodePredicate to test nodes for

user_data :

user-supplied data passed to the predicate

Returns :

the appropriate node satisfying predicate, or NULL if there are none

cong_node_calc_final_node_in_subtree_satisfying ()

CongNodePtr         cong_node_calc_final_node_in_subtree_satisfying
                                                        (CongNodePtr node,
                                                         CongNodePredicate predicate,
                                                         gpointer user_data);

Finds the final node in a depth-first traversal of the subtree below this node that satisfies the predicate.

Note that node is the initial node of the tree (and hence is tested last)

node :

the top of the subtree

predicate :

the CongNodePredicate to test nodes for

user_data :

user-supplied data passed to the predicate

Returns :

the appropriate node satisfying predicate, or NULL if there are none

cong_node_calc_prev_node_satisfying ()

CongNodePtr         cong_node_calc_prev_node_satisfying (CongNodePtr node,
                                                         CongNodePredicate predicate,
                                                         gpointer user_data);

Finds the first preceding node relative to the input that satisfies the predicate, in an imagined depth-first traversal of the document. Includes ancestors.

node :

the start of the search

predicate :

the CongNodePredicate to test nodes for

user_data :

user-supplied data passed to the predicate

Returns :

the appropriate node satisfying predicate, or NULL if there are none

cong_node_calc_next_node_satisfying ()

CongNodePtr         cong_node_calc_next_node_satisfying (CongNodePtr node,
                                                         CongNodePredicate predicate,
                                                         gpointer user_data);

Finds the first following node relative to the input that satisfies the predicate, in an imagined depth-first traversal of the document. Includes ancestors.

node :

the start of the search

predicate :

the CongNodePredicate to test nodes for

user_data :

user-supplied data passed to the predicate

Returns :

the appropriate node satisfying predicate, or NULL if there are none