Lua bindings for libxml2

Peter S. Housel

August 2003–January 2004

Copyright

This is the Monday Lua-libxml library, used to interface to the libxml library from the Lua extension language.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Introduction

Many bindings have been provided for the Lua extension language. This library provides a rudimentary Lua binding for Daniel Veillard's libxml (also known as gnome-xml). This binding focuses on the DOM-style interface to libxml, and provides a “DOM-inspired” interface. (The gdome library was used as a reference for implementing DOM methods on top of the libxml base.)

<Module lua-libxml.h>=

#ifndef LUA_LIBXML_H
#define LUA_LIBXML_H

int luaopen_libxml(lua_State *L);

#endif

<Module lua-libxml.c>=

#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <limits.h>

#ifdef DEBUG
#include <stdio.h>
#endif

#if defined(HAVE_LUA_H)
#include <lua.h>
#include <lauxlib.h>
#elif defined(HAVE_LUA50_LUA_H)
#include <lua50/lua.h>
#include <lua50/lauxlib.h>
#endif

#include <libxml/tree.h>
#include <libxml/parser.h>
#include <libxml/globals.h>

<Other includes>

#include "lua-libxml.h"

<Implementation declarations>
<C implementation definitions>
int
luaopen_libxml(lua_State *L) {
  static const struct luaL_reg libxml[] = {
    <Functions registered in the libxml table>
    {NULL, NULL}
  };
  static const struct luaL_reg libxslt[] = {
    <Functions registered in the libxsltl table>
    {NULL, NULL}
  };
  <Initialize libxml>
  luaL_openlib(L, "libxml", libxml, 0);
  luaL_openlib(L, "libxslt", libxslt, 0);
  return 2;
}

DTDs are good. Fully expanded entities are also good.

<Initialize libxml>=

xmlLoadExtDtdDefaultValue = 1;
xmlSubstituteEntitiesDefault(1);

Namespace Construction

The Document Object Model (DOM) defines a module named dom defining a number of interfaces such as Node, NodeList, Document, and so on. Here we define our equivalent of this namespace layout, with a global dom table.

<Initialize libxml>+=

lua_pushstring(L, "dom");
lua_newtable(L);
<Insert namespace items into the dom table>
lua_settable(L, LUA_GLOBALSINDEX);

Memory Management

Pointers from Lua to C data structures require the use of either light or full userdata. In order to allow the use of metatable methods, full userdata items must be used.

Since libxml handles allocating its own data structures, the only thing we need to store in our userdata items is a pointer to these structures—in effect a “boxed pointer”.

<Implementation declarations>=

struct box {
  void *ptr;
};

We want to insure that a unique boxed pointer full userdata exists for any given libxml object. We'll do this using a weak table, keyed on a light userdata also pointing to the object. We'll locate the weak table by storing it in the registry, keyed on a light userdata pointer to some random address.

<Implementation declarations>+=

static int unique_table;

<Initialize libxml>+=

lua_pushlightuserdata(L, &unique_table);
lua_newtable(L);                /* weak table */
lua_newtable(L);                /* metatable for weak table */
lua_pushliteral(L, "__mode");
lua_pushliteral(L, "kv");       /* both keys and values are weak */
lua_settable(L, -3);
lua_setmetatable(L, -2);
lua_settable(L, LUA_REGISTRYINDEX);

There is no automatic memory managment in libxml; nodes belong to the document they are a part of and are usually only freed when the entire document is freed. This means that we can not free anything when the "gc" method of an xmlNode internal to a document is called. Furthermore, we cannot free the document when its "gc" method is called if there are still any userdata containing internal pointers.

Fortunately each node contains a pointer to the document it belongs to. We can use this to maintain a reference count of userdata items pointing to internal nodes. When the last reference to a node in the document is collected, then we can free the entire document.

<Implementation declarations>+=

struct document_private {
  unsigned refcount;
};

The DOM `Node` and `NodeList` Interfaces

The base interface for most of the DOM interfaces we're interested in is the Node interface.

<Insert namespace items into the dom table>=

lua_pushstring(L, "Node");
lua_newtable(L);
<Insert namespace items into the dom.Node table>
<Register items that are subtypes of dom.Node>
lua_settable(L, -3);

The following values can be returned for the nodeType attribute:

<Implementation declarations>+=

#define NodeTypeDefs \
  NODETYPE(ELEMENT_NODE, 1) \
  NODETYPE(ATTRIBUTE_NODE, 2) \
  NODETYPE(TEXT_NODE, 3) \
  NODETYPE(CDATA_SECTION_NODE, 4) \
  NODETYPE(ENTITY_REFERENCE_NODE, 5) \
  NODETYPE(ENTITY_NODE, 6) \
  NODETYPE(PROCESSING_INSTRUCTION_NODE, 7) \
  NODETYPE(COMMENT_NODE, 8) \
  NODETYPE(DOCUMENT_NODE, 9) \
  NODETYPE(DOCUMENT_TYPE_NODE, 10) \
  NODETYPE(DOCUMENT_FRAGMENT_NODE, 11) \
  NODETYPE(NOTATION_NODE, 12)

enum NodeType {
#define NODETYPE(name, value) name = value,
NodeTypeDefs
#undef NODETYPE
};

<Insert namespace items into the dom.Node table>=

#define NODETYPE(name, value) \
  lua_pushstring(L, #name); \
  lua_pushnumber(L, (lua_Number) value); \
  lua_settable(L, -3);
NodeTypeDefs
#undef NODETYPE

This routine takes an xmlNode pointer and pushes it onto the Lua stack. If it is necessary to create a new userdata, it determines the appropritate metatable..

<C implementation definitions>=

static int
luaX_pushxmlNode(lua_State *L, xmlNode *node) {
  if(node == NULL) {
    lua_pushnil(L);
    return 1;
  } else {
    lua_pushlightuserdata(L, &unique_table);
    lua_gettable(L, LUA_REGISTRYINDEX);
    lua_pushlightuserdata(L, node);
    lua_rawget(L, -2);
    if(!lua_isnil(L, -1)) {
      lua_remove(L, -2);
#ifdef DEBUG
      fprintf(stderr, "Userdata for %p is old\n", node);
#endif
      return 1;
    } else {
      struct box *sb;
      char *mtname = NULL;
      switch(node->type) {
      <Cases for xmlNode types in luaX_pushxmlNode>
      default:
        luaL_error(L, "can't push XML node type %d", node->type);
        return 0;
      }
      sb = lua_newuserdata(L, sizeof(struct box));
      sb->ptr = node;
      luaL_getmetatable(L, mtname);
      lua_setmetatable(L, -2);
      <Add the new userdata to the unique_table>
      lua_replace(L, -3);
      lua_pop(L, 1);

      <Increment the document's count of internal references>
#ifdef DEBUG
      fprintf(stderr, "Userdata for %p (type %s) is new\n", node, mtname);
#endif
      return 1;
    }
  }
}

We need to add the newly-created userdata to the unique_table. At this point the Lua stack contains the unique_table, a nil, and the new full userdata.

<Add the new userdata to the unique_table>=

lua_pushlightuserdata(L, node);
lua_pushvalue(L, -2);
lua_rawset(L, -5);

When the userdata is new then we can increment the reference count.

<Increment the document's count of internal references>=

{
  xmlDoc *doc = node->doc;
  struct document_private *private = doc->_private;
  ++(private->refcount);
#ifdef DEBUG
  fprintf(stderr, "document %p now has %u references\n",
          doc, private->refcount);
#endif
}

When a reference to a node is freed, we decrement the refernece count.

<Implementation declarations>+=

static int dom_Node__gc(lua_State *L);

Copyright

Introduction

Namespace Construction

Memory Management

The DOM Node and NodeList Interfaces

The Document Node

Element Nodes

Text Nodes

Comment Nodes

Output Support

Catalog Support

XSLT Support

Parsing Stylesheets

Applying Stylesheets

Saving Results

Stylesheet Garbage Collection

The DOM `Node` and `NodeList` Interfaces