README
1$Id: README,v 1.10 2003/10/21 16:01:54 kmacleod Exp $
2
3
4 libxml-perl
5
6 Collection of Perl modules for working with XML.
7
8
9INTRODUCTION
10
11 libxml-perl is a collection of smaller Perl modules, scripts, and
12 documents for working with XML in Perl. libxml-perl software
13 works in combination with XML::Parser, PerlSAX, XML::DOM,
14 XML::Grove and others.
15
16 See the file Changes for user-visible changes and ChangeLog for
17 detailed changes. See the `examples' directory for examples. POD
18 style documentation is included in all non-alpha modules and
19 scripts. You should also be able to use the 'perldoc' utility to
20 extract documentation from the module files directly. HTML
21 formatted docs are available at the libxml-perl home page
22 <http://bitsko.slc.ut.us/libxml-perl/>.
23
24 Newer versions of this module can be found on CPAN at
25 <http://www.perl.com/CPAN/modules/by-module/XML/>. To join the
26 Perl-XML mailing list, send an email message to
27 ListManager@ActiveState.com with the following text in the body:
28 Subscribe Perl-XML
29
30 View the Perl XML FAQ at
31 <http://www.perlxml.com/faq/perl-xml-faq.html>.
32
33 Copyright (C) 1998 Ken MacLeod and others
34 This library is free software; you can redistribute it and/or
35 modify it under the same terms as Perl itself.
36
37
38MODULES
39
40 The following modules are marked with their release status:
41
42 STABLE -- has been in use for a while with few or no outstanding
43 bugs
44 BETA -- interfaces are stable but there may still be bugs
45 ALPHA -- interfaces are changing, there may be lots of bugs, and
46 there may not be docs available yet
47
48 XML::Parser::PerlSAX STABLE
49 XML::Parser::PerlSAX is a PerlSAX parser using XML::Parser
50 (which uses James Clark's Expat XML Parser).
51
52 XML::Handler::Sample STABLE
53 XML::Handler::Sample is a PerlSAX handler that simply prints
54 out the event names as they are parsed by a PerlSAX parser.
55 It can be used for debugging or as a template for building new
56 handlers. XML::Handler::Sample contains handlers for all
57 known parser events.
58
59 XML::ESISParser STABLE
60 XML::ESISParser is a validating PerlSAX parser using James
61 Clark's `nsgmls' SGML/XML Parser. ESISParser supports both
62 XML and SGML document instances. Unless you need validation,
63 you should probably be using XML::Parser::PerlSAX or
64 XML::Parser.
65
66 XML::ESISParser with XML::Grove obsolete the
67 SGML::SPGroveBuilder and SGML::Grove modules.
68
69 XML::Handler::XMLWriter STABLE
70 A PerlSAX handler for writing readable XML (in contrast to
71 Canonical XML, for example). XMLWriter is also subclassable
72 and supports calling start and end methods by element-names
73 (subclassed from XML::Handler::Subs). XMLWriter is similar to
74 XML::Parser's Stream style.
75
76 XML::Handler::Subs STABLE
77 A PerlSAX handler base class that calls start and end methods
78 by element-names. Subs is similar to XML::Parser's Subs
79 style.
80
81 XML::Handler::CanonXMLWriter STABLE
82 A PerlSAX handler that outputs in Canonical XML
83 <http://www.jclark.com/xml/canonxml.html>. This module is
84 generally only used for debugging.
85
86 Data::Grove STABLE
87 Data::Grove::Parent STABLE
88 Data::Grove::Visitor STABLE
89 Data::Grove and it's helpers provide a base class for deeply
90 nested or directed graph structures. Used by XML::Grove (and
91 others soon).
92
93 XML::SAX2Perl ALPHA
94 XML::Perl2SAX ALPHA
95 SAX2Perl and Perl2SAX are SAX Parser<->DocumentHandler
96 filters. These modules translate parse events between the
97 Java/CORBA style SAX methods and PerlSAX style methods.
98
99 XML::PatAct::MatchName ALPHA
100 MatchName is a pattern matching module that can be used with
101 PatAct action modules. MatchName uses simple element names or
102 element name lists to match names to actions.
103
104 XML::PatAct::ToObjects ALPHA
105 ToObjects is a PatAct action module. ToObjects can be used to
106 create application-ready Perl objects from XML instances.
107
108 XML::PatAct::Amsterdam ALPHA
109 Amsterdam is a PatAct action module. Amsterdam can be used to
110 apply a very simple form of style-sheet to an XML instance by
111 using ``before'' and ``after'' strings that are output before
112 and after the contents of elements.
113
114 XML::PatAct::PatternTempl BETA
115 XML::PatAct::ActionTempl BETA
116 PatternTempl and ActionTempl are template files that
117 pattern/action module writers can copy to create new modules.
118 See Creating PatAct Modules for more information.
119
120DOCUMENTS
121
122 sax-2.0.html, sax-2.0-adv.html
123 PerlSAX 2.0 bindings. Maintained by Robin Berjon and the
124 XML-Perl mailing list.
125
126 PerlSAX
127 This document defines a Perl binding to SAX 1.0. PerlSAX-
128 based parser modules implement and possibly extend the
129 interface described in PerlSAX.
130
131 UsingPerlSAX
132 A brief introduction to PerlSAX using the XML::Parser::PerlSAX
133 module.
134
135 UsingPatActModules
136 Describes how to use pattern/action modules to transform XML
137 instances.
138
139 CreatingPatActModules
140 A document for module writers who are writing new pattern/
141 action modules.
142
143 modules.xml
144 modules.xml contains a listing of all Perl XML packages and
145 their public modules categorized by several topics.
146
147
148INSTALLATION
149
150 In order to use this package you will need Perl version 5.005 or
151 better. Several other modules may also be required to use some
152 modules in libxml-perl, including XML::Parser, XML::DOM, and
153 XML::Grove. These are all available in the XML module directory
154 on CPAN.
155
156<http://www.perl.com/CPAN/modules/by-module/XML/>
157
158 You install libxml-perl, as you would install any perl module
159 library, by running these commands:
160
161 perl Makefile.PL
162 make
163 make test
164 make install
165
166 If you want to install a private copy of libxml-perl in your home
167 directory, then you should try to produce the initial Makefile
168 with something like this command:
169
170 perl Makefile.PL PREFIX=~/perl
171
172