$Id: README,v 1.5 1998/09/20 18:48:00 kmacleod Exp $ XML::Grove A Perl 5 module providing simple objects for parsed XML documents. Ken MacLeod ken@bitsko.slc.ut.us INTRODUCTION XML::Grove provides simple objects for parsed XML documents. The objects may be modified but no checking is performed by XML::Grove. XML::Grove objects do not include parsing information such as character positions or type of tags used. This package also includes several extensions to XML::Grove, including `as_string' methods, iterators, and visitor methods (callbacks). See the file Changes for user-visible changes. See the `examples' directory for an example of using XML::Grove. Newer versions of this module can be found on CPAN or at . To join the Perl-XML mailing list, send an email message to ListManager@ActiveState.com with the following text in the body: Subscribe Perl-XML Copyright (C) 1998 Ken MacLeod XML::Grove is distributed under the same terms as Perl. See the file COPYING for distribution terms. OVERVIEW Groves are generally created by calling a parser or grove building module that returns an XML::Grove object. The XML::Grove object then contains the root element of the document and may contain errors generated during the parsing or building, entities and notations used within the document, or other parser or grove builder specific information. Grove building modules include [for now, just] XML::Parser::Grove. Elements of the document are XML::Grove::Element objects. Elements have a name, attributes, and the contents of the element. Attributes are stored as a Perl hash, with the values as an array of scalars and XML::Grove::Entity objects. The contents of an element may be more Elements, scalars, entity reference objects, processing instruction (PI) objects, or comment objects. XML::Grove::AsString adds `as_string' methods to XML::Grove objects to return the character data of the object and any elements contained in the object. The string may optionally be filtered, have entity references mapped to different replacement text, or written to a file. XML::Grove::AsCanonXML adds `as_canon_xml' methods to XML::Grove objects to return a string or write objects to a file in ``Canonical XML'' format. XML::Grove::Iter is a proxy-based tree iterator that supports moving around the objects in the XML document. XML::Grove::Visitor adds callback methods to XML objects to give a subroutine interface for your packages. INSTALLATION XML::Grove requires Perl 5. Most likely you will also want to get XML::Parser for reading XML documents. XML::Grove installs as a standard Perl module perl Makefile.PL make make test make install