| 1 |
XML::SAX::Base is intended for use as a base class for SAX filter modules |
| 2 |
and XML parsers generating SAX events. |
| 3 |
|
| 4 |
If you simply wish to build a SAX handler class to 'consume' SAX events you |
| 5 |
do not need to use XML::SAX::Base directly although you will need to install |
| 6 |
XML::SAX. |
| 7 |
|
| 8 |
This module used to be distributed as part of the XML:SAX distribution but |
| 9 |
is now distributed separately and referenced as a dependency by XML::SAX. |
| 10 |
|
| 11 |
INSTALLATION: |
| 12 |
|
| 13 |
via tarball: |
| 14 |
|
| 15 |
% tar -zxvf XML-SAX-Base-xxx.tar.gz |
| 16 |
% perl Makefile.PL |
| 17 |
% make && make test |
| 18 |
% make install |
| 19 |
|
| 20 |
via CPAN shell: |
| 21 |
|
| 22 |
% perl -MCPAN -e shell |
| 23 |
% install XML::SAX::Base |
| 24 |
|
| 25 |
The rest of this file consists of the fine XML::SAX::Base documentation |
| 26 |
contributed by Robin Berjon. |
| 27 |
|
| 28 |
Enjoy! |
| 29 |
|
| 30 |
=head1 NAME |
| 31 |
|
| 32 |
XML::SAX::Base - Base class SAX Drivers and Filters |
| 33 |
|
| 34 |
=head1 SYNOPSIS |
| 35 |
|
| 36 |
package MyFilter; |
| 37 |
use XML::SAX::Base; |
| 38 |
@ISA = ('XML::SAX::Base'); |
| 39 |
|
| 40 |
=head1 DESCRIPTION |
| 41 |
|
| 42 |
This module has a very simple task - to be a base class for PerlSAX |
| 43 |
drivers and filters. It's default behaviour is to pass the input directly |
| 44 |
to the output unchanged. It can be useful to use this module as a base class |
| 45 |
so you don't have to, for example, implement the characters() callback. |
| 46 |
|
| 47 |
The main advantages that it provides are easy dispatching of events the right |
| 48 |
way (ie it takes care for you of checking that the handler has implemented |
| 49 |
that method, or has defined an AUTOLOAD), and the guarantee that filters |
| 50 |
will pass along events that they aren't implementing to handlers downstream |
| 51 |
that might nevertheless be interested in them. |
| 52 |
|
| 53 |
=head1 WRITING SAX DRIVERS AND FILTERS |
| 54 |
|
| 55 |
The Perl Sax API Reference is at L<http://perl-xml.sourceforge.net/perl-sax/>. |
| 56 |
|
| 57 |
Writing SAX Filters is tremendously easy: all you need to do is |
| 58 |
inherit from this module, and define the events you want to handle. A |
| 59 |
more detailed explanation can be found at |
| 60 |
http://www.xml.com/pub/a/2001/10/10/sax-filters.html. |
| 61 |
|
| 62 |
Writing Drivers is equally simple. The one thing you need to pay |
| 63 |
attention to is B<NOT> to call events yourself (this applies to Filters |
| 64 |
as well). For instance: |
| 65 |
|
| 66 |
package MyFilter; |
| 67 |
use base qw(XML::SAX::Base); |
| 68 |
|
| 69 |
sub start_element { |
| 70 |
my $self = shift; |
| 71 |
my $data = shift; |
| 72 |
# do something |
| 73 |
$self->{Handler}->start_element($data); # BAD |
| 74 |
} |
| 75 |
|
| 76 |
The above example works well as precisely that: an example. But it has |
| 77 |
several faults: 1) it doesn't test to see whether the handler defines |
| 78 |
start_element. Perhaps it doesn't want to see that event, in which |
| 79 |
case you shouldn't throw it (otherwise it'll die). 2) it doesn't check |
| 80 |
ContentHandler and then Handler (ie it doesn't look to see that the |
| 81 |
user hasn't requested events on a specific handler, and if not on the |
| 82 |
default one), 3) if it did check all that, not only would the code be |
| 83 |
cumbersome (see this module's source to get an idea) but it would also |
| 84 |
probably have to check for a DocumentHandler (in case this were SAX1) |
| 85 |
and for AUTOLOADs potentially defined in all these packages. As you can |
| 86 |
tell, that would be fairly painful. Instead of going through that, |
| 87 |
simply remember to use code similar to the following instead: |
| 88 |
|
| 89 |
package MyFilter; |
| 90 |
use base qw(XML::SAX::Base); |
| 91 |
|
| 92 |
sub start_element { |
| 93 |
my $self = shift; |
| 94 |
my $data = shift; |
| 95 |
# do something to filter |
| 96 |
$self->SUPER::start_element($data); # GOOD (and easy) ! |
| 97 |
} |
| 98 |
|
| 99 |
This way, once you've done your job you hand the ball back to |
| 100 |
XML::SAX::Base and it takes care of all those problems for you! |
| 101 |
|
| 102 |
Note that the above example doesn't apply to filters only, drivers |
| 103 |
will benefit from the exact same feature. |
| 104 |
|
| 105 |
=head1 METHODS |
| 106 |
|
| 107 |
A number of methods are defined within this class for the purpose of |
| 108 |
inheritance. Some probably don't need to be overridden (eg parse_file) |
| 109 |
but some clearly should be (eg parse). Options for these methods are |
| 110 |
described in the PerlSAX2 specification available from |
| 111 |
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/~checkout~/perl-xml/libxml-perl/doc/sax-2.0.html?rev=HEAD&content-type=text/html. |
| 112 |
|
| 113 |
=over 4 |
| 114 |
|
| 115 |
=item * parse |
| 116 |
|
| 117 |
The parse method is the main entry point to parsing documents. Internally |
| 118 |
the parse method will detect what type of "thing" you are parsing, and |
| 119 |
call the appropriate method in your implementation class. Here is the |
| 120 |
mapping table of what is in the Source options (see the Perl SAX 2.0 |
| 121 |
specification for the meaning of these values): |
| 122 |
|
| 123 |
Source Contains parse() calls |
| 124 |
=============== ============= |
| 125 |
CharacterStream (*) _parse_characterstream($stream, $options) |
| 126 |
ByteStream _parse_bytestream($stream, $options) |
| 127 |
String _parse_string($string, $options) |
| 128 |
SystemId _parse_systemid($string, $options) |
| 129 |
|
| 130 |
However note that these methods may not be sensible if your driver class |
| 131 |
is not for parsing XML. An example might be a DBI driver that generates |
| 132 |
XML/SAX from a database table. If that is the case, you likely want to |
| 133 |
write your own parse() method. |
| 134 |
|
| 135 |
Also note that the Source may contain both a PublicId entry, and an |
| 136 |
Encoding entry. To get at these, examine $options->{Source} as passed |
| 137 |
to your method. |
| 138 |
|
| 139 |
(*) A CharacterStream is a filehandle that does not need any encoding |
| 140 |
translation done on it. This is implemented as a regular filehandle |
| 141 |
and only works under Perl 5.7.2 or higher using PerlIO. To get a single |
| 142 |
character, or number of characters from it, use the perl core read() |
| 143 |
function. To get a single byte from it (or number of bytes), you can |
| 144 |
use sysread(). The encoding of the stream should be in the Encoding |
| 145 |
entry for the Source. |
| 146 |
|
| 147 |
=item * parse_file, parse_uri, parse_string |
| 148 |
|
| 149 |
These are all convenience variations on parse(), and in fact simply |
| 150 |
set up the options before calling it. You probably don't need to |
| 151 |
override these. |
| 152 |
|
| 153 |
=item * get_options |
| 154 |
|
| 155 |
This is a convenience method to get options in SAX2 style, or more |
| 156 |
generically either as hashes or as hashrefs (it returns a hashref). |
| 157 |
You will probably want to use this method in your own implementations |
| 158 |
of parse() and of new(). |
| 159 |
|
| 160 |
=item * get_feature, set_feature |
| 161 |
|
| 162 |
These simply get and set features, and throw the |
| 163 |
appropriate exceptions defined in the specification if need be. |
| 164 |
|
| 165 |
If your subclass defines features not defined in this one, |
| 166 |
then you should override these methods in such a way that they check for |
| 167 |
your features first, and then call the base class's methods |
| 168 |
for features not defined by your class. An example would be: |
| 169 |
|
| 170 |
sub get_feature { |
| 171 |
my $self = shift; |
| 172 |
my $feat = shift; |
| 173 |
if (exists $MY_FEATURES{$feat}) { |
| 174 |
# handle the feature in various ways |
| 175 |
} |
| 176 |
else { |
| 177 |
return $self->SUPER::get_feature($feat); |
| 178 |
} |
| 179 |
} |
| 180 |
|
| 181 |
Currently this part is unimplemented. |
| 182 |
|
| 183 |
=back |
| 184 |
|
| 185 |
It would be rather useless to describe all the methods that this |
| 186 |
module implements here. They are all the methods supported in SAX1 and |
| 187 |
SAX2. In case your memory is a little short, here is a list. The |
| 188 |
apparent duplicates are there so that both versions of SAX can be |
| 189 |
supported. |
| 190 |
|
| 191 |
=over 4 |
| 192 |
|
| 193 |
=item * start_document |
| 194 |
|
| 195 |
=item * end_document |
| 196 |
|
| 197 |
=item * start_element |
| 198 |
|
| 199 |
=item * start_document |
| 200 |
|
| 201 |
=item * end_document |
| 202 |
|
| 203 |
=item * start_element |
| 204 |
|
| 205 |
=item * end_element |
| 206 |
|
| 207 |
=item * characters |
| 208 |
|
| 209 |
=item * processing_instruction |
| 210 |
|
| 211 |
=item * ignorable_whitespace |
| 212 |
|
| 213 |
=item * set_document_locator |
| 214 |
|
| 215 |
=item * start_prefix_mapping |
| 216 |
|
| 217 |
=item * end_prefix_mapping |
| 218 |
|
| 219 |
=item * skipped_entity |
| 220 |
|
| 221 |
=item * start_cdata |
| 222 |
|
| 223 |
=item * end_cdata |
| 224 |
|
| 225 |
=item * comment |
| 226 |
|
| 227 |
=item * entity_reference |
| 228 |
|
| 229 |
=item * notation_decl |
| 230 |
|
| 231 |
=item * unparsed_entity_decl |
| 232 |
|
| 233 |
=item * element_decl |
| 234 |
|
| 235 |
=item * attlist_decl |
| 236 |
|
| 237 |
=item * doctype_decl |
| 238 |
|
| 239 |
=item * xml_decl |
| 240 |
|
| 241 |
=item * entity_decl |
| 242 |
|
| 243 |
=item * attribute_decl |
| 244 |
|
| 245 |
=item * internal_entity_decl |
| 246 |
|
| 247 |
=item * external_entity_decl |
| 248 |
|
| 249 |
=item * resolve_entity |
| 250 |
|
| 251 |
=item * start_dtd |
| 252 |
|
| 253 |
=item * end_dtd |
| 254 |
|
| 255 |
=item * start_entity |
| 256 |
|
| 257 |
=item * end_entity |
| 258 |
|
| 259 |
=item * warning |
| 260 |
|
| 261 |
=item * error |
| 262 |
|
| 263 |
=item * fatal_error |
| 264 |
|
| 265 |
=back |
| 266 |
|
| 267 |
=head1 TODO |
| 268 |
|
| 269 |
- more tests |
| 270 |
- conform to the "SAX Filters" and "Java and DOM compatibility" |
| 271 |
sections of the SAX2 document. |
| 272 |
|
| 273 |
=head1 AUTHOR |
| 274 |
|
| 275 |
Kip Hampton ([email protected]) did most of the work, after porting |
| 276 |
it from XML::Filter::Base. |
| 277 |
|
| 278 |
Robin Berjon ([email protected]) pitched in with patches to make it |
| 279 |
usable as a base for drivers as well as filters, along with other patches. |
| 280 |
|
| 281 |
Matt Sergeant ([email protected]) wrote the original XML::Filter::Base, |
| 282 |
and patched a few things here and there, and imported it into |
| 283 |
the XML::SAX distribution. |
| 284 |
|
| 285 |
=head1 SEE ALSO |
| 286 |
|
| 287 |
L<XML::SAX> |
| 288 |
|
| 289 |
=cut |