Debian Codegraph @

README

raw
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