Provided by: libbadger-perl_0.16-3_all bug

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.