| 1 |
$Id: README,v 1.12 1999/09/03 21:41:00 kmacleod Exp $ |
| 2 |
|
| 3 |
|
| 4 |
XML::Grove |
| 5 |
|
| 6 |
A Perl 5 module providing simple access to the |
| 7 |
information set of parsed XML, HTML, or SGML instances. |
| 8 |
|
| 9 |
|
| 10 |
Ken MacLeod |
| 11 |
[email protected] |
| 12 |
|
| 13 |
INTRODUCTION |
| 14 |
|
| 15 |
XML::Grove provides simple access to the information set of parsed |
| 16 |
XML, HTML, or SGML instances using a tree of Perl hashes. This |
| 17 |
package also includes several extensions to XML::Grove that |
| 18 |
provide the following: |
| 19 |
|
| 20 |
* returning element contents as a string |
| 21 |
* returning element contents as XML, HTML, or Canonical XML |
| 22 |
* processing entire groves using the visitor pattern |
| 23 |
* processing entire groves using PerlSAX |
| 24 |
* running a filter over all nodes in the grove |
| 25 |
* substituting values into an XML template grove |
| 26 |
* indexing a grove by ID or other attributes |
| 27 |
* accessing elements and objects via URL-like paths |
| 28 |
* create grove objects using an easy shorthand |
| 29 |
|
| 30 |
See ``Using XML::Grove'' for an introduction to using XML::Grove. |
| 31 |
|
| 32 |
See the file Changes for user-visible changes. See the `examples' |
| 33 |
directory for examples of using XML::Grove. POD documentation is |
| 34 |
included in all non-alpha modules and scripts. You should also be |
| 35 |
able to use the 'perldoc' utility to extract documentation from |
| 36 |
the module files directly. HTML formatted docs are available at |
| 37 |
the XML::Grove home page <http://bitsko.slc.ut.us/XML-Grove/>. |
| 38 |
|
| 39 |
Newer versions of this module can be found on CPAN at |
| 40 |
<http://www.perl.com/CPAN/modules/by-module/XML/>. To join the |
| 41 |
Perl-XML mailing list, send an email message to |
| 42 |
[email protected] with the following text in the body: |
| 43 |
Subscribe Perl-XML |
| 44 |
|
| 45 |
Copyright (C) 1998, 1999 Ken MacLeod |
| 46 |
XML::Grove is distributed under the same terms as Perl. |
| 47 |
See the file COPYING for distribution terms. |
| 48 |
|
| 49 |
MODULES |
| 50 |
|
| 51 |
The following modules are marked with their release status: |
| 52 |
|
| 53 |
STABLE -- has been in use for a while with few or no outstanding |
| 54 |
bugs |
| 55 |
BETA -- interfaces are stable but there may still be bugs |
| 56 |
ALPHA -- interfaces are changing, there may be lots of bugs, and |
| 57 |
there may not be docs available yet |
| 58 |
|
| 59 |
XML::Grove STABLE |
| 60 |
Declares all the XML::Grove object classes and provides a |
| 61 |
`new()' method for basic object creation. |
| 62 |
|
| 63 |
XML::Grove::Builder STABLE |
| 64 |
Builds entires groves from *ML instances using PerlSAX parsers. |
| 65 |
|
| 66 |
XML::Grove::AsString STABLE |
| 67 |
Adds `as_string()' methods to XML::Grove objects to return the |
| 68 |
character data of the object and any elements contained in the |
| 69 |
object. The string may optionally be filtered, have entity |
| 70 |
references mapped to different replacement text, or written to |
| 71 |
a file. |
| 72 |
|
| 73 |
XML::Grove::AsCanonXML STABLE |
| 74 |
Adds `as_canon_xml()' methods to XML::Grove objects to return |
| 75 |
a string or write objects to a file in ``Canonical XML'' |
| 76 |
format. |
| 77 |
|
| 78 |
Data::Grove::Visitor STABLE (in libxml-perl) |
| 79 |
Processes or ``walks' an entire grove by making callbacks to a |
| 80 |
class you define. Visitor calls your class once for every |
| 81 |
grove object (no start/end calls), allows arguments to be |
| 82 |
passed down during the walk, and you can stop any further |
| 83 |
processing below an element or other container. |
| 84 |
|
| 85 |
XML::Grove::PerlSAX STABLE |
| 86 |
Processes an entire grove by making callbacks to a class you |
| 87 |
define using the PerlSAX API. Calls start/end methods for |
| 88 |
container objects. PerlSAX can be used to provide input to |
| 89 |
SAX filters. |
| 90 |
|
| 91 |
Data::Grove::Parent STABLE (in libxml-perl) |
| 92 |
Adds a Parent property and `root()' and `rootpath()' methods |
| 93 |
to grove objects. |
| 94 |
|
| 95 |
XML::Grove::Factory BETA |
| 96 |
Provides objects and functions to easily create groves |
| 97 |
directly from Perl. |
| 98 |
|
| 99 |
XML::Grove::IDs BETA |
| 100 |
Return a hash mapping ID or other attributes to the elements |
| 101 |
where they are defined. |
| 102 |
|
| 103 |
XML::Grove::Path BETA |
| 104 |
Return an object in the grove using URL-like paths, e.g. |
| 105 |
`/html/head/title'. |
| 106 |
|
| 107 |
XML::Grove::Sub BETA |
| 108 |
Run a sub or filter across all objects in the grove. |
| 109 |
|
| 110 |
XML::Grove::XPointer DEPRECATED |
| 111 |
Implements a `xp_child()' method used by XML::Grove::Path. |
| 112 |
Does _not_ implement any current XPointer features. |
| 113 |
|
| 114 |
XML::Grove::ToObjects OBSOLETE |
| 115 |
Convert XML to Perl objects via a mapping table. Replaced by |
| 116 |
XML::PatAct::ToObjects in libxml-perl. |
| 117 |
|
| 118 |
|
| 119 |
INSTALLATION |
| 120 |
|
| 121 |
XML::Grove requires Perl 5.005 and libxml-perl. Most likely you |
| 122 |
will also want to get XML::Parser for reading XML documents. |
| 123 |
XML::Parser is available from CPAN: |
| 124 |
|
| 125 |
<http://www.perl.com/CPAN/modules/by-module/XML/> |
| 126 |
|
| 127 |
XML::Grove installs as a standard Perl module |
| 128 |
|
| 129 |
perl Makefile.PL |
| 130 |
make |
| 131 |
make test |
| 132 |
make install |