# XML::Handler::Subs - phpMan

## 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)] 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)], [PerlSAX.pod(3)]