File Coverage

blib/lib/Params/Filter.pm

Criterion	Covered	Total	%
statement	149	149	100.0
branch	79	92	85.8
condition	17	22	77.2
subroutine	14	14	100.0
pod	9	9	100.0
total	268	286	93.7

package Params::Filter;
use v5.36;
our $VERSION = '0.016';

=head1 NAME

Params::Filter - Field filtering for strict parameter construction

=encoding utf-8

=head1 SYNOPSIS

    use Params::Filter	qw/filter/;    # import filter() subroutine

    # Define filter rules
    my @required_fields = qw(name email);
    my @accepted_fields = qw(phone city state zip);
    my @excluded_fields = qw(ssn password);

    # Functional interface
    # Apply filter to incoming data (from web form, CLI, API, etc.)
    my ($filtered_data, $status) = filter(
        $incoming_params,    # Data from external source
        \@required_fields,
        \@accepted_fields,
        \@excluded_fields,
    );

    if ($filtered_data) {
        # Success - use filtered data
        process_user($filtered_data);
    } else {
        # Error - missing required fields
        die "Filtering failed: $status";
    }

    # Object-oriented interface
    my $user_filter = Params::Filter->new_filter({
        required => ['username', 'email'],
        accepted => ['first_name', 'last_name', 'phone', 'bio'],
        excluded => ['password', 'ssn', 'credit_card'],
    });

    # Apply same filter to multiple incoming datasets
    my ($user1, $msg1) = $user_filter->apply($web_form_data);
    my ($user2, $msg2) = $user_filter->apply($api_request_data);
    my ($user3, $msg3) = $user_filter->apply($db_record_data);

    # Closure interface (maximum speed)
    use Params::Filter qw/make_filter/;

    my $fast_filter = make_filter(
        [qw(id username)],      # required
        [qw(email bio)],        # accepted
        [qw(password token)],   # excluded
    );

    # Apply to high-volume data stream
    for my $record (@large_dataset) {
        my $filtered = $fast_filter->($record);
        next unless $filtered;  # Skip if required fields missing
        process($filtered);
    }

=head1 DESCRIPTION

C provides lightweight parameter filtering that checks
only for the presence or absence of specified fields. It does B validate
values - no type checking, truthiness testing, or lookups.

This module separates field filtering from value validation:

=over 4

=item * **Field filtering** (this module) - Check which fields are present/absent

=item * **Value validation** (later step) - Check if field values are correct

=back

=head2 Primary Benefits

The main advantages of using Params::Filter are:

=over 4

=item * **Consistency** - Converts varying incoming data formats to consistent key-value pairs

=item * **Security** - Sensitive fields (passwords, SSNs, credit cards) never reach your validation code or database statements

=item * **Compliance** - Automatically excludes fields that shouldn't be processed or stored (e.g., GDPR, PCI-DSS)

=item * **Correctness** - Ensures only expected fields are processed, preventing accidental data leakage or processing errors

=item * **Maintainability** - Clear separation between data filtering (what fields to accept) and validation (whether values are correct)

=back

=head2 Performance Considerations

The functional and OO interfaces include features that add overhead
compared to manual hash lookups, especially when the incoming data is in a known
consistent format. The value of Params::Filter shows in its capability to assure the
security, compliance, and correctness benefits listed above.

For speed with fewer features, the closure interface (C)
provides maximum performance and can be faster than hand-written Perl filtering
code due to pre-computed exclusion lookups and specialized closure variants.
Use C for hot code paths or high-frequency filtering.

For all interfaces, Params::Filter CAN improve overall performance when downstream
validation is expensive (database statements, API calls, complex regex) by failing
fast when required fields are missing.

A simple benchmark comparing the validation cost of typical input to that of
input restricted to required fields would reveal any speed gain with expensive
downstream validations.

=head2 This Approach Handles Common Issues

=over 4

=item * Subroutine signatures can become unwieldy with many parameters

=item * Ad-hoc argument checking is error-prone

=item * Validation may not catch missing inputs quickly enough

=item * Many fields to check multiplies validation time (for expensive validation)

=back

=head2 When to Use This Module

This module is useful when you have:

=over 4

=item * Known parameters for downstream input or processes (API calls, method/subroutine arguments, database operations)

=over 8

=item * Fields that must be provided for success downstream ("required")

=item * Fields useful downstream if provided ("accepted")

=item * Fields to remove before further processing ("excluded")

=back

=item * Incoming data from external sources (web forms, APIs, databases, user input)

=item * No guarantee that incoming data is consistent or complete

=item * Multiple data instances to process with the same rules

=item * Multiple uses tapping incoming data

=item * A distinction between missing and "false" data

=back

=head1 FEATURES

=over 4

=item * **Dual interface** - Functional or OO usage

=item * **Fast-fail** - Returns immediately on missing required parameters

=item * **Fast-success** - Returns immediately if all required parameters are provided and no others are provided or will be accepted

=item * **Flexible input** - Accepts hashrefs, arrayrefs, or scalars

=item * **Wildcard support** - Use C<'*'> in accepted list to accept all fields

=item * **No value checking** - Only presence/absence of fields

=item * **Debug mode** - Optional warnings about unrecognized or excluded fields

=item * **Method chaining** - Modifier methods return C<$self>

=item * **Perl 5.36+** - Modern Perl with signatures and post-deref

=item * **No dependencies** - Only core Perl's L

=back

=head2 When NOT to Use This Module

If you're constructing both the filter rules B the data structure
at the same point in your code, you probably don't need this module.
The module's expected use is to apply pre-defined rules to data that
may be inconsistent or incomplete for its intended use.
If there isn't repetition or an unknown/unreliable data structure, this might be overkill.

=cut

=head2 This Module Does NOT Do Fancy Stuff

As much as this module attempts to be versatile in usage, there are some B

=over 4

=item * No regex field name matching for designating fields to require, accept, or exclude

=item * No conditional field designations I a filter:

    C   # No way a filter can do this

=item * No coderefs or callbacks for use when filtering

=item * No substitutions or changes to field names

=item * No built-in filter lists except an empty arrayref C<[]> = none

=item * No fields ADDED to yielded data, EXCEPT:

=over 8

=item * If the provided data resolves to a list or array with an odd number of elements, the LAST element is treated as a flag, set to the value 1

=item * If the provided data resolves to a single non-reference scalar (probably a text string) the data is stored as a hashref value with the key C<'_'>, and returned if C<'_'> is included in the accepted list or the list is set to C<['*']> (accept all)

=back

=back

=cut

use Exporter;
our @ISA		= qw{ Exporter  };
our @EXPORT		= qw{  };
our @EXPORT_OK	= qw{ filter make_filter };

sub new_filter {
	my ($class,$args) = @_;
	$args = {} unless ($args and ref($args) =~ /hash/i);
	my $self			= {
		required	=> $args->{required} || [],
		accepted	=> $args->{accepted} || [],
		excluded	=> $args->{excluded} || [],
		debug		=> $args->{DEBUG} || $args->{debug} || 0,
	};
	bless $self, __PACKAGE__;
	return $self;
}

sub make_filter ($req,$ok=[],$no=[]) {
	my $exclusions	= { map { $_ => 1 } $no->@* };
	my $any			= grep { $_ eq '*' } $ok->@*; # added to enable use of '*' wildcard'
	unless ($ok->@*) {
		# Only check for required; nothing else will be included in output
		return sub {
			my ($unfiltered)	= @_;
			my $filtered		= {};
			for ($req->@*) {
				return unless exists $unfiltered->{$_};
			}
			$filtered->@{ $req->@* }	= $unfiltered->@{ $req->@* };
			return $filtered;
		}
	}
	return $any
	# Check for required, and allow all additional input fields, minus exclusions
	? sub {
		my ($unfiltered)	= @_;
		my $filtered		= {};
		for ($req->@*) {
			return unless exists $unfiltered->{$_};
		}
		$filtered->@{ $req->@* }	= $unfiltered->@{ $req->@* };
		for (keys $unfiltered->%*) {
			next if $exclusions->{$_};
			$filtered->{$_} = $unfiltered->{$_};
		}
		return $filtered;
	}
	# Check for required, and allow only specified accepted input fields, minus exclusions
	:  sub {
		my ($unfiltered)	= @_;
		my $filtered		= {};
		for ($req->@*) {
			return unless exists $unfiltered->{$_};
		}
		$filtered->@{ $req->@* }	= $unfiltered->@{ $req->@* };
		for ($ok->@*) {
			next if $exclusions->{$_};
			$filtered->{$_} = $unfiltered->{$_} if exists $unfiltered->{$_};
		}
		return $filtered;
	}
}

=head1 SECURITY

This module provides important security benefits by excluding sensitive fields
before they reach downstream systems like logging, validation, or storage.

=head2 Safe Logging - Exclude Credentials

A common security requirement is logging user activity without exposing credentials:

    use Params::Filter qw/make_filter/;

    # Create filter for safe logging - exclude credentials
    my $log_filter = make_filter(
        [qw(timestamp action)],           # required
        [qw(username email ip_address)],  # accepted - safe to log
        [qw(user_id password session_token)], # excluded - never logged
    );

    # Web form submission from user login
    my $form_data = {
        timestamp    => '2026-01-27T10:30:00Z',
        action       => 'login_attempt',
        username     => 'alice',
        email        => '[e-mail]',
        ip_address   => '192.168.1.100',
        user_id      => 12345,
        password     => 'secret123',      # MUST NOT appear in logs
        session_token => 'abc123xyz',     # MUST NOT appear in logs
    };

    # Filter for logging - credentials automatically excluded
    my $log_entry = $log_filter->($form_data);
    write_audit_log($log_entry);
    # Logged: { timestamp, action, username, email, ip_address }
    # Never logged: user_id, password, session_token

=head2 Multiple Filters for Data Segregation

Use different filters on the same input to route data to appropriate subsystems,
ensuring credentials only reach authentication and never reach public display:

    # Auth filter - requires credentials, excludes public data
    my $auth_filter = Params::Filter->new_filter({
        required => ['user_id', 'password'],
        accepted => [],  # Only credentials, nothing else
        excluded => ['name', 'comment', 'category', 'date'],
    });

    # Comment filter - accepts public data, excludes credentials
    my $comment_filter = Params::Filter->new_filter({
        required => ['name', 'comment'],
        accepted => ['category', 'date'],
        excluded => ['user_id', 'password'],  # Never show on comment page
    });

    # Single web form submission with mixed data
    my $form_submission = {
        user_id  => 12345,
        password => 'secret123',
        name     => 'Alice',
        comment  => 'Great article!',
        category => 'feedback',
        date     => '2026-01-27',
    };

    # Route to authentication system - only credentials
    my ($auth_data, $auth_msg) = $auth_filter->apply($form_submission);
    if ($auth_data) {
        $app->authenticate($auth_data);
        # Sent to auth: { user_id => 12345, password => 'secret123' }
    }

    # Route to comment display - only public data
    my ($comment_data, $comment_msg) = $comment_filter->apply($form_submission);
    if ($comment_data) {
        $app->add_comment($comment_data);
        # Sent to comment page: { name => 'Alice', comment => '...', category => '...', date => '...' }
        # Password and user_id NEVER reach the comment display system
    }

=head2 Compliance Benefits

Helps meet regulatory requirements by design:

=over 4

=item * **PCI-DSS** - Ensure credit card numbers never touch logging or validation code

=item * **GDPR** - Exclude fields you shouldn't store before processing

=item * **Data Minimization** - Only process fields you actually need for each subsystem

=item * **Audit Trails** - Clear record of what fields are accepted/excluded per destination

=back

=head2 Defense in Depth

Even if downstream validation code has bugs or is later modified, excluded fields
B reach it:

    # Logging system updated to dump all input - credentials still excluded
    my $safe_data = $log_filter->($user_activity);
    log_everything($safe_data);  # Password field was already filtered out

This provides defense in depth: sensitive data is removed at the filter layer,
regardless of what happens downstream.

=head1 CLOSURE INTERFACE (Maximum Performance)

The closure interface provides B through specialized,
pre-compiled closures. This is the most important performance feature of
Params::Filter and can be faster than hand-written Perl filtering code.

B

=over 4

=item * **Fastest interface** - Pre-computed exclusions, specialized variants

=item * **Hashref input only** - No input parsing overhead (unlike functional/OO interfaces)

=item * **Immutable** - Filter cannot be modified after creation (unlike OO interface)

=item * **No error messages** - Returns C on failure (unlike functional/OO interfaces)

=item * **No debug mode** - Minimal overhead for maximum speed

=back

B Performance is critical, you have high-frequency
filtering operations, or you're processing large datasets.

=head2 make_filter

    use Params::Filter qw/make_filter/;

    # Create a reusable filter closure
    my $filter = make_filter(
        \@required,     # Arrayref of required field names
        \@accepted,     # Arrayref of optional field names (default: [])
        \@excluded,     # Arrayref of names of fields to remove (default: [])
    );

    # Apply filter to data (must be hashref)
    my $result = $filter->($input_hashref);

Creates a fast, reusable closure that filters hashrefs according to field
specifications. The closure checks only for presence/absence of fields, not
field values.

=head3 Parameters

=over 4

=item * C<\@required> - Arrayref of names of fields that B be present

=item * C<\@accepted> - Arrayref of optional names of fields to accept (default: [])

=item * C<\@excluded> - Arrayref of names of fields to remove even if accepted (default: [])

=back

=head3 Returns

A code reference that accepts a single hashref argument and returns a filtered
hashref, or C if required fields are missing.

B No error message is returned. The closure only returns the filtered
hashref or C. Use the functional or OO interfaces if you need error messages.

=head3 Specialized Closure Variants

The closure is optimized based on your configuration:

=over 4

=item * **Required-only** - When C<@accepted> is empty, returns only required fields

=item * **Wildcard** - When C<@accepted> contains C<'*'>, accepts all input fields except exclusions

=item * **Accepted-specific** - When C<@accepted> has specific fields, returns required plus those accepted fields (minus exclusions)

=back

=head3 Example

    # Create filter for user registration
    my $user_filter = make_filter(
        [qw(username email)],     # required
        [qw(full_name bio)],      # accepted
        [qw(password confirm)],   # excluded
    );

    # Apply to multiple records - very fast
    for my $record (@records) {
        my $filtered = $user_filter->($record);
        next unless $filtered;  # Skip if required fields missing
        process_user($filtered);
    }

    # Wildcard example - accept everything except sensitive fields
    my $safe_filter = make_filter(
        [qw(id type)],
        ['*'],                      # accept all other fields
        [qw(password token ssn)],   # but exclude these
    );

=head3 Performance Characteristics

=over 4

=item * Non-destructive - Original hashref is never modified

=item * Pre-computed - Exclusion hash built once at filter creation

=item * Specialized - No runtime conditionals, closure is tailored during construction

=item * Can be faster than raw Perl - Up to 20-25% faster than hand-written filtering code in many cases

=item * No overhead for multiple uses - Create once, apply many times

=back

=head3 Trade-offs Compared to Other Interfaces

=over 4

=item * **Advantages**: Maximum speed, lightweight, no feature overhead, fastest option available

=item * **Limitations**: No error messages, no debug mode, no modifier methods, no input parsing (only accepts hashrefs), immutable after creation

=item * **When to use**: High-frequency filtering, performance-critical code, hot code paths, large dataset processing

=item * **When to use OO/functional instead**: When you need error messages, debug mode, input format flexibility (arrayrefs/scalars), or dynamic reconfiguration

=back

=head1 FUNCTIONAL INTERFACE

The functional interface provides direct parameter filtering through the C function.
This interface supports flexible input parsing (hashrefs, arrayrefs, scalars) and returns
detailed error messages.

B You need flexible input formats, detailed error messages,
or one-off filtering operations.

=head2 filter

    my ($filtered, $status) = filter(
        $input_data,     # Hashref, arrayref, or scalar
        \@required,      # Arrayref of required field names
        \@accepted,      # Arrayref of optional field names (default: [])
        \@excluded,      # Arrayref of names of fields to remove (default: [])
        $debug_mode,     # Boolean: enable warnings (default: 0)
    );

    # Scalar context - returns filtered hashref or undef on failure
    my $result = filter($input, \@required, \@accepted);

Filters input data according to field specifications. Only checks for
presence/absence of fields, not field values.

=head3 Parameters

=over 4

=item * C<$input_data> - Input parameters (hashref, arrayref, or scalar)

=item * C<\@required> - Arrayref of names of fields that B be present

=item * C<\@accepted> - Arrayref of optional names of fields to accept (default: [])

=item * C<\@excluded> - Arrayref of names of fields to remove even if accepted (default: [])

=item * C<$debug_mode> - Boolean to enable warnings (default: 0)

=back

=head3 Returns

In list context: C<(hashref, status_message)> or C<(undef, error_message)>

In scalar context: Hashref with filtered parameters, or C on failure

=head3 Example

    # Define filter rules (could be from config file)
    my @required = qw(username email);
    my @accepted = qw(full_name phone);
    my @excluded = qw(password ssn);

    # Apply to incoming data from web form
    my ($user_data, $msg) = filter(
        $form_submission,
        \@required,
        \@accepted,
        \@excluded,
    );

    if ($user_data) {
        create_user($user_data);
    } else {
        log_error($msg);
    }

=head1 OBJECT-ORIENTED INTERFACE

The OO interface provides reusable filter objects that can be configured once and applied to multiple datasets. This interface includes the most features, including modifier methods for dynamic configuration.

=head2 new_filter

    my $filter = Params::Filter->new_filter({
        required => ['field1', 'field2'],
        accepted => ['field3', 'field4', 'field5'],
        excluded => ['forbidden_field'],
        DEBUG    => 1,              # Optional debug mode
    });

    # Empty constructor - rejects all fields by default
    my $strict_filter = Params::Filter->new_filter();

Creates a reusable filter object with predefined field rules. The filter
can then be applied to multiple datasets using the L method.

=head3 Parameters

=over 4

=item * C - Arrayref of names of required fields (default: [])

=item * C - Arrayref of names of optional fields (default: [])

=item * C - Arrayref of names of fields to always remove (default: [])

=item * C - Boolean to enable debug warnings (default: 0)

=back

=head3 Returns

A C object

=head3 Example

    # Create filter for user registration data
    my $user_filter = Params::Filter->new_filter({
        required => ['username', 'email'],
        accepted => ['first_name', 'last_name', 'phone', 'bio'],
        excluded => ['password', 'ssn', 'credit_card'],
    });

    # Apply to multiple incoming datasets
    my ($user1, $msg1) = $user_filter->apply($web_form_data);
    my ($user2, $msg2) = $user_filter->apply($api_request_data);

=head2 apply

    my ($filtered, $status) = $filter->apply($input_data);

Applies the filter's predefined rules to input data. This is the OO
equivalent of the L function.

=head3 Parameters

=over 4

=item * C<$input_data> - Hashref, arrayref, or scalar to filter

=back

=head3 Returns

In list context: C<(hashref, status_message)> or C<(undef, error_message)>

In scalar context: Hashref with filtered parameters, or C on failure

=head3 Example

    my $filter = Params::Filter->new_filter({
        required => ['id', 'type'],
        accepted => ['name', 'value'],
    });

    # Process multiple records from database
    for my $record (@db_records) {
        my ($filtered, $msg) = $filter->apply($record);
        if ($filtered) {
            process_record($filtered);
        } else {
            log_error("Record failed: $msg");
        }
    }

=cut

sub set_required {
	my ($self, @fields)	= @_;
	@fields 			= ref $fields[0] eq 'ARRAY' ? $fields[0]->@* : @fields;
	my @required		= grep { defined } @fields;
	$self->{required}	= @required ? [ @required ] : [];
	return $self;
}

sub set_accepted {
	my ($self, @fields)	= @_;
	@fields 			= ref $fields[0] eq 'ARRAY' ? $fields[0]->@* : @fields;
	my @accepted		= grep { defined } @fields;
	$self->{accepted}	= @accepted ? [ @accepted ] : [];
	return $self;
}

sub accept_all {
	my ($self)			= @_;
	$self->{accepted}	= ['*'];
	return $self;
}

sub accept_none {
	my ($self)			= @_;
	$self->{accepted}	= [];
	return $self;
}

sub set_excluded {
	my ($self, @fields)	= @_;
	@fields				= ref $fields[0] eq 'ARRAY' ? $fields[0]->@* : @fields;
	my @excluded		= grep { defined } @fields;
	$self->{excluded}	= @excluded ? [ @excluded ] : [];
	return $self;
}

sub apply {
	my ($self,$args) = @_;
	my $req		= $self->{required} || [];
	my $ok		= $self->{accepted} || [];
	my $no		= $self->{excluded} || [];
	my $db		= $self->{debug} || 0;
	my @result	= filter( $args, $req, $ok, $no, $db);
	return wantarray ? @result : $result[0];
}

=head1 MODIFIER METHODS

The OO interface provides methods to modify a filter's configuration after creation.

=head2 Modifier Methods for Dynamic Configuration

The OO interface provides methods to modify a filter's configuration after creation.

    # Start with an empty filter (rejects all by default)
    my $filter = Params::Filter->new_filter();

    # Configure it in steps as needed
    $filter->set_required(['id', 'name']);
    # later:
    $filter->set_accepted(['email', 'phone'])
    $filter->set_excluded(['password']);

=head3 Available Modifier Methods

=over 4

=item * **C** - Set required fields (accepts arrayref or list)

=item * **C** - Set accepted fields (accepts arrayref or list)

=item * **C** - Set excluded fields (accepts arrayref or list)

=item * **C** - Convenience method: sets accepted to C<['*']> (wildcard mode)

=item * **C** - Convenience method: sets accepted to C<[]> (reject all extras)

=back

=head2 Important Behavior Notes

B

If no fields are provided to C, C, or C, the respective list is set to an empty array C<[]>:

    $filter->set_accepted();  # Sets accepted to `[]`
    # Result: Only required fields will be accepted (extras rejected)

B

All modifier methods return C<$self> for chaining:

    $filter->set_required(['id'])
            ->set_accepted(['name'])
            ->accept_all();  # Overrides set_accepted

B

A filter may call its modifier methods more than once, and the changes take effect immediately.

=head2 Meta-Programming Use Cases

These methods enable dynamic configuration for conditional scenarios:

    # Environment-based configuration
    my $filter = Params::Filter->new_filter();

    if ($ENV{MODE} eq 'production') {
        $filter->set_required(['api_key', 'endpoint'])
              ->set_accepted(['timeout', 'retries'])
              ->set_excluded(['debug_info']);
    }
    else {
        $filter->set_required(['debug_mode'])
              ->accept_all();
    }

    # Dynamic field lists from config
    my $config_fields = load_config('fields.json');
    $filter->set_required($config_fields->{required})
          ->set_accepted($config_fields->{accepted})
          ->set_excluded($config_fields->{excluded});

=cut

sub filter ($args,$req,$ok=[],$no=[],$db=0) {
	my %args		= ();
	my @messages	= ();	# Parsing messages (always reported)
	my @warnings	= ();	# Debug warnings (only when $db is true)
	my $wantarray	= wantarray;

	# ============================================================
	# PHASE 1: Parse input data to hashref format
	# ============================================================
	if (ref $args eq 'HASH') {
		%args	= $args->%*
	}
	elsif (ref $args eq 'ARRAY') {
		if (ref($args->[0]) eq 'HASH') {
			%args	= $args->[0]->%*;			# Ignore the rest
		}
		else {
			my @args	= $args->@*;
			if (@args == 1) {
				%args = ( '_' => $args[0] );	# make it a value with key '_'
				my $preview = length($args[0]) > 20
					? substr($args[0], 0, 20) . '...'
					: $args[0];
				push @messages => "Plain text argument accepted with key '_': '$preview'";
			}
			elsif ( @args % 2 ) {
				%args = (@args, 1);				# make last arg element a flag
				push @messages => "Odd number of arguments provided; " .
					"last element '$args[-1]' converted to flag with value 1";
			}
			else {
				%args = @args;					# turn array into hash pairs
			}
		}
	}
	elsif ( !ref $args ) {
		%args	= ( '_' => $args);				# make it a value with key '_'
		my $preview = length($args) > 20
			? substr($args, 0, 20) . '...'
			: $args;
		push @messages => "Plain text argument accepted with key '_': '$preview'";
	}

	my @required_flds	= $req->@*;
	unless ( keys %args ) {
		my $err = "Unable to initialize without required arguments: " .
			join ', ' => map { "'$_'" } @required_flds;
		return $wantarray ? (undef, $err) : undef;
	}

	if ( scalar keys(%args) < @required_flds ) {
		my $err	= "Unable to initialize without all required arguments: " .
			join ', ' => map { "'$_'" } @required_flds;
		return $wantarray ? (undef, $err) : undef;
	}

	# ============================================================
	# PHASE 2: Pre-compute optimization data structures
	# ============================================================
	# Pre-compute exclusion hash (once per call, not per field)
	my $exclusions	= { map { $_ => 1 } $no->@* };

	# Check for wildcard once (not per iteration)
	my $has_wildcard = grep { $_ eq '*' } $ok->@*;

	# ============================================================
	# PHASE 3: Check required fields and copy to output
	# ============================================================
	my $filtered	= {};

	# Check all required fields exist
	for my $fld (@required_flds) {
		return $wantarray ? (undef, "Unable to initialize without required arguments: '$fld'") : undef
			unless exists $args{$fld};
	}

	# Copy required fields using hash slice (faster than individual assignments)
	$filtered->@{ $req->@* } = @args{ $req->@* };

	# Fast return: no accepted fields (required-only)
	unless ($ok->@* or $has_wildcard) {
		my @all_msgs	= (@messages, @warnings);
		my $return_msg	= @all_msgs
			? join "\n" => @all_msgs
			: "Admitted";

		return $wantarray ? ( $filtered, $return_msg ) : $filtered;
	}

	# ============================================================
	# PHASE 4: Apply accepted/excluded fields (non-destructive)
	# ============================================================
	if ($has_wildcard) {
		# Wildcard: accept all fields except exclusions
		for my $fld (keys %args) {
			next if $exclusions->{$fld};
			next if exists $filtered->{$fld};  # Skip required fields (already copied)
			$filtered->{$fld} = $args{$fld};
		}
	}
	elsif ($ok->@*) {
		# Accepted-specific: only copy specified fields (unless excluded)
		for my $fld ($ok->@*) {
			next if $exclusions->{$fld};
			$filtered->{$fld} = $args{$fld} if exists $args{$fld};
		}
	}

	# Collect debug info about excluded/unrecognized fields
	my @unrecognized	= ();
	if ($db) {
		for my $fld (keys %args) {
			next if exists $filtered->{$fld};
			next if $exclusions->{$fld};
			push @unrecognized, $fld;
		}

		if (@unrecognized > 0) {
			push @warnings => "Ignoring unrecognized arguments: " .
				join ', ' => map { "'$_'" } @unrecognized;
		}

		my @found_excluded = grep { exists $args{$_} } $no->@*;
		if (@found_excluded > 0) {
			push @warnings => "Ignoring excluded arguments: " .
				join ', ' => map { "'$_'" } @found_excluded;
		}
	}

	# ============================================================
	# PHASE 5: Build return message
	# ============================================================
	my @all_msgs	= (@messages, @warnings);
	my $return_msg	= @all_msgs
		? join "\n" => @all_msgs
		: "Admitted";

	return $wantarray ? ( $filtered, $return_msg ) : $filtered;
}

=head1 INPUT PARSING

B This section applies to the L and L only. The L accepts only hashrefs for maximum speed.

The C function parses multiple common input formats into a consistent internal structure. This flexibility allows you to use the module with data from differing sources such as form input, arguments to subroutines/methods, fetched database records, and test input, without pre-processing.

=head2 Supported Input Formats

=head3 1. Hashref (Most Common)

##### Uses the hashref's key-value pairs as provided

    # External data source (e.g., from web form, API, or database)
    my $incoming_user = { name => 'Alice', email => '[e-mail]', phone => '555-1234' };

    # Apply filter with rules defined inline
    my ($result, $msg) = filter(
        $incoming_user,
        ['name', 'email'],
        ['phone'],
    );
    # Result: { name => 'Alice', email => '[e-mail]', phone => '555-1234' }

=head3 2. Arrayref with Even Number of Elements

##### Makes key-value pairs from arrayref elements, reading left to right

    # Pre-defined filter rules (typically defined at package level or in config)
    my @required_fields = qw(name email);
    my @accepted_fields = qw(age);

    # External data from command-line arguments or similar list source
    my @cli_args = ('name', 'Bob', 'email', '[e-mail]', 'age', 30);

    my ($result, $msg) = filter(
        \@cli_args,
        \@required_fields,
        \@accepted_fields,
    );
    # Result: { name => 'Bob', email => '[e-mail]', age => 30 }

=head3 3. Arrayref with Odd Number of Elements

##### Makes key-value pairs from arrayref elements, reading left to right, but when an array has an odd number of elements, the last element (right-most) becomes a flag assigned the value C<1>:

    # Pre-defined filter configuration
    my @required = qw(name);
    my @accepted = qw(verbose force);

    # External data with odd number of elements (e.g., CLI args with flags)
    my $command_args = ['name', 'Charlie', 'verbose', 'debug', 'force'];

    my ($result, $msg) = filter(
        $command_args,
        \@required,
        \@accepted,
        [], 1,  # Debug mode to see warning
    );
    # Result: { name => 'Charlie', verbose => 'debug', force => 1 }
    # Message includes: "Odd number of arguments provided; last element 'force' treated as flag"

=head3 4. Arrayref with Hashref as First Element

##### Uses the hashref's key-value pairs as provided, ignores rest of arrayref

    # Pre-configured filter
    my @required = qw(name);
    my @accepted = qw(age title);

    # External data source with hashref wrapped in array
    my $arg0    = { name => 'Diana', age => 25, hire_date => 2026-01-09, title => 'CTO' };
    my $arg1    = $something;
    my $arg2    = $something_else;

    my $api_response = [ $arg0, $arg1, $arg2, ];
    my ($result, $msg) = filter(
        $api_response,
        \@required,
        \@accepted,
    );
    # Result: { name => 'Diana', age => 25, title => 'CTO' }

=head3 5. Single-Element Arrayref

##### Creates a hashref with the element as the value and '_' as its key.
To make use of this feature, C<'_'> or the wildcard C<'*'> must be included in the appropriate filter lists.

    # Filter configuration accepting special '_' key
    my @required = ();
    my @accepted = qw(_);

    # External data: single-element array
    my $single_value = ['search_query'];

    my ($result, $msg) = filter(
        $single_value,
        \@required,
        \@accepted,
    );
    # Result: { _ => 'search_query' }

=head3 6. Plain Scalar (String)

##### Creates a hashref with the scalar as the value and '_' as its key.
To make use of this feature, C<'_'> or the wildcard C<'*'> must be included in the appropriate filter lists.

Note: No attempt is made to parse strings into data.

    # Pre-configured filter setup
    my @required = ();
    my @accepted = qw(_);

    # External scalar data (e.g., raw input from file or stream)
    my $raw_input = 'plain text string';

    my ($result, $msg) = filter(
        $raw_input,
        \@required,
        \@accepted,
        [], 1,  # Debug mode to see warning
    );
    # Result: { _ => 'plain text string' }
    # Message includes: "Plain text argument accepted with key '_': 'plain text string'"

=head3 7. List Passed as Arrayref

##### Flattened key-value lists must be wrapped in an arrayref

    # Filter rules defined once, reused
    my @req_fields = qw(name email);
    my @acc_fields = qw(city);

    # External key-value list data must be wrapped in arrayref
    my ($result, $msg) = filter(
        [name => 'Eve', email => '[e-mail]', city => 'Boston'],
        \@req_fields,
        \@acc_fields,
    );
    # Result: { name => 'Eve', email => '[e-mail]', city => 'Boston' }

=head2 Special Parsing Keys

=head3 The C<'_'> Key

- Used for scalar input and single-element arrays
- Must be in accepted list or use wildcard C<['*']>
- Stores non-reference data that doesn't fit the hashref pattern

=head2 Parsing Status Messages (Always Provided)

These messages appear in the status message to inform you about structural transformations:

=over 4

=item * **Odd array elements**: C<"Odd number of arguments provided; last element 'X' treated as flag">

=item * **Scalar input**: C<"Plain text argument accepted with key '_': 'preview...'">

=item * **Single array element**: C<"Plain text argument accepted with key '_': 'preview...'">

=back

These messages help you understand when your input format differs from the standard hashref.

=head1 RETURN VALUES

Both L and L return data in a consistent format, regardless
of how the input was provided. The returned result's structure depends on context.

=head2 Return Structure

=head3 Scalar Context

    # Pre-defined filter rules
    my @required = qw(name);
    my @accepted = qw(email);

    # External input data
    my $input = { name => 'Alice', email => '[e-mail]' };

    my $result = filter($input, \@required, \@accepted);
    # Returns: hashref or undef on failure
    if ($result) {
        say $result->{name};
    }

=head3 List Context (Recommended)

    # Filter configuration
    my @required = qw(name email);
    my @accepted = qw(phone);

    # External data source
    my $input = get_external_data();  # e.g., from API, web form, etc.

    my ($data, $message) = filter($input, \@required, \@accepted);
    # Returns: (hashref, status_message) or (undef, error_message)
    if ($data) {
        say $data->{name};
    } else {
        say "Error: $message";
    }

=head2 Success

On success, returns a hashref containing only the fields that passed filtering:

    # Pre-configured filter rules
    my @required_fields = qw(name email);
    my @accepted_fields = qw(phone);
    my @excluded_fields = qw(password spam);

    # External data source (e.g., web form submission)
    my $web_form_data = {
        name     => 'Alice',
        email    => '[e-mail]',
        password => 'secret',
        spam     => 'yes'
    };

    my ($user, $msg) = filter(
        $web_form_data,
        \@required_fields,
        \@accepted_fields,
        \@excluded_fields,
    );

    # $user = { name => 'Alice', email => '[e-mail]' }
    # $msg = "Admitted"

    # Notes:
    # - 'name' and 'email' included (required and present)
    # - 'password' and 'spam' excluded (removed even if present)
    # - 'phone' not in input, so not included
    # - 'spam' not in required/accepted, so ignored

=head2 Failure

On failure (missing required fields), returns C and an error message:

    # Filter rules defined once, reused
    my @required = qw(name email);
    my @accepted = qw(phone);

    # Incomplete external data
    my $incomplete_data = { name => 'Bob' };  # email missing!

    my ($data, $msg) = filter(
        $incomplete_data,
        \@required,
        \@accepted,
    );

    # $data = undef
    # $msg = "Unable to initialize without required arguments: 'email'"

=head2 Status Message Types

The status message provides feedback about the filtering operation:

=over 4

=item * 1. **"Admitted"** - Success, all required fields present

=item * 2. **"Unable to initialize without required arguments: 'field1', 'field2'"** - Failure, missing required fields

=item * 3. **Parsing messages** - Information about input format transformations (always provided)

=item * 4. **Debug warnings** - Information about excluded/unrecognized fields (provided in debug mode only)

=back

=head2 Consistent Output Format

B

    # Filter rules (could be pre-defined constants)
    my @req1 = qw(name);
    my @acc1 = qw();

    # Hashref input → hashref output
    my $hash_input = { name => 'Alice' };
    my $result1 = filter($hash_input, \@req1, \@acc1);
    # → { name => 'Alice' }

    # Arrayref input → hashref output
    my @req2 = qw(name);
    my @acc2 = qw(age);
    my $array_input = ['name', 'Bob', 'age', 30];
    my $result2 = filter($array_input, \@req2, \@acc2);
    # → { name => 'Bob', age => 30 }

    # Scalar input → hashref output with '_' key
    my @req3 = qw();
    my @acc3 = qw(_);
    my $scalar_input = 'text';
    my $result3 = filter($scalar_input, \@req3, \@acc3);
    # → { _ => 'text' }

This consistency makes the filtered data easy to use in downstream code without worrying about the original input format.

=head1 DEBUG MODE

B This feature applies to the L and L only. The L does not support debug mode for maximum speed.

Debug mode provides additional information about field filtering during development:

    my ($filtered, $msg) = filter(
        $input,
        ['name'],
        ['email'],
        ['password'],
        1,  # Enable debug mode
    );

Debug warnings (only shown when debug mode is enabled):

=over 4

=item * Excluded fields that were removed

=item * Unrecognized fields that were ignored

=back

Parsing messages (always shown, regardless of debug mode):

=over 4

=item * Plain text arguments accepted with key '_'

=item * Odd number of array elements converted to flags

=back

Parsing messages inform you about transformations the filter made to your input format.
These are always reported because they affect the structure of the returned data.
Debug warnings help you understand which fields were filtered out during development.

=head1 WILDCARD SUPPORT

=head2 Wildcard for Accepting Fields

    # Accept all fields
    filter($input, [], ['*']);

    # Accept all fields except specific exclusions
    filter($input, [], ['*'], ['password', 'ssn']);

    # Required + all other fields
    filter($input, ['id', 'name'], ['*']);

    # Wildcard can appear anywhere in accepted list
    filter($input, [], ['name', 'email', '*']);  # debugging: add '*' to see everything
    filter($input, [], ['*', 'phone', 'address']);

=head2 Important Notes

=over 4

=item * C<'*'> is B parameter>

=item * In C or C, C<'*'> is treated as a literal field name

=item * Empty C<[]> for accepted means "accept none beyond required"

=item * Multiple wildcards are redundant but harmless

=item * Exclusions are always removed before acceptance is processed

=back

=head2 Debugging Pattern

A common debugging pattern is to add C<'*'> to an existing accepted list:

    # Normal operation
    filter($input, ['id'], ['name', 'email']);

    # Debugging - see all inputs
    filter($input, ['id'], ['name', 'email', '*']);


=head1 EXAMPLES

=head2 Form Field Filtering

    use Params::Filter	qw/filter/;    # import filter() subroutine

    # Define filtering rules (could be from config file)
    my @required = qw(name email);
    my @accepted = qw(phone city state zip);

    # Apply to incoming web form data
    my ($user_data, $status) = filter(
        $form_submission,   # Data from web form
        \@required,
        \@accepted,
    );

    if ($user_data) {
        register_user($user_data);
    } else {
        show_error($status);
    }

=head2 Reusable Filter for Multiple Data Sources

    # Create filter once
    my $user_filter = Params::Filter->new_filter({
        required => ['username', 'email'],
        accepted => ['full_name', 'phone', 'bio'],
        excluded => ['password', 'ssn', 'credit_card'],
    });

    # Apply to multiple incoming datasets
    my ($user1, $msg1) = $user_filter->apply($web_form_data);
    my ($user2, $msg2) = $user_filter->apply($api_request_data);
    my ($user3, $msg3) = $user_filter->apply($csv_import_data);

=head2 Environment-Specific Filtering

    my $filter = Params::Filter->new_filter();

    if ($ENV{APP_MODE} eq 'production') {
        # Strict: only specific fields allowed
        $filter->set_required(['api_key'])
              ->set_accepted(['timeout', 'retries'])
              ->set_excluded(['debug_info', 'verbose']);
    } else {
        # Development: allow everything
        $filter->set_required(['debug_mode'])
              ->accept_all();
    }

    my ($config, $msg) = $filter->apply($incoming_config);

=head2 Security Filtering

    # Remove sensitive fields from user input
    my ($safe_data, $msg) = filter(
        $user_input,
        ['username', 'email'],           # required
        ['full_name', 'phone', 'bio'],    # accepted
        ['password', 'ssn', 'api_key'],   # excluded
    );

    # Result contains only safe fields
    # password, ssn, api_key are removed even if provided

=head2 Dynamic Configuration from File

    # Load filter rules from config file
    my $config = decode_json(`cat filters.json`);

    my $filter = Params::Filter->new_filter()
        ->set_required($config->{user_create}{required})
        ->set_accepted($config->{user_create}{accepted})
        ->set_excluded($config->{user_create}{excluded});

    # Apply to incoming data
    my ($filtered, $msg) = $filter->apply($api_data);

=head2 Data Segregation for Multiple Subsystems

B

An application may need to handle incoming data from varying sources and prepare it for the same downstream processing. Filtering rules can be tailored to assure that only usable data is passed on.

An application may need to split incoming data into subsets for different handlers or storage locations. Multiple filters may be applied to a given input, and each filter extracts only the fields needed for its specific purpose, simplifying next steps and improving security through compartmentalization.

This example demonstrates how Params::Filter can integrate incoming data and segregate the yielded data for multiple outputs.

    # Three different Subscription forms collect overlapping data:

    #  Main subscription signup form collects:
    #   name, email, zip,
    #   user_id, password, credit_card_number, subscription_term

    #  Subscription form with full profile collects:
    #  name, email, address, city, state, zip,
    #  user_id, password, credit_card_number, subscription_term,
    #  phone, occupation, position, education
    #  alt_card_number, billing_address, billing_zip

    #  Promo subscription form collects:
    #  name, email, zip, subscription_term,
    #  user_id, password, credit_card_number, promo_code

    my $data = $webform->input(); # From any of the above

    # Three different uses for the data:
    #  Personal contact info to be stored
    #  Subscription business to be transacted
    #  Authentication credentials to be encrypted and stored

    # Personal data filter - general user info (no sensitive data)
    my $person_filter = Params::Filter->new_filter({
        required => ['name', 'user_id', 'email'],
        accepted => ['address', 'city', 'state', 'zip', 'phone',
                     'occupation', 'position', 'education'],
        excluded => ['password', 'credit_card_number'],
    });

    # Business data filter - subscription and billing info
    my $biz_filter = Params::Filter->new_filter({
        required => ['user_id', 'name', 'subscription_term', 'credit_card_number', 'zip'],
        accepted => ['alt_card_number', 'billing_address', 'billing_zip', 'promo_code'],
        excluded => ['password'],
    });

    # Authentication data filter - only credentials
    my $auth_filter = Params::Filter->new_filter({
        required => ['user_id', 'password'],
        accepted => [],
        excluded => [],
    });

    # Apply all filters to the same web form submission
    my ($person_data,     $pmsg) = $person_filter->apply($data);
    my ($biz_data,        $bmsg) = $biz_filter->apply($data);
    my ($auth_data,       $amsg) = $auth_filter->apply($data);

    # One way to use the filter results:
    # Set the requirement that all filtering requirements must be met
    # with data provided by any of the three webform sources:
    unless ($person_data && $biz_data && $auth_data) {
      return "Unable to add user: " .
        join ' ' => grep { $_ ne 'Admitted' } ($pmsg, $bmsg, $amsg);
    }

    # Route each filtered data subset to appropriate handler
    $self->add_user(         $person_data   );    # User profile
    $self->set_subscription( $biz_data      );    # Billing system
    $self->set_password(     $auth_data     );    # Auth system

B: The original C<$data> is not modified during filtering, so the same data can be safely processed by multiple filters.

=head1 SEE ALSO

=over 4

=item * L - Full-featured parameter validation

=item * L - Data structure validation

=item * L - JSON Schema validation

=back

=head1 AUTHOR

Bruce Van Allen

=head1 LICENSE

This module is licensed under the same terms as Perl itself.
See L.

=head1 COPYRIGHT

Copyright (C) 2026, Bruce Van Allen

=cut

1;