Ubuntu Manpage: Lire::XMLParser - Base object-oriented XML parser.

Provided by: lire-devel-doc_2.1.1-2.1_all

NAME

       Lire::XMLParser - Base object-oriented XML parser.

SYNOPSIS

           package MyParser;

           use base qw/ Lire::XMLParser /;

DESCRIPTION

       This module makes it possible to write object-oriented parser using the non-oo XML::Parser module.

CLIENT METHODS

   parse( $xml )
       Parse the XML and returns the result. $xml can either be a string or a reference to an open filehandle or
       IO::Handle object.

   parsefile( $file )
       Parses the XML contained in $file and returns the result.

META-INFORMATION TEMPLATE METHODS

       Two template methods must be implemented by subclasses. These methods gives information on the content
       model of the XML expected by the parser.

   namespaces()
       This method should return an hash reference. The keys are XML namespaces understood by the parser. The
       value is the prefix which is used for that namespace in the elements_spec() method.

   elements_spec()
       This method should return an hash reference. The key are the known XML elements. An error will be thrown
       by the parser when an element not defined in this hash is encountered.

       The key should be of the form [ prefix : ] element_name. If prefix is used it should be defined in the
       namespaces() method.

       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:

       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 elements_spec() 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 PCDATA, the string 'PCDATA' should be listed in the array.

       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 element_end if it exists, or no handler otherwise. '_' is substituted for invalid method
           name characters, i.e. report-spec becomes report_spec_start.

       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 element_end if it exists, or no handler otherwise. '_' is substituted for invalid method
           name characters, i.e. report-spec becomes report_spec_end.

       char
           This specify the handler called when PCDATA is encountered within the element. This can  only  happen
           if  'PCDATA' 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 element_char if it exists, or
           no handler otherwise. '_' is substituted for invalid method name characters, i.e.  list-item  becomes
           list_item_char.

       The  specification  can also be an array reference, in that case it will be interpreted as the content of
       the 'content' hash attribute.

       Errors will be reported for invalid specification.

UTILITY METHODS

   expat()
       During the parse, this returns the underlying Lire::XMLParser::Expat parser object.

   error( $msg )
       Will terminate parsing with error message $msg. The current parsing  context  will  be  appended  to  the
       message.

   warning( $msg )
       Will print a warning message $msg. The current parsing context will be appended to the message.

   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 elements_spec().

   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 elements_spec().

   in_element( $element_name )
       This  returns  true  if  the  innermost  currently  opened  element  has  the same name as $element_name.
       $element_name should be one of the elements defined by elements_spec(), otherwise the method will croak.

       Example:

           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
           }

   within_element( $element_name )
       This returns the number of times an element is opened in the  current  element  ancestor.  Like  for  the
       in_element(),  the  element's name should have been defined by elements_spec(), otherwise the method will
       croak.

   recognized_string()
       Returns the string that trigger the current event.

   depth()
       Returns the number of opened and not yet closed elements. In start and end handlers, the  current  elemnt
       is part of that list.

EVENT HANDLERS METHODS

       These are methods that are called during the XML parsing.

   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.

   parse_end( )
       This methods is invoked once after all the XML file was processed. The value  that  this  method  returns
       will  be returned by the parse() or parsefile() method (whichever was used to start the parsing). Default
       implementation does nothing.

   element_start( $name, $attributes )
       Called when a valid element is opened. $name 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 namespaces() method. $attributes contains the defined attributes in an hash reference.

       The default method will dispatch to the handlers defined by elements_spec().

   element_end( $name )
       Called  when  a  valid  element is closed. $name contains the name of the element. Default implementation
       dispatch to the handler defined by elements_spec().

   pcdata( $text )
       Called when parsed character data are encountered in an element  which  is  allowed  to  contain  PCDATA.
       Default implementation dispatch to the handler defined by elements_spec().

   ignorable_ws( $ws )
       Called  when  whitespace  is encountered while processing an element which cannot contain PCDATA. Default
       implementation does nothing. This is mainly used by parser which want to keep the user's format.

HELPERS METHODS

Two common tasks when writing event-based parsers is to use "stacks" and "collectors". The XMLParser
object offers some method to manage these common objects.

init_collector( $name )
This initialize a collector with the name $name. If there was already a collector defined under this
name, its content will be reset to the empty string ''.

collect( $name, $text )
Appends $text to the collector $name. An exception will be thrown if no collector $name was previously
defined.

get_collector( $name )
Returns the content accumulated in the collector $name. An exception will be thrown if no collector $name
was previously defined.

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.

collector_char( $text )
This is a method which can be used as a char event handler. It will append $text to the collector named
under the element in which this text occurs.

init_stack( $name )
Initialize a stack object named $name.

stack_push( $name, $value )
Returns true if the stack $name is empty. An exception will be raise if no stack $name was defined.

stack_depth( $name )
Returns the number of element on the stack $name. An exception will be raise if no stack $name was
defined.

stack_push( $name, $value )
Pushes $value onto the stack $name. An exception will be raise if no stack $name was defined.

stack_pop( $name )
Removes and returns the top value on the stack $name. An exception will be raised if no stack $name was
defined or if the stack is empty.

stack_peek( $name )
Returns the top value of the stack $name. An exception will be raised if no stack $name was defined or if
the stack is empty.

AUTHOR

         Francis J. Lacoste <flacoste@logreport.org>

VERSION

       $Id: XMLParser.pm,v 1.11 2006/07/23 13:16:30 vanbaal Exp $

COPYRIGHT

       Copyright (C) 2004 Stichting LogReport Foundation LogReport@LogReport.org

       This file is part of Lire.

       Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public
       License  as  published  by  the  Free  Software  Foundation; either version 2 of the License, or (at your
       option) any later version.

       This program is distributed in the hope that it will be useful, but WITHOUT ANY  WARRANTY;  without  even
       the  implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
       License for more details.

       You should have received a copy of the GNU General Public License along with this program (see  COPYING);
       if not, check with http://www.gnu.org/copyleft/gpl.html.

Lire 2.1.1                                         2006-07-23                                     XMLParser(3pm)