Badger::Filter(3pm)

💖 Badger::Filter 💖

ok so this is the manual for Badger::Filter(3pm), a little Perl module from the User Contributed Perl Documentation crew. it's a whole vibe: it filters stuff. that's it. that's the girl. 🎀

---

✨ NAME ✨

Badger::Filter — object for simple filtering 🧚

---

🌸 SYNOPSIS 🌸

bestie here's the whole thing in action, no cap:

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 🦋

okay so this module defines a simple object for filtering data. items get included and/or excluded via a simple set of rules. it's giving bouncer at the club but make it Perl. 💅

use Badger::Filter;

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

the rules you can drop into either the include or exclude options can be simple strings, regular expressions, hash references or list references. iconic behavior honestly.

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

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. main character energy, it just gets in. 👑

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

---

🎀 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. yeah same options, different intentions bestie. 🙈

---

💅 METHODS 💅

💜 new(%options)

constructor method. it makes the filter, the filter is made. 🌈

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

✨ accept(@items)

returns a list (in list context) or a 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 a 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()). (yes the original has that extra ) — i said what i said, keeping it exactly as it is, no cap. 😭)

🧚 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). it's included, she's in her era.

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.

---

ok that's the whole page bestie, you ate. 💖 this lil masterpiece is living in perl v5.36.0, dated 2023-08-28, filed under Badger::Filter(3pm) — go forth and filter, icon. 🫶✨