Re: [xml] libxml2 API crazy?

[Nikita Churaev <lamefun x0r gmail com>]

> What do you want to achieve ? I think I understand but it is better if
> stated.

Make so you can use libxml2 and be sure that you use it correctly rather
than just blindly guess.

The main problem here is casting quirks, libxml2 tree seems to cast
xmlDoc*, xmlAttr* and even xmlNs* into xmlNode*, so not only the fields
after the common node parts are unsafe to access without checking, even
ones in the common part are, except xmlElementType type. The
documentation provides no answer whatsoever on what structures
correspond to each xmlElementType. Casting xmlNs* to xmlNode* is the
worst one.

I want to add:

safe casting functions, for example:

xmlNodePtr xmlDocToNode(xmlDocPtr node); 

xmlDocPtr xmlNodeToDoc(xmlNodePtr node); // returns NULL if 
                                         // node is not a doc

safe accessor functions for the common part (this might not be needed if
casting of xmlNs* to xmlNode* is only needed for dead code), for
example:

xmlNodePtr
xmlGetNextSibling (xmlNodePtr node)
{
    if (node == NULL)
        return NULL;

    /* struct _xmlNs, doesn't have the common node part */
    if (node->type == XML_NAMESPACE_DECL)
        return NULL;

    return node->next;
}

documentation, eg:

https://github.com/lamefun/libxml2/blob/5e06cbb88c1debbfbb8ad047e0a2e46f691cf09e/include/libxml/tree.h#L572

> Probably don't need to scrap
> everything, but reorganize in an easy to follow/review set.

I moved too many functions around the tree.h and tree.c, this will make
the patch hard to read. I'll just do all the same changes I made, but
without moving stuff around too much.

> The key point is the absolute imperative of keeping API and ABI
> stability.

I don't want to break anything. I'll add documentation (only editing the
comments), and add some new functions that hide all the crazy things.

> I would also prefer to not add too many new entry points
> for both human and technical reasons (first because the API is confusingly
> too big already, and second because the resolution of all entry points in
> ELF shared library may turn quadratic and we are already quite big)

I think the human problem is solvable by adding categories in the
documentation.

Also, things will be much more simple if casting xmlNs* to xmlNode* is
only used by dead code and is not a normal behavior, like some people
suggested on IRC, the common part will them be safe to access directly.