Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for xml::grove (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

XML::Grove(3)		       User Contributed Perl Documentation		    XML::Grove(3)

       XML::Grove - Perl-style XML objects

	use XML::Grove;

	# Basic parsing and grove building
	use XML::Grove::Builder;
	use XML::Parser::PerlSAX;
	$grove_builder = XML::Grove::Builder->new;
	$parser = XML::Parser::PerlSAX->new ( Handler => $grove_builder );
	$document = $parser->parse ( Source => { SystemId => 'filename' } );

	# Creating new objects
	$document = XML::Grove::Document->new ( Contents => [ ] );
	$element = XML::Grove::Element->new ( Name => 'tag',
					      Attributes => { },
					      Contents => [ ] );

	# Accessing XML objects
	$tag_name = $element->{Name};
	$contents = $element->{Contents};
	$parent = $element->{Parent};
	$characters->{Data} = 'XML is fun!';

       XML::Grove is a tree-based object model for accessing the information set of parsed or
       stored XML, HTML, or SGML instances.  XML::Grove objects are Perl hashes and arrays where
       you access the properties of the objects using normal Perl syntax:

	 $text = $characters->{Data};

       How To Create a Grove

       There are several ways for groves to come into being, they can be read from a file or
       string using a parser and a grove builder, they can be created by your Perl code using the
       `"new()"' methods of XML::Grove::Objects, or databases or other sources can act as groves.

       The most common way to build groves is using a parser and a grove builder.  The parser is
       the package that reads the characters of an XML file, recognizes the XML syntax, and pro-
       duces ``events'' reporting when elements (tags), text (characters), processing instruc-
       tions, and other sequences occur.  A grove builder receives (``consumes'' or ``handles'')
       these events and builds XML::Grove objects.  The last thing the parser does is return the
       XML::Grove::Document object that the grove builder created, with all of it's elements and
       character data.

       The most common parser and grove builder are XML::Parser::PerlSAX (in libxml-perl) and
       XML::Grove::Builder.  To build a grove, create the grove builder first:

	 $grove_builder = XML::Grove::Builder->new;

       Then create the parser, passing it the grove builder as it's handler:

	 $parser = XML::Parser::PerlSAX->new ( Handler => $grove_builder );

       This associates the grove builder with the parser so that every time you parse a document
       with this parser it will return an XML::Grove::Document object.	To parse a file, use the
       `"Source"' parameter to the `"parse()"' method containing a `"SystemId"' parameter (URL or
       path) of the file you want to parse:

	 $document = $parser->parse ( Source => { SystemId => 'kjv.xml' } );

       To parse a string held in a Perl variable, use the `"Source"' parameter containing a
       `"String"' parameter:

	 $document = $parser->parse ( Source => { String => $xml_text } );

       The following are all parsers that work with XML::Grove::Builder:

	 XML::Parser::PerlSAX (in libxml-perl, uses XML::Parser)
	 XML::ESISParser      (in libxml-perl, uses James Clark's `nsgmls')
	 XML::SAX2Perl	      (in libxml-perl, translates SAX 1.0 to PerlSAX)

       Most parsers supply more properties than the standard information set below and XML::Grove
       will make available all the properties given by the parser, refer to the parser documenta-
       tion to find out what additional properties it may provide.

       Although there are not any available yet (August 1999), PerlSAX filters can be used to
       process the output of a parser before it is passed to XML::Grove::Builder.
       XML::Grove::PerlSAX can be used to provide input to PerlSAX filters or other PerlSAX han-

       Using Groves

       The properties provided by parsers are available directly using Perl's normal syntax for
       accessing hashes and arrays.  For example, to get the name of an element:

	 $element_name = $element->{Name};

       By convention, all properties provided by parsers are in mixed case.  `"Parent"' proper-
       ties are available using the `"Data::Grove::Parent"' module.

       The following is the minimal set of objects and their properties that you are likely to
       get from all parsers:


       The Document object is parent of the root element of the parsed XML document.

       Contents    An array containing the root element.

       A document's `Contents' may also contain processing instructions, comments, and white-

       Some parsers provide information about the document type, the XML declaration, or nota-
       tions and entities.  Check the parser documentation for property names.


       The Element object represents elements from the XML source.

       Parent	   The parent object of this element.

       Name	   A string, the element type name of this element

       Attributes  A hash of strings or arrays

       Contents    An array of elements, characters, processing instructions, etc.

       In a purely minimal grove, the attributes of an element will be plain text (Perl scalars).
       Some parsers provide access to notations and entities in attributes, in which case the
       attribute may contain an array.


       The Characters object represents text from the XML source.

       Parent	   The parent object of this characters object

       Data	   A string, the characters


       The PI object represents processing instructions from the XML source.

       Parent	   The parent object of this PI object.

       Target	   A string, the processing instruction target.

       Data	   A string, the processing instruction data, or undef if none was supplied.

       In addition to the minimal set of objects above, XML::Grove knows about and parsers may
       provide the following objects.  Refer to the parser documentation for descriptions of the
       properties of these objects.

	 ::Entity::External  External entity reference
	 ::Entity::SubDoc    External SubDoc reference (SGML)
	 ::Entity::SGML      External SGML reference (SGML)
	 ::Entity	     Entity reference
	 ::Notation	     Notation declaration
	 ::Comment	     <!-- A Comment -->
	 ::SubDoc	     A parsed subdocument (SGML)
	 ::CData	     A CDATA marked section
	 ::ElementDecl	     An element declaration from the DTD
	 ::AttListDecl	     An element's attribute declaration, from the DTD

       XML::Grove by itself only provides one method, new(), for creating new XML::Grove objects.
       There are Data::Grove and XML::Grove extension modules that give additional methods for
       working with XML::Grove objects and new extensions can be created as needed.

       $obj = XML::Grove::OBJECT->new( [PROPERTIES] )
	   `"new"' creates a new XML::Grove object with the type OBJECT, and with the initial
	   PROPERTIES.	PROPERTIES may be given as either a list of key-value pairs, a hash, or
	   an XML::Grove object to copy.  OBJECT may be any of the objects listed above.

       This is a list of available extensions and the methods they provide (as of Feb 1999).
       Refer to their module documentation for more information on how to use them.

	   as_string	   return portions of groves as a string
	   attr_as_string  return an element's attribute as a string

	   as_canon_xml    return XML text in canonical XML format

	   parse	   emulate a PerlSAX parser using the grove objects

	   root 	   return the root element of a grove
	   rootpath	   return an array of all objects between the root
			   element and this object, inclusive

	   Data::Grove::Parent also adds `C<Parent>' and `C<Raw>' properties
	   to grove objects.

	   accept	   call back a subroutine using an object type name
	   accept_name	   call back using an element or tag name
	   children_accept for each child in Contents, call back a sub
	   children_accept_name  same, but using tag names
	   attr_accept	   call back for the objects in attributes

	   get_ids	   return a list of all ID attributes in grove

	   at_path	   $el->at_path('/html/body/ul/li[4]')

	   filter	   run a sub against all the objects in the grove

       The class `"XML::Grove"' is the superclass of all classes in the XML::Grove module.
       `"XML::Grove"' is a subclass of `"Data::Grove"'.

       If you create an extension and you want to add a method to all XML::Grove objects, then
       create that method in the XML::Grove package.  Many extensions only need to add methods to
       XML::Grove::Document and/or XML::Grove::Element.

       When you create an extension you should definitly provide a way to invoke your module
       using objects from your package too.  For example, XML::Grove::AsString's `"as_string()"'
       method can also be called using an XML::Grove::AsString object:

	 $writer= new XML::Grove::AsString;
	 $string = $writer->as_string ( $xml_object );

       Ken MacLeod, ken@bitsko.slc.ut.us

       perl(1), XML::Grove(3)

       Extensible Markup Language (XML) <http://www.w3c.org/XML>

perl v5.8.0				    1999-09-09				    XML::Grove(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 05:20 PM.