1=head1 Using PerlSAX
2
3Working with PerlSAX involves using two classes (packages), a PerlSAX
4parser that generates parsing events and a class that you write that
5will receive those parsing events, the ``handler''.  This guide will
6use the XML::Parser::PerlSAX parser that uses Clark Cooper's
7XML::Parser module.
8
9The handler class implements the PerlSAX handler methods that you are
10interested in.  The following example, MyHandler.pm, prints a message
11every time an element starts or ends:
12
13    package MyHandler;
14
15    sub new {
16        my ($type) = @_;
17        return bless {}, $type;
18    }
19
20    sub start_element {
21        my ($self, $element) = @_;
22
23        print "Start element: $element->{Name}\n";
24    }
25
26    sub end_element {
27        my ($self, $element) = @_;
28
29        print "End element: $element->{Name}\n";
30    }
31
32    1;
33
34To use your handler you will need to have a script, myhandler.pl, that
35loads and creates your handler and the parser, and then calls the
36parser to parse the XML instance and send events to your handler:
37
38    use XML::Parser::PerlSAX;
39    use MyHandler;
40
41    my $my_handler = MyHandler->new;
42    my $parser = XML::Parser::PerlSAX->new( Handler => $my_handler );
43
44    foreach my $instance (@ARGV) {
45        $parser->parse(Source => { SystemId => $instance });
46    }
47
48Given this XML instance, myhandler.xml:
49
50    <?xml version="1.0"?>
51
52    <article>
53    <title>Using PerlSAX</title>
54    <paragraph>Working with PerlSAX ...</paragraph>
55    </article>
56
57Running myhandler.pl like this:
58
59    perl myhandler.pl myhandler.xml
60
61will produce this output:
62
63    Start element: article
64    Start element: title
65    End element: title
66    Start element: paragraph
67    End element: paragraph
68    End element: article
69
70=head2 For More Information
71
72PerlSAX.pod describes the PerlSAX interface.  Each parser module
73describes it's individual capabilities.  XML::Parser::PerlSAX is the
74most commonly used PerlSAX implementation.
75
76The files described in this doc are in the `examples' directory.  A
77more complete implementation of the very simple handler above is in
78the module XML::Handler::Sample.  Other, more complex handlers are in
79the XML::Handler directory as well.
80
81Another hands-on doc for PerlSAX is the XML-Parser-and-PerlSAX.pod.
82This doc describes the difference between and the purpose of PerlSAX
83with respect to XML::Parser.
84
85This document was inspired by and uses the code examples from David
86Megginson's ``Quick Start for SAX Application Writers.''
87<http://www.megginson.com/SAX/quickstart.html>
88