libgdome-ruby 0.1       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.x       http://www.gtk.org/
zlib     >= 1.x         http://www.gzip.org/zlib.tar.gz
libxml2  >= 2.3.x       http://xmlsoft.org/
gdome2   >= 0.6.7       http://www.cs.unibo.it/%7Ecasarini/gdome2/

You also need a working ruby inbstallation. Ruby 1.4.3 worked for me.

Depending on your system (read: Windows) you might also need other libraries
like libiconv. I will add a detailed description on how to install
libgdome-ruby on windows when I have actually done that.

Then, 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 produces 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:
  parseFile(uri)               parses an XML file and returns a Document object
  validateFile(uri)            parses and validates an XML file and returns a
                               Document object
  saveFile(filename, doc)      saves document doc in file filename, returns
                               true on success
  saveFormatFile(filename, doc, mode) saves document doc in file filename,
                               returns true on success. mode is either
                               Dom::SAVE_STANDARD or Dom::SAVE_LIBXML_INDENT.
                               The latter constant causes some indentation of
                               the output.
  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.
  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) the same as saveFormatFile, only the
                               parameters are in a different order
  saveDocToMemory(doc, mode)   saves the DOM tree of the Document specified to
                               a string. 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.


BUGS
====
There is currently a memory leak in libgdome-ruby. While all gdome2 objects are
properly deleted by ruby's garbage collection, the XML document representation
used by gdome2 is not deleted automatically. This will be resolved, either by
a future version of gdome2 (not before release 0.6.9), or by the next release
of libgdome-ruby. We are currently discussing how this should be handled by
the underlying C library.

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

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


LEGAL
=====
Copyright (C) 2001  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

Copyright (c) 2000 World Wide Web Consortium (Massachusetts Institute of
Technology, Institut National de Recherche en Informatique et en Automatique,
Keio University). All Rights Reserved.
 
and provided under the terms of the W3C software license. See the files
dom.idl and COPYING.dom.idl for details.
