## 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