.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XMLParser 3pm"
.TH XMLParser 3pm "2006-07-23" "Lire 2.1.1" "LogReport's Lire 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"
Lire::XMLParser \- Base object\-oriented XML parser.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    package MyParser;
\&
\&    use base qw/ Lire::XMLParser /;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module makes it possible to write object-oriented parser using
the non-oo XML::Parser module.
.SH "CLIENT METHODS"
.IX Header "CLIENT METHODS"
.ie n .SS "parse( $xml )"
.el .SS "parse( \f(CW$xml\fP )"
.IX Subsection "parse( $xml )"
Parse the \s-1XML\s0 and returns the result. \f(CW$xml\fR can either be a string or a
reference to an open filehandle or IO::Handle object.
.ie n .SS "parsefile( $file )"
.el .SS "parsefile( \f(CW$file\fP )"
.IX Subsection "parsefile( $file )"
Parses the \s-1XML\s0 contained in \f(CW$file\fR and returns the result.
.SH "META-INFORMATION TEMPLATE METHODS"
.IX Header "META-INFORMATION TEMPLATE METHODS"
Two template methods must be implemented by subclasses. These methods
gives information on the content model of the \s-1XML\s0 expected by the
parser.
.SS "\fInamespaces()\fP"
.IX Subsection "namespaces()"
This method should return an hash reference. The keys are \s-1XML\s0
namespaces understood by the parser. The value is the prefix which is
used for that namespace in the \fIelements_spec()\fR method.
.SS "\fIelements_spec()\fP"
.IX Subsection "elements_spec()"
This method should return an hash reference. The key are the known \s-1XML\s0
elements. An error will be thrown by the parser when an element not
defined in this hash is encountered.
.PP
The key should be of the form [ \fIprefix\fR : ] \fIelement_name\fR. If
prefix is used it should be defined in the \fInamespaces()\fR method.
.PP
The value of the hash are element specification. This specification
can be used to configure the event handlers that will be called as
well as specifying the content model of the elements. This
specification is an hash reference with the following keys:
.IP "content" 4
.IX Item "content"
This is an array reference that should contains the name of the
elements allowed to appear in that element. These names are in the
same format than for the \fIelements_spec()\fR keys. If that element is
omitted, the element is considered to be empty and thus cannot
contains any other element. If the element can contain \s-1PCDATA\s0, the
string '\s-1PCDATA\s0' should be listed in the array.
.IP "start" 4
.IX Item "start"
This specify the handler called when the opening tag for this element
is encountered. This can be either a function reference or a method
name. If this element is omitted, the handler will be the method named
\&\fIelement\fR_end if it exists, or no handler otherwise. '_' is
substituted for invalid method name characters, i.e. report-spec
becomes report_spec_start.
.IP "end" 4
.IX Item "end"
This specify the handler called when the closing tag for this element
is encountered. This can be either a function reference or a method
name. If this element is omitted, the handler will be the method named
\&\fIelement\fR_end if it exists, or no handler otherwise. '_' is
substituted for invalid method name characters, i.e. report-spec
becomes report_spec_end.
.IP "char" 4
.IX Item "char"
This specify the handler called when \s-1PCDATA\s0 is encountered within the
element. This can only happen if '\s-1PCDATA\s0' appeared in the 'content'
attribute. This can be either a function reference or a method name.
If this element is omitted, the handler will be the method named
\&\fIelement\fR_char if it exists, or no handler otherwise. '_' is
substituted for invalid method name characters, i.e. list-item becomes
list_item_char.
.PP
The specification can also be an array reference, in that case it will
be interpreted as the content of the 'content' hash attribute.
.PP
Errors will be reported for invalid specification.
.SH "UTILITY METHODS"
.IX Header "UTILITY METHODS"
.SS "\fIexpat()\fP"
.IX Subsection "expat()"
During the parse, this returns the underlying Lire::XMLParser::Expat
parser object.
.ie n .SS "error( $msg )"
.el .SS "error( \f(CW$msg\fP )"
.IX Subsection "error( $msg )"
Will terminate parsing with error message \f(CW$msg\fR. The current parsing
context will be appended to the message.
.ie n .SS "warning( $msg )"
.el .SS "warning( \f(CW$msg\fP )"
.IX Subsection "warning( $msg )"
Will print a warning message \f(CW$msg\fR. The current parsing
context will be appended to the message.
.SS "\fIcontext()\fP"
.IX Subsection "context()"
Returns as an array reference the names of the currently opened
elements. In start and end tag, the last element will be the tag of
the parent element. The name of the elements will be in the same
format than the one used by \fIelements_spec()\fR.
.SS "\fIcurrent_element()\fP"
.IX Subsection "current_element()"
Returns the name of the innermost currently opened element. In start
and end tag, the last element will be the tag of the parent element.
The name of the elements will be in the same format than the one used
by \fIelements_spec()\fR.
.ie n .SS "in_element( $element_name )"
.el .SS "in_element( \f(CW$element_name\fP )"
.IX Subsection "in_element( $element_name )"
This returns true if the innermost currently opened element has the
same name as \f(CW$element_name\fR. \f(CW$element_name\fR should be one of the
elements defined by \fIelements_spec()\fR, otherwise the method will croak.
.PP
Example:
.PP
.Vb 5
\&    if ( $self\->in_element( "lire:report") ) {
\&        # Parent element is a Lire report element.
\&    } elsif ( $self\->in_element( "listitem" ) ) {
\&        # We are in a DocBook listitem element
\&    }
.Ve
.ie n .SS "within_element( $element_name )"
.el .SS "within_element( \f(CW$element_name\fP )"
.IX Subsection "within_element( $element_name )"
This returns the number of times an element is opened in the current
element ancestor. Like for the \fIin_element()\fR, the element's name should
have been defined by \fIelements_spec()\fR, otherwise the method will croak.
.SS "\fIrecognized_string()\fP"
.IX Subsection "recognized_string()"
Returns the string that trigger the current event.
.SS "\fIdepth()\fP"
.IX Subsection "depth()"
Returns the number of opened and not yet closed elements. In start and
end handlers, the current elemnt is part of that list.
.SH "EVENT HANDLERS METHODS"
.IX Header "EVENT HANDLERS METHODS"
These are methods that are called during the \s-1XML\s0 parsing.
.SS "\fIparse_start()\fP"
.IX Subsection "parse_start()"
This methods is invoked once before the document is parsed. It can be
used for any initialization the processor has to do. Default
implementation does nothing.
.SS "parse_end( )"
.IX Subsection "parse_end( )"
This methods is invoked once after all the \s-1XML\s0 file was processed. The
value that this method returns will be returned by the \fIparse()\fR or
\&\fIparsefile()\fR method (whichever was used to start the parsing). Default
implementation does nothing.
.ie n .SS "element_start( $name, $attributes )"
.el .SS "element_start( \f(CW$name\fP, \f(CW$attributes\fP )"
.IX Subsection "element_start( $name, $attributes )"
Called when a valid element is opened. \f(CW$name\fR contains the name of the
element. This name is the canonical form, that is that if the element
is within a namespace, it will be prefixed with the prefix declared by
the \fInamespaces()\fR method. \f(CW$attributes\fR contains the defined attributes
in an hash reference.
.PP
The default method will dispatch to the handlers defined by
\&\fIelements_spec()\fR.
.ie n .SS "element_end( $name )"
.el .SS "element_end( \f(CW$name\fP )"
.IX Subsection "element_end( $name )"
Called when a valid element is closed. \f(CW$name\fR contains the name of the
element. Default implementation dispatch to the handler defined by
\&\fIelements_spec()\fR.
.ie n .SS "pcdata( $text )"
.el .SS "pcdata( \f(CW$text\fP )"
.IX Subsection "pcdata( $text )"
Called when parsed character data are encountered in an element which
is allowed to contain \s-1PCDATA\s0. Default implementation dispatch to the
handler defined by \fIelements_spec()\fR.
.ie n .SS "ignorable_ws( $ws )"
.el .SS "ignorable_ws( \f(CW$ws\fP )"
.IX Subsection "ignorable_ws( $ws )"
Called when whitespace is encountered while processing an element
which cannot contain \s-1PCDATA\s0. Default implementation does nothing. This
is mainly used by parser which want to keep the user's format.
.SH "HELPERS METHODS"
.IX Header "HELPERS METHODS"
Two common tasks when writing event-based parsers is to use \*(L"stacks\*(R"
and \*(L"collectors\*(R". The XMLParser object offers some method to manage
these common objects.
.ie n .SS "init_collector( $name )"
.el .SS "init_collector( \f(CW$name\fP )"
.IX Subsection "init_collector( $name )"
This initialize a collector with the name \f(CW$name\fR. If there was already
a collector defined under this name, its content will be reset to the
empty string ''.
.ie n .SS "collect( $name, $text )"
.el .SS "collect( \f(CW$name\fP, \f(CW$text\fP )"
.IX Subsection "collect( $name, $text )"
Appends \f(CW$text\fR to the collector \f(CW$name\fR. An exception will be thrown if
no collector \f(CW$name\fR was previously defined.
.ie n .SS "get_collector( $name )"
.el .SS "get_collector( \f(CW$name\fP )"
.IX Subsection "get_collector( $name )"
Returns the content accumulated in the collector \f(CW$name\fR. An exception
will be thrown if no collector \f(CW$name\fR was previously defined.
.ie n .SS "collector_start( $element, $attributes )"
.el .SS "collector_start( \f(CW$element\fP, \f(CW$attributes\fP )"
.IX Subsection "collector_start( $element, $attributes )"
This is a method which can be used as a start event handler. It will
define a collector with the same name than the element which is
started.
.ie n .SS "collector_char( $text )"
.el .SS "collector_char( \f(CW$text\fP )"
.IX Subsection "collector_char( $text )"
This is a method which can be used as a char event handler. It will
append \f(CW$text\fR to the collector named under the element in which this
text occurs.
.ie n .SS "init_stack( $name )"
.el .SS "init_stack( \f(CW$name\fP )"
.IX Subsection "init_stack( $name )"
Initialize a stack object named \f(CW$name\fR.
.ie n .SS "stack_push( $name, $value )"
.el .SS "stack_push( \f(CW$name\fP, \f(CW$value\fP )"
.IX Subsection "stack_push( $name, $value )"
Returns true if the stack \f(CW$name\fR is empty. An exception will be raise
if no stack \f(CW$name\fR was defined.
.ie n .SS "stack_depth( $name )"
.el .SS "stack_depth( \f(CW$name\fP )"
.IX Subsection "stack_depth( $name )"
Returns the number of element on the stack \f(CW$name\fR. An
exception will be raise if no stack \f(CW$name\fR was defined.
.ie n .SS "stack_push( $name, $value )"
.el .SS "stack_push( \f(CW$name\fP, \f(CW$value\fP )"
.IX Subsection "stack_push( $name, $value )"
Pushes \f(CW$value\fR onto the stack \f(CW$name\fR. An exception will be raise if no
stack \f(CW$name\fR was defined.
.ie n .SS "stack_pop( $name )"
.el .SS "stack_pop( \f(CW$name\fP )"
.IX Subsection "stack_pop( $name )"
Removes and returns the top value on the stack \f(CW$name\fR. An exception
will be raised if no stack \f(CW$name\fR was defined or if the stack is empty.
.ie n .SS "stack_peek( $name )"
.el .SS "stack_peek( \f(CW$name\fP )"
.IX Subsection "stack_peek( $name )"
Returns the top value of the stack \f(CW$name\fR. An exception will be raised if
no stack \f(CW$name\fR was defined or if the stack is empty.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 2
\& Lire::Config::SpecParser(3pm), Lire::ReportParser(3pm),
\& Lire::XMLSpecContainer(3pm)
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  Francis J. Lacoste <flacoste@logreport.org>
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR XMLParser.pm,v 1.11 2006/07/23 13:16:30 vanbaal Exp $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2004 Stichting LogReport Foundation LogReport@LogReport.org
.PP
This file is part of Lire.
.PP
Lire is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program (see \s-1COPYING\s0); if not, check with
http://www.gnu.org/copyleft/gpl.html.