A comprehensive, flexible Perl library for validating and processing input data, particularly useful for web applications and APIs.
- Schema-based validation - Define reusable validation schemas with comprehensive rules
- Nested data structures - Full support for validating arrays, hashes, and deeply nested combinations
- Unknown parameter handling - Control how unknown parameters are handled (ignore, remove, or reject)
- Schema inheritance - Create new schemas by extending existing ones
- Custom validators - Easy integration of custom validation logic
- Pre/post processing - Transform data before validation and after successful validation
- Rich error reporting - Detailed error information with dot-notation paths for nested structures
cpanm Brannigan
git clone https://github.com/ido50/Brannigan.git
cd Brannigan
perl Makefile.PL
make
make test
make install
use Brannigan;
# Create validator
my $b = Brannigan->new({ handle_unknown => 'remove' });
# Define a schema
my $user_schema = {
params => {
name => {
required => 1,
length_between => [2, 50],
preprocess => sub { s/^\s+|\s+$//gr }, # trim whitespace
},
email => {
required => 1,
matches => qr/^[^@]+@[^@]+\.[^@]+$/,
},
age => {
required => 0,
integer => 1,
value_between => [13, 120],
default => 18,
},
preferences => {
hash => 1,
keys => {
newsletter => { default => 0 },
theme => { one_of => ['light', 'dark'], default => 'light' },
},
},
},
};
# Register the schema
$b->register_schema('user', $user_schema);
# Validate input data
my %input = (
name => ' John Doe ',
email => 'john@example.com',
preferences => { newsletter => 1 },
unknown_field => 'will be removed',
);
my $rejects = $b->process('user', \%input);
if ($rejects) {
# Validation failed
print "Validation errors:\n";
for my $field (keys %$rejects) {
print " $field: " . join(', ', keys %{$rejects->{$field}}) . "\n";
}
} else {
# Validation passed - input has been processed in-place
print "User data: " . Dumper(\%input);
# Output: name is trimmed, age defaults to 18, theme defaults to 'light'
}
Brannigan processes input through a 5-stage pipeline:
- Schema Preparation - Load and merge inherited schemas
- Preprocessing - Apply default values and preprocess functions
- Validation - Check all validation rules
- Postprocessing - Apply postprocess functions if validation passed
- Result - Return
undef
(success) or rejects hash-ref (failure)
Control how unknown parameters are handled:
my $b = Brannigan->new({ handle_unknown => 'ignore' }); # Keep unknown params (default)
my $b = Brannigan->new({ handle_unknown => 'remove' }); # Delete unknown params
my $b = Brannigan->new({ handle_unknown => 'reject' }); # Fail validation on unknown params
Schemas can inherit from other schemas:
my $base_schema = {
params => {
name => { required => 1, length_between => [2, 50] },
email => { required => 1 },
},
};
my $user_update_schema = {
inherits_from => 'base_user',
params => {
name => { required => 0 }, # Override: name no longer required for updates
last_login => { required => 0 }, # Add new field
},
};
$b->register_schema('base_user', $base_schema);
$b->register_schema('user_update', $user_update_schema);
Run perldoc Brannigan
after installation for the complete documentation.
# Run all tests
prove -l t/
# Run specific test files
perl -Ilib t/01-validations.t
perl -Ilib t/07-complex-structures.t
perl Makefile.PL
make dist
Use the included release script:
./release.sh
This will:
- Run all tests
- Create the distribution tarball
- Provide instructions for CPAN upload
For CPAN upload, you'll need:
- A PAUSE account (https://pause.perl.org/)
- CPAN::Uploader installed (
cpanm CPAN::Uploader
) - PAUSE credentials in
~/.pause
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Ensure all tests pass:
prove -l t/
- Submit a pull request
Licensed under the Apache License, Version 2.0. See LICENSE file for details.