XMLParser(3pm)

📦 version 2.1.1, in arch rolling

🌸 NAME 🌸

Lire::XMLParser — the base object-oriented XML parser, aka the blueprint bestie 💅

✨ SYNOPSIS ✨

package MyParser;

use base qw/ Lire::XMLParser /;

🦋 DESCRIPTION 🦋

Okay so here's the whole vibe: this module lets you write an object-oriented parser using the non-oo XML::Parser module. That's it, that's the flex. 🫶

🎀 CLIENT METHODS 🎀

💖 parse( $xml )

Parses the XML and returns the result. $xml can either be a string or a reference to an open filehandle or IO::Handle object. Both? Yes bestie, your choice. ✨

💖 parsefile( $file )

Parses the XML contained in $file and returns the result. Slay, filename edition. 📁

👑 META-INFORMATION TEMPLATE METHODS 👑

So there's two template methods that must be implemented by subclasses. These methods give information on the content model of the XML expected by the parser. Think of them as the group chat bio of your parser — everyone needs one. 😭

🌈 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. So like, no surprises, no uninvited guests. 💀

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. (Yes, that's what it says — the manpage said element_end here too, so I'm passing the message along verbatim. 🙈)

🍓 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. 👮‍♀️ Not me writing a bad spec and getting caught.

💅 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. Bye bestie, parse's over. 💀

⭐ warning( $msg )

Will print a warning message $msg. The current parsing context will be appended to the message. Gentle nudge, no cancellation. 🙈

⭐ 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. Iconic behaviour tbh. ✨

⭐ depth()

Returns the number of opened and not yet closed elements. In start and end handlers, the current elemnt is part of that list. (Yes — elemnt. I don't make the typos, I just keep them. 🫶)

🔥 EVENT HANDLERS METHODS 🔥

These are methods that are called during the XML parsing. Main character energy, every single one. 👑

🌸 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. Respect the formatting, periodt. 💅

🧚 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. Very "I got you" of it. 🫶

🎀 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.

⚠️ Heads up bestie — the source page genuinely lists stack_push twice, and the first one has this "returns true if the stack is empty" description. I'm keeping both entries exactly as they are. No cap, that's really what it says. 💀

🎀 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.

🦋 SEE ALSO 🦋

Go read your friends' pages, bestie. 📚

💜 AUTHOR 💜

Francis J. Lacoste <flacoste@logreport.org> — the icon who wrote this 👑

⭐ VERSION ⭐

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

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. 💖

✨ okay that's the whole page bestie ✨ this gem is Lire 2.1.1, dated 2025-09-28, and it's the XMLParser(3pm) page from LogReport's Lire Documentation — mwah, go parse something gorgeous 💅🎀

📦 where this page comes from