kolibrios/contrib/network/netsurf/libhubbub/docs/Treebuilder

Hubbub treebuilding interface
=============================

Introduction
------------

  hubbub uses an interface to build a tree.  this is what the functions should
  do.

Types
-----

  hubbub_string
  -------------


Reference counting
------------------

  The callback interface provides hooks to allow tree nodes to be reference 
  counted.  There is, however, no requirement that the client actually performs
  reference counting.  It is perfectly acceptable to use some other object use
  tracking scheme (e.g. garbage collection).  The descriptions below describe
  the expected reference counting behaviour, regardless.


Callback behaviour
------------------
  
  The first parameter to all callbacks is the context passed to the library
  on initialisation.
  
  All node creation functions should return 0 on success, and something else
  on failure.
  
  
  Node creation
  -------------
  
  | int hubbub_tree_create_comment(void *ctx,
  |                                const hubbub_string *data,
  |                                void **result);
  |
  | int hubbub_tree_create_doctype(void *ctx,
  |                                const hubbub_doctype *doctype,
  |                                void **result);
  |
  | int hubbub_tree_create_element(void *ctx,
  |                                const hubbub_tag *tag,
  |                                void **result);
  |
  | int hubbub_tree_create_text(void *ctx,
  |                             const hubbub_string *data,
  |                             void **result);
  
  All node creation functions must create a node with the information passed
  in their second argument, and place a pointer to that node in *result.  The
  reference count of the created node must be set to 1.
  
  
  | int hubbub_tree_clone_node(void *ctx,
  |                            void *node,
  |                            bool deep,
  |                            void **result);
  
  If deep == false, then this function must duplicate "node" and none of its
  children, and place a pointer to the clone in *result.  It must also set the
  reference count of the clone to 1.  The clone must be isolated from the 
  document tree (it must have no parent or sibling nodes).
  
  If deep == true, then this function must duplicate "node" and all of its
  children.  A pointer to the clone of "node" must be placed in *result.  The
  reference count of the clone must be set to 1.  The reference count of all
  other created nodes must be set to 0. The clone must also be isolated from
  the document tree (it must have no parent or sibling nodes).
  
  
  
  Reference counting
  ------------------
  
  | int hubbub_tree_ref_node(void *ctx, void *node);
  | int hubbub_tree_unref_node(void *ctx, void *node);
  
  These functions should increase and decrease the reference count of "node",
  respectively.  If the reference count of "node" falls to zero, and it is
  isolated from the document tree (it has no parent or sibling nodes), then
  it must be destroyed. 
  
  
  
  Tree manipulation
  -----------------
  
  | int hubbub_tree_append_child(void *ctx,
  |                              void *parent,
  |                              void *child,
  |                              void **result);
  
  This function must append the node "child" to the end of the list of children
  of the node "parent", and place a pointer to the newly-inserted node in
  *result.
  
  If the node "child" is a text node, and the last child node of "parent" is
  also a text node, then instead the text of "child" must be appended to that
  node, and a pointer to the node thus appended to must be placed in *result.
  
  In any case, the reference count of the node pointed to by *result at the end
  of these steps must be incremented.
  
  
  | int hubbub_tree_insert_before(void *ctx,
  |                               void *parent,
  |                               void *child,
  |                               void *ref_child,
  |                               void **result);
  
  This function must insert the node "child" into the list of children of
  "parent" immediately before the node "ref_child", and place a pointer to the
  newly-inserted node in *result.
  
  If the node "child" is a text node, and the node "ref_child" or the node
  before "ref_child" is also a text node, then instead the text of "child" must
  be prepended to the text of "ref_child", or appended to the text of node
  before "ref_node", and a pointer to the node thus appended to must be placed
  in *result.
  
  In any case, the reference count of the node pointed to by *result at the end
  of these steps must be incremented.
  
  
  | int hubbub_tree_remove_child(void *ctx,
  |                              void *parent,
  |                              void *child,
  |                              void **result);
  
  This function must remove the node "child" from the document tree.  It must
  increment the reference count of the node "child", and place a pointer to
  the newly-removed node in *result.
  
  
  | int hubbub_tree_reparent_children(void *ctx,
  |                                   void *node,
  |                                   void *new_parent);

  This function must detach all children from "node" and insert them into 
  "new_parent" in the same order as they were found in "node".
  
  | int hubbub_tree_get_parent(void *ctx,
  |                            void *node,
  |                            bool element_only,
  |                            void **result);
  
  This function must retrieve the parent of "node".  If there is no parent 
  node, then NULL must be placed in *result.  Otherwise, it must increment 
  the reference count of the parent, and place a pointer to the parent in 
  *result.

  If "element_only" == true and the retrieved parent is not an element node,
  then act as if no parent exists. 

  | int hubbub_tree_has_children(void *ctx,
  |                              void *node,
  |                              bool *result);

  If "node" has any child nodes attached to it, then *result must be set to 
  true.  Otherwise, *result must be set to false.  
 
  | int hubbub_tree_form_associate(void *ctx,
  |                                void *form,
  |                                void *node);

  This function must associate "node" with the node "form" (which is the 
  currently active form element). 

  | int hubbub_tree_add_attributes(void *ctx,
  |                                void *node,
  |                                const hubbub_attribute *attributes,
  |                                uint32_t n_attributes);
 
  For each attribute in the array "attributes", this function must check to
  see if there is such an attribute already present on "node".  If there is
  not such an attribute, then the attribute must be added to "node". 
  
  | int hubbub_tree_set_quirks_mode(void *ctx,
  |                                 hubbub_quirks_mode mode);

  This function must set the quirks mode flag of the document to "mode".

  | int hubbub_tree_encoding_change(void *ctx,
  |                                 const char *name);
  
  This function is called when a meta tag which specifies a charset is seen
  in the treebuilder. [1]  The client is responsible for checking if the
  encoding the document is being processed as should actually be changed, and
  if it should, this function should return 1.  In this case, the parser
  instance will return the error code HUBBUB_ENCODINGCHANGE when it returns
  from parsing the chunk that triggered the encoding change.  The parser
  instance should then be destroyed and a new one created with that encoding
  specified.
  
  [1] http://www.whatwg.org/specs/web-apps/current-work/#in-head