---
name: "Badger::Filter"
section: "3pm"
platform: "linux"
package: "libbadger-perl"
version: "0.16-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Badger::Filter"
---

# Badger::Filter(3pm)

object for simple filtering

## 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.