NAME

XML::Filter::Mode - Filter out all chunks not in the current mode.

SYNOPSIS

    use XML::Filter::Mode;
    use strict;

    my $filter = XML::Filter::Mode->new( Modes => "a,b,c" );
    my $filter = XML::Filter::Mode->new( Modes => [qw( a b c )] );

    ## To inspect the modes:
    my @modes = $filter->modes;

    ## To change the modes:
    $h->modes( qw( d e ) );

DESCRIPTION

Filters portions of documents based on a mode= attribute.

I use this to have XML documents that can be read in several modes, for instance "test", "demo" and normal (ie not test or demo), or "C", "Bytecraft_C", "Perl".

Mode names must contain only alphanumerics and "_" (ie match Perl's \w regexp assertion).

The filter is given a comma separated list of modes. Each element in the XML document may have a mode="" attribute that gives a mode expression. If there is no mode attribute or it is empty or the mode expression matches the list of modes, then the element is accepted. Otherwise it and all of its children are cut from the document.

The mode expression is a boolean expression using the operators & (which unfortunately must be escaped as "&amp;"), |, , to build mode matching expressions from a list Parentheses may be used to group operations. of words. , and <|> are synonyms.

! may be used as a prefix negation operator, so !a means "unless mode a".

Examples:

    Modes    mode="..." Action
    Enabled  Value
    =====    ========== ======
    (none)   ""         pass

    a        ""         pass
    a        "a"        pass
    a        "a"        pass
    a,b      "a"        pass
    a        "a,b"      pass
    b        "a,b"      pass
    a,b      "a,b"      pass
    b        "!a,b"     pass
    a,b      "a b"      pass

    (none)   "b"        cut
    a        "b"        cut
    a        "a&b"  cut
    b        "a&b"  cut
    a        "!a,b"     cut
    a        "!a"       cut

METHODS

new

    my $filter = XML::Filter::Mode->new( Modes => \@modes );

where $modes is a comma separated list of mode names and @modes is a list of mode names.

modes

    $filter->modes( "test,debug" );
    $filter->modes( qw( test debug ) );
    my @modes = $filter->modes;

Sets/gets the modes to be active during parse. Note that the comma is the only separator allowed, although whitespace may surround it. This is not the same comma as used in the mode="" attribute values, this comma is just a list separator, that one is

Pass in an undef to clear the list.

Returns a list of mode names.

LIMITATIONS

The modes passed in are a list and the attributes in the document are an expression. Some applications might prefer the reverse, so the user could say "give me elements for ( A and B ) or C or something. But we can address that when we get there.

COPYRIGHT

Copyright 2003, R. Barrie Slaymaker, Jr., All Rights Reserved

LICENSE

You may use this module under the terms of the BSD, Artistic, or GPL licenses, any version.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>