libgdome-ruby 0.3       http://libgdome-ruby.berlios.de/

libgdome-ruby is a ruby extension that provides the DOM level 2 Core API for
accessing XML documents.  It is implemented as a wrapper around the libgdome
library (aka gdome2) which in turn uses another library called libxml.


Installation
============

libgdome-ruby depends on the following libraries:

glib     >= 1.2.10      http://www.gtk.org/
libxml2  >= 2.4.19      http://xmlsoft.org/
gdome2   >= 0.7.1       http://phd.cs.unibo.it/gdome2/

You also need a working Ruby 1.6.x inbstallation. When you meet these
requirements, run
# ruby extconf.rb
# make
# make install


Documentation
=============

libgdome-ruby provides the DOM level 2 Core API for ruby.  Read about it at
http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/ .  This is the
official DOM level 2 Core documentation.

The following changes have been made with respect to the official API:
1) Trivial changes (Things that you would have expected)
- interfaces are implemented as ruby classes
- unsigned short and unsigned long are implemented as ruby's numeric types
- boolean is mapped to true/false when libgdome-ruby returns a boolean value.
  When a boolean parameter is expected, everything but false and nil is
  evaluated as true

2) Other changes (Things important to know)
- the Module which contains all the DOM classes and constants outside
  interfaces is called "Dom" (instead of "dom")
- the module function Dom::implementation creates a DOMImplementation object
- methods returning a boolean value end with a question mark
- the same is true for boolean attributes:  The read access method ends with a
  question mark
- attribute write access methods end with the equal sign (=)
- DOMString is not implemented.  Instead, use ruby's strings, and encode your
  strings in utf8
- The same node of a DOM tree can be referred to by two or more different ruby
  objects.  Thus, you can not tell wether two ruby variables point to the same
  DOM node by comparing their id.  Instead you should use the method gdome_id
  if you really need this test.  This should only be necessary for debugging!
- the DOM objects in gdome are reference counted.  If you need to access the
  current internal reference count, you can read it with the method ref_count.
  This is only meant for debugging!
- document loading and saving support:  Documents can be loaded and saved using
  the following additional methods of class DOMImplementation:
  createDocFromURI(uri, mode)  loads an XML Document from a URI and returns a
                               Document object. If mode is Dom::LOAD_PARSING
                               the document must be well formed, if mode is
                               Dom::LOAD_VALIDATING the document must valid and
                               if mode is Dom::LOAD_RECOVERING a DOM tree is
                               built anyway.  If the
                               GDOME_LOAD_SUBSTITUTE_ENTITIES flag is or-ed in,
                               entity substitution is performed.  If the
                               GDOME_LOAD_COMPLETE_ATTR flag is or-ed in, the
                               tree is populated with default attributes from
                               the DTD
  createDocFromMemory(string, mode) loads an XML Document from a string and
                               returns a Document object.  mode has the same
                                meaning as in createDocFromURI
  saveDocToFile(doc, filename, mode) saves document doc in file filename,
                               returns true on success.  mode is either
                               GDOME_SAVE_STANDARD or GDOME_SAVE_LIBXML_INDENT.
                               The latter constant causes some indentation of
                               the output
  saveDocToString(doc, mode)   saves the DOM tree of the Document specified to
                               a string (this string is returned).  mode has
                               the same meaning as in saveFormatFile


A few examples are present in the examples subdirectory. Look at them for a
quick start after reading the official DOM 2 Core specification.

MEMORY CONVENTION
=================
Most of the time, memory management is handled automatically by the wrapper
objects in conjunction with the underlying C library.  It is, however,
IMPORTANT that you know about a memory management convention in libgdome:

The DOM defines a tree based data structure, and it is possible to detach
subtrees from the main tree using methods like Node::removeChild,
Node::replaceChild, or create Nodes outside the main tree with the
Document::create* methods.

The convention is, that such a detached subtree is deleted as soon as the root
node of the detached subtree is no longer referenced.  Be sure to understand
this: A detached subtree is deleted when its root is no longer referenced, even
if it contains nodes that are still referenced by your program.  These nodes
are then rendered unusable, the only thing you can do with them is to let the
garbace collector collect them.  And if you want to keep such a detached
subtree in memory, be sure to keep a wrapper object to its root node in scope.
There is no need to do the same with the main tree (the one with the Document
node as the root).

BUGS
====
If you find bugs, please report them by e-mail.

CONTACT
=======
libgdome-ruby is maintained by Tobias Peters <t-peters@users.berlios.de>.


LEGAL
=====
Copyright (C) 2001 2002  Tobias Peters

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

libgdome-ruby 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
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with libgdome-ruby in a file called COPYING.LIB; if
not, write to the Free Software Foundation, Inc., 59 Temple Place,
Suite 330, Boston, MA  02111-1307  USA


The file dom.idl included in this distribution is provided under the terms of
the W3C software license.  See the files dom.idl and COPYING.dom.idl for
details.
