---
name: "XML::Handler::Subs"
section: "3pm"
platform: "linux"
package: "libxml-perl"
version: "0.08-9"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/XML::Handler::Subs"
---

# XML::Handler::Subs(3pm)

a PerlSAX handler base class for calling user-defined subs

## NAME

XML::Handler::Subs - a PerlSAX handler base class for calling user-defined subs

## SYNOPSIS

```
 use XML::Handler::Subs;
 package MyHandlers;
 use vars qw{ @ISA };
 sub s_NAME { my ($self, $element) = @_ };
 sub e_NAME { my ($self, $element) = @_ };
 $self->{Names};    # an array of names
 $self->{Nodes};    # an array of $element nodes
 $handler = MyHandlers->new();
 $self->in_element($name);
 $self->within_element($name);
```

## DESCRIPTION

`"XML::Handler::Subs"` is a base class for PerlSAX handlers. `"XML::Handler::Subs"` is subclassed to implement complete behavior and to add element-specific handling.

Each time an element starts, a method by that name prefixed with \`s\_' is called with the element to be processed.  Each time an element ends, a method with that name prefixed with \`e\_' is called.  Any special characters in the element name are replaced by underscores.

Subclassing XML::Handler::Subs in this way is similar to XML::Parser's Subs style.

XML::Handler::Subs maintains a stack of element names, \``"$self-"`{Names}', and a stack of element nodes, \``"$self-"`{Nodes}\>' that can be used by subclasses.  The current element is pushed on the stacks before calling an element-name start method and popped off the stacks after calling the element-name end method.  The \``in_element()`' and \``within_element()`' calls use these stacks.

If the subclass implements \``start_document()`', \``end_document()`', \``start_element()`', and \``end_element()`', be sure to use \``"SUPER::"`' to call the the superclass methods also.  See [**perlobj**(1)](/perlobj/1.md) for details on SUPER::.  \``SUPER::start_element()`' and \``SUPER::end_element()`' return 1 if an element-name method is called, they return 0 if no method was called.

XML::Handler::Subs does not implement any other PerlSAX handlers.

XML::Handler::Subs supports the following methods:

- new( *OPTIONS* )

  A basic \``new()`' method.  \``new()`' takes a list of key, value pairs or a hash and creates and returns a hash with those options; the hash is blessed into the subclass.

- in\_element($name)

  Returns true if \``$name`' is equal to the name of the innermost currently opened element.

- within\_element($name)

  Returns the number of times the \``$name`' appears in Names.

## AUTHOR

Ken MacLeod, ken@bitsko.slc.ut.us

## SEE ALSO

[**perl**(1)](/perl/1.md), **PerlSAX.pod**(3)