NAME

Badger::Filter - object for simple filtering

SYNOPSIS

    use Badger::Filter;
    
    # filter to only include certain things
    my $filter = Badger::Filter->new(
        include => [
            'meat',
            qr/beer|wine/,
            sub { $_[0] eq 'soda' },
        ],
    );

    # filter to only exclude certain things
    my $filter = Badger::Filter->new(
        exclude => [
            'cheese',
            qr/alcohol-free|salad|diet/,
            sub { $_[0] eq 'diet soda' },
        ],
    );

    # filter to include and exclude
    my $filter = Badger::Filter->new(
        include => [
            ...
        ],
        exclude => [
            ...
        ],
    );

    # filtering items
    my @items = $filter->accept(
        'meat', 'cheese', 'potato salad', 'green salad',
        'beer', 'alcohol-free beer',
        'wine', 'soda', 'diet soda'
    );

DESCRIPTION

This module defines a simple object for filtering data. Items can be included and/or excluded via a simple set of rules.

    use Badger::Filter;
    
    my $filter = Badger::Filter->new(
        include => [
            # inclusion rules
        ],
        exclude => [
            # exclusion rules
        ],
    );

The rules that can be specified in either include or exclude options can be simple strings, regular expressions, hash or list references.

    my $filter = Badger::Filter->new(
        include => [
            'meat',                     # fixed string
            qr/beer|wine/,              # regular expression
            sub { $_[0] eq 'soda' },    # subroutine,
            {
                foo => 1,               # 'foo' fixed string
                bar => 1,               # 'bar' fixed string
                baz => 0,               # ignored (not a true value)
            },
        ],
    );

The accept() method returns any items that match any of the include rules and don't match any exclude rules.

    my @matching = $filter->accept(@candidates);

If there are any include rules, then a candidate item must match at least one of them to be included. If there aren't any include rules then the candidate is assumed to be included by default.

All candidates that are included are then filtered through the exclude rules. If a candidate matches an exclude rule then it is rejected. If it doesn't match an exclude rule, or there aren't any exclude rules defined then the candidate item is accepted.

CONFIGURATION OPTIONS

include

One or more items that should be included (i.e. not filtered out) by the filter. This can be any of:

A simple string. This should match a candidate string exactly for it to be included.
A string containing a '*' wilcard character, e.g. "foo/*". The star is used to represent any sequence of characters.
A regular expression. This should match a candidate string for it to be included.
A code reference. The function will be called, passing the candidate as the only argument. It should return any TRUE value if the item should be included or false if not.
A hash reference. All keys in the hash reference with corresponding values set to any TRUE value are considered to be simple, static strings that a candidate string should match.
A list reference. Containing any of the above.

exclude

One or more items that should be excluded (i.e. filtered out) by the filter. This can be any of the same argument types as for include.

METHODS

new(%options)

Constructor method.

    my $filter = Badger::Filter->new(
        include => ['badger'],
        exclude => ['ferret'],
    );

accept(@items)

Returns a list (in list context) or reference to a list (in scalar context) of all items passed as arguments that are accepted (passed through) by the filter. Each item is tested via a call to item_accepted().

reject(@items)

Returns a list (in list context) or reference to a list (in scalar context) of all items passed as arguments that are rejected by the filter. Each item is tested via a call to item_rejected()).

item_accepted($item)

Return true if the item is included (via a call to the item_included() method) and not excluded (ditto to item_excluded).

    my $accept = $filter->item_accepted($candidate);

item_rejected($item)

Return the logical opposite of accepted().

    my $reject = $filter->item_rejected($candidate);

item_included($item)

Tests if $item should be included by the filter (i.e. passed through, NOT filtered out).

If there is no include specification defined then the item is accepted by default (return value is TRUE).

If there is an include specification then the item must match any one of the include checks for it to be included (returns TRUE), otherwise it is rejected (returns FALSE).

item_excluded($item)

Tests if $item should be excluded by the filter (i.e. NOT passed through, filtered out).

If there is no exclude specification defined then the item is accepted by default. In this case, the return value is FALSE (i.e. item is NOT excluded, thus it is included).

If there is an exclude specification then the item will be excluded (return value is TRUE) if it matches any of the exclude checks. Otherwise the method returns FALSE to indicate that the item is NOT excluded (i.e. included).

AUTHOR

Andy Wardley <http://wardley.org/>

COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.