$Header: /spare2/ecila-cvsroot/XML-RDF/README,v 1.1.1.1 1999/03/24 17:55:57 ecila40 Exp $

NAME
       XML::RDF - A perl module for parsing XML RDF documents

SYNOPSIS
	 use XML::RDF;

	 $p = XML::RDF->new('RDFHandlers' => {
			    'Description' => \&description_start,
			    '/Description' => \&description_end,
			    'Bag' => \&bag_start,
			    '/Bag' => \&bag_end,
			    },
			    'Style' => 'Stream',
			   );
	 $p->parsefile('file.rdf');


DESCRIPTION
       This module is a subclass of XML::Parser class. The basic
       functions provided by XML::Parser are not modified. A few
       handlers have been added to provide easier access to RDF
       specificities.

       When creating an XML::RDF object the Namespaces option is
       automatically set.

METHODS
       setRDFHandlers(TYPE, HANDLER, [, TYPE, HANDLER [...]])
	   This method registers handlers for various parser
	   events. It overrides previous handlers registered
	   through RDFHandlers option. If HANDLERS is set to
	   undef the corresponding handler is removed.	See a
	   description of the handler types in the section on
	   HANDLERS.

       resetRDFHandlers()
	   This method removes all the handlers registered
	   through RDFHandlers option or the setRDFHandlers
	   method.

HANDLERS
       The most complex handlers are related to containers. The
       idea is that XML::RDF will collect the elements from the
       container, store them in a list and provide them to the
       handler registered for the end tag of the container (/Bag,
       /Seq or /Alt). When the elements of the container are
       simple as in:

	 <Bag>
	  <li resource="http://www.foo.org/"/>
	  <li resource="http://www.bar.org/"/>
	 </Bag>

       it's enough to register a handler for /Bag to get the list
       of elements.  However, if the container looks like this:

	 <Bag>
	  <li> <Description resource="http://www.foo.org/"/> </li>
	  <li> <Description resource="http://www.bar.org/"/> </li>
	 </Bag>

       you must provide the ContainerItem handler that will be
       called for every recognized XML construct within each
       <li>. This handler is expected to collect data that will
       built the item list.

       When the /Bag, /Seq or /Alt handlers are called, their
       Content argument has the following structure, if <li> tags
       were used:

	  [
	    {
	      'attlist' => [ Attr, Val ... ],  # Attribute list from <li> tag.
	      'char' => 'abcde...',	       # Text between <li></li> if no
					       # ContainerItem handler.
	      ...			       # whatever was added by ContainerItem.
	    }
	    ...
	  ]

       or the following structure if _[0-9]+ attributes were
       used:

	  [
	    'abcde...',			       # value of _0
	    undef,			       # _1 was not specified
	    'abcde...',			       # value of _2
	    ...
	  ]


       Description    (Expat, about, ID, aboutEach,
       aboutEachPrefix, bagID [, Attr, Val [,...]])

       This event is generated when the <Description> tag is
       recognized.

       /Description	(Expat)

       This event is generated when the </Description> tag is
       recognized.

       Bag		(Expat, Element [, Attr, Val [,...]])

       This event is generated when the <Bag> tag is recognized.
       If the attributes contain _[0-9]+ style names, they are
       removed from the list given in argument.	 The Element
       argument is provided so that it's possible to register
       only one function for the Bag, Alt and Seq Handlers.

       Alt		(Expat, Element [, Attr, Val [,...]])

       This event is generated when the <Alt> tag is recognized.
       If the attributes contain _[0-9]+ style names, they are
       removed from the list given in argument.	 The Element
       argument is provided so that it's possible to register
       only one function for the Bag, Alt and Seq Handlers.

       Seq		(Expat, Element [, Attr, Val [,...]])

       This event is generated when the <Seq> tag is recognized.
       If the attributes contain _[0-9]+ style names, they are
       removed from the list given in argument.	 The Element
       argument is provided so that it's possible to register
       only one function for the Bag, Alt and Seq Handlers.

       ContainerItem	(ItemHash, Event, Expat [...])

       This event is generated whenever a Start, End, Char or
       Proc event occur and that the context is a <li> within a
       container. The ItemHash is a reference to a hash table
       that the ContainerItem is expected to fill.  The attlist
       member of this hash table is reserved. The Event arguement
       is either Start, End, Char or Proc. The remaining
       arguments are the arguments given to the corresponding
       event.

       If no ContainerItem is registered a default action is
       associated to the Char event. It appends the String
       argument to the char member of the ItemHash table.

       /Bag		 (Expat, Element, Attlist, Content)

       This event is generated when the </Bag> tag is recognized.
       See above for a description of the Content argument.
       Attlist is a reference to an array containing the
       attributes found in the <li> tag.  The Element argument is
       provided so that it's possible to register only one
       function for the /Bag, /Alt and /Seq Handlers.

       /Alt		 (Expat, Element, Attlist, Content)

       This event is generated when the </Alt> tag is recognized.
       See above for a description of the Content argument.
       Attlist is a reference to an array containing the
       attributes found in the <li> tag.  The Element argument is
       provided so that it's possible to register only one
       function for the /Bag, /Alt and /Seq Handlers.

       /Seq		 (Expat, Element, Attlist, Content)

       This event is generated when the </Seq> tag is recognized.
       See above for a description of the Content argument.
       Attlist is a reference to an array containing the
       attributes found in the <li> tag.  The Element argument is
       provided so that it's possible to register only one
       function for the /Bag, /Alt and /Seq Handlers.

BUGS
       This is an early alpha version. It does not provide
       complete RDF support and is not fully tested.
       Contributions and critics are wellcome.

       The latest version may be found on http://www.senga.org/.

AUTHOR
       Loic Dachary <loic@senga.org> who was forced to contribute
       this module but is very willing to surrender :-)