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 '*' wildcard 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

       Copyright (C) 2013 Andy Wardley.  All Rights Reserved.

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