.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "XML::SAX::EventMethodMaker 3pm"
.TH XML::SAX::EventMethodMaker 3pm "2022-06-28" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::SAX::EventMethodMaker \- SAX event names, creation of methods from templates
.SH "VERSION"
.IX Header "VERSION"
version 0.46
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use XML::SAX::EventMethodMaker qw(
\&        sax_event_names missing_methods compile_methods
\&    );
\&
\&  ## Getting event names by handler type and SAX version
\&    my @events          = sax_event_names;
\&    my @dtd_events      = sax_event_names "DTDHandler";
\&    my @sax1_events     = sax_event_names 1;
\&    my @sax1_dtd_events = sax_event_names 1, "DTDHandler";
\&
\&  ## Figuring out what events a class or object does not provide
\&    my @missing = missing_methods $class, @events ;
\&
\&  ## Creating all SAX event methods
\&    compile_methods $class, <<\*(AqTEMPLATE_END\*(Aq, sax_event_names;
\&    sub <EVENT> {
\&        my $self = shift;
\&        ... do something ...
\&
\&        ## Pass the event up to the base class
\&        $self\->SUPER::<EVENT>( @_ );
\&    }
\&    TEMPLATE_END
\&
\&  ## Creating some methods
\&    compile_methods $class, <<\*(AqTEMPLATE_END\*(Aq, @method_names;
\&    ...
\&    TEMPLATE_END
\&
\&  ## Creating only missing event handlers
\&    compile_missing_methods $class, <<\*(AqTEMPLATE_END\*(Aq;
\&    ...
\&    TEMPLATE_END
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In building \s-1SAX\s0 machines, it is often handle to build a set of event
handlers from a common template.  This helper library (or class)
provides the database of handler names, queryable by type, and
.SH "NAME"
XML::SAX::EventMethodMaker \- SAX event names, creation of methods from templates
.SH "Functions"
.IX Header "Functions"
.IP "sax_event_names" 4
.IX Item "sax_event_names"
.Vb 1
\&    my @names = sax_event_names @query_terms;
.Ve
.Sp
Takes a list of query terms and returns all matching events.
.Sp
Query terms may be:
    \- a \s-1SAX\s0 version number: 1 or 2 (no floating point or ranges)
    \- Handler
    \- DTDHandler
    \- ContentHandler
    \- DocumentHandler
    \- DeclHandler
    \- ErrorHandler
    \- EntityResolver
    \- LexicalHandler
.Sp
In addition to normal \s-1SAX\s0 events, there are also \*(L"parse\*(R" events:
    \- ParseMethods
.Sp
Unrecognized query terms cause exceptions.
.Sp
If no query terms are provided, then all event names from all versions
are returned except for parse methods (parse, parse_uri, ...).
.Sp
If any version numbers are supplied, then only events from those version
numbers are returned.  No support for noninteger version numbers is
provided, nor for ranges.  So far, only two \s-1SAX\s0 versions exist in Perl, 1 and
2.
.Sp
If any handler types are provided, then only events of those types are
returned.  Handler types are case insensitive.
.Sp
In other words, all returned events must match both a version number and
a handler type.
.Sp
No support for boolean logic is provided.
.IP "missing_methods" 4
.IX Item "missing_methods"
.Vb 2
\&    my @missing = missing_methods _\|_PACKAGE_\|_, @event_names;
\&    my @missing = missing_methods $object, @event_names;
.Ve
.Sp
This subroutine looks to see if the object or class has declared
event handler methods for the named events.  Any events that haven't
been declared are returned.
.Sp
It is sufficient to use subroutine prototypes to prevent shimming AUTOLOADed
(or otherwise lazily compiled) methods:
.Sp
.Vb 1
\&    sub start_document ;
.Ve
.IP "compile_methods" 4
.IX Item "compile_methods"
.Vb 2
\&    compile_methods _\|_PACKAGE_\|_, $template, @method_names;
\&    compile_methods $object,     $template, @method_names;
.Ve
.Sp
Compiles the given template for each given event name, substituting
the event name for the string <\s-1EVENT\s0> or <\s-1METHOD\s0> in the template.
There is no difference between these two tags, they are provided to
only to let you make your templates more readable to you.
.IP "compile_missing_methods" 4
.IX Item "compile_missing_methods"
.Vb 2
\&    compile_missing_methods _\|_PACKAGE_\|_, $template, @method_names;
\&    compile_missing_methods $objects,    $template, @method_names;
.Ve
.Sp
Shorthand for calls like
.Sp
.Vb 2
\&    compile_methods _\|_PACKAGE_\|_, $template,
\&        missing_methods _\|_PACKAGE_\|_, @method_names;
.Ve
.SH "Due Credit"
.IX Header "Due Credit"
The database of handlers by type was developed by Kip Hampton,
modified by Robin Berjon, and pilfered and corrupted by me.
.SH "LICENSE"
.IX Header "LICENSE"
.Vb 2
\&    Database Copyright 2002, Barrie Slaymaker, Kip Hampton, Robin Berjon
\&    Code Copyright 2002, Barrie Slaymaker <barries@slaysys.com>
.Ve
.PP
You may use this under the terms of the Artistic, \s-1GNU\s0 Public, or \s-1BSD\s0
licences, as you see fit.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Barry Slaymaker
.IP "\(bu" 4
Chris Prather <chris@prather.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2013 by Barry Slaymaker.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.