NAME
    "XML::Filter::Conditional" - an XML SAX filter for conditionally
    ignoring XML content

SYNOPSIS
    CODE:

     package My::XML::Filter;
     use base qw( XML::Filter::Conditional );

     sub store_switch
     {
        my $self = shift;
        my ( $e ) = @_;

        my $ename = $e->{Attributes}{'{}env'}{Value};
        return $ENV{$ename};
     }

     sub eval_case
     {
        my $self = shift;
        my ( $value, $e ) = @_;

        return $value eq $e->{Attributes}{'{}value'}{Value};
     }

    XML:

     <message>
       <switch env="USER">
         <case value="root">Hello there, root user</case>
         <case value="mail">Hello there, mail user</case>
         <otherwise>Hello, whoever you are</otherwise>
       </switch>
     </message>

DESCRIPTION
    This module provides an abstract base class to implement a PerlSAX
    filter which conditionally ignores part of the XML content. The base
    class provides the implememtation of actually surpressing SAX events for
    filtering purposes, and delegates the evaluation of matches to the
    subclassed instance.

    The evaluation of the matches is performed by the abstract methods
    "store_switch()" and "eval_case()"; see their detail below.

CONSTRUCTOR
  $filter = XML::Filter::Conditional->new( %opts )
    Takes the following options:

    Handler => OBJECT
            The PerlSAX handler (or another filter) that will receive the
            PerlSAX events from this filter.

    SwitchTag => STRING or REGEXP
    CaseTag => STRING or REGEXP
    OtherwiseTag => STRING or REGEXP
            Changes the tag names used for the "switch", "case" and
            "otherwise" elements. Can be precompiled regexp values instead
            of literal strings. The values will be matched against the local
            name of the tag only, ignoring any namespace prefix.

    NamespaceURI => STRING
            If present, the tags will only be recognised if they are part of
            the given namespace. Defaults to the empty string, meaning tags
            will only be recognised if they do not have a namespace prefix,
            and no default namespace was defined for the document.

    MatchAll => BOOLEAN
            Determines whether all of the matching "<case>" elements will be
            used, or only the first one that matches. By default, only the
            first matching one will be used.

ABSTRACT METHODS
    The following methods must be implemented by any instance of this class
    which is constructed.

  $value = $self->store_switch( $e )
    This method is called when a "switch" element is entered. It is passed
    the PerlSAX node in the $e parameter. The value it returns, in scalar
    context, is stored by the object, to pass into any "eval_case()" methods
    which may apply to this element.

    This method helps to keep the case evaluations efficient, by allowing
    the evaluation logic to precompute whatever values it might find useful
    once, to be reused by the cases themselves. See the SYNOPSIS section for
    an example.

  $bool = $self->eval_case( $value, $e )
    This method is called when a "case" element is found, to determine
    whether it should be considered to match. It is passed whatever the
    earlier "store_switch()" method returned as the $value parameter, and
    the PerlSAX node as the $e parameter. It should return a value, whose
    truth will be used to determine if the case matches.

    See the SYNOPSIS section for an example.

SEE ALSO
    *   XML::SAX - Simple API for XML

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

