forked from KolibriOS/kolibrios
203 lines
7.6 KiB
Plaintext
203 lines
7.6 KiB
Plaintext
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
|