NAME
Basic::Types::XS - Fast but limited type constraints
VERSION
Version 0.11
SYNOPSIS
package Test;
use Moo;
use Basic::Types::XS qw/Str Num Int ArrayRef HashRef/;
has string => (
is => 'ro',
isa => Str,
required => 1,
);
has num => (
is => 'ro',
isa => Num,
);
has int => (
is => 'rw',
isa => Int,
);
has array => (
is => 'ro',
isa => ArrayRef,
default => sub { return [] },
);
has hash => (
is => 'ro',
isa => HashRef,
default => sub { return {} },
);
1;EXPORT
This module exports type constraints that can be used to validate and coerce values in your Perl code. You can import the types you need by specifying them in the use statement:
use Basic::Types::XS qw/Str Num Int ArrayRef HashRef/;Type Options
Each type constraint can be used directly as a function to validate values, or you can create a type constraint with options. For example, to create a type constraint for a string with custom options:
use Basic::Types::XS qw/Str/;
my $Str = Str(
default => sub { return "default value" },
coerce => sub {
my $value = shift;
return join ",", @{$value} if ref $value eq "ARRAY";
return $value;
},
message => "This is a custom error message",
);
$Str->("abc"); # Validates and returns "abc"
$Str->(undef); # Returns "default value"
$Str->([qw/a b c/]); # Coerces array to string "a,b,c"
$Str->({}); # Throws an error with custom messagedefault- A coderef to provide a default value if the input is undefinedcoerce- A coderef to coerce the input value before validationmessage- A custom error message stringvalidate- A value that may be used by the constraint to validate the input
Any
Absolutely any value passes this type constraint (even undef).
Any->("abc");Defined
Only undef fails this type constraint.
Defined->("abc");Bool
Values that are reasonable booleans. Accepts 1, 0, "", undef, \1, \0, \"", \undef
Bool->(1);Str
Values that are valid strings, this includes numbers.
Str->("abc");StrMatch
Values that are valid strings and match a regex pattern.
StrMatch(validate => qr/^[a-z]+$/)->("abc");Num
Values that are valid numbers, this incldues floats/doubles.
Num->(123.456);Int
Values that are valide integers.
Int->(123);Ref
Values that contain any reference
Ref->({ ... });ScalarRef
Values that contain a scalar reference.
ScalarRef->(\"abc");ArrayRef
Values that contain array references.
ArrayRef->([qw/a b c/]);HashRef
Values that contain hash references
HashRef->({ a => 1, b => 2, c => 3 });CodeRef
Values that contain code references
CodeRef->(sub { return 'abc' });RegexpRef
Value that contain regexp references
RegexpRef->(qr/abc/);GlobRef
Value that contain glob references
my $open, '>', 'abc.txt';
GlobRef->($open);Object
Values that contain blessed references (objects).
Object->(My::Class->new());ClassName
Values that contain valid class names (strings).
ClassName->("My::Class");Enum
Values that contain a value found in the Enum array reference.
Enum(validate => [qw/yes no/])->("yes");METHODS
message
Sets a custom error message for the type constraint. This message will be used when validation fails.
Str->message("This is a custom error message");default
Sets a default value for the type constraint. This value will be returned when the input is undefined.
Str->default(sub { return "default value" });coerce
Sets a coercion function for the type constraint. This function will be used to convert input values before validation.
Str->coerce(sub {
my $value = shift;
return join ",", @{$value} if ref $value eq "ARRAY";
return $value;
});validate
This method maybe used to set the constaint validation option. What you set here will depend on the type you are using. For example for the StrMatch type you would set a regex to match against.
StrMatch->validate(qr/^[a-z]+$/);constraint
Returns the validation function for the type constraint. This function can be used to validate values against the type constraint.
Str->validate->("abc");BENCHMARK
The following benchmark is between Types::Standard with Type::Tiny::XS installed and Basic::Types::XS.
use Benchmark qw(:all :hireswallclock);
use Types::Standard;
use Basic::Types::XS;
my $r = timethese(1000000, {
'Basic::Types::XS' => sub {
my $Str = Basic::Types::XS::Definition::Str->('123');
my $Num = Basic::Types::XS::Definition::Num->(123);
my $Int = Basic::Types::XS::Definition::Int->(123);
my $Array = Basic::Types::XS::Definition::ArrayRef->([qw/1 2 3/]);
my $Hash = Basic::Types::XS::Definition::HashRef->({ a => 1, });
my $Code = Basic::Types::XS::Definition::CodeRef->(sub { return 1 });
},
'Types::Standard' => sub {
my $Str = Types::Standard::Str->('123');
my $Num = Types::Standard::Num->(123);
my $Int = Types::Standard::Int->(123);
my $Array = Types::Standard::ArrayRef->([qw/1 2 3/]);
my $Hash = Types::Standard::HashRef->({ a => 1, });
my $Code = Types::Standard::CodeRef->(sub { return 1 });
},
});
Benchmark: timing 1000000 iterations of Basic::Types::XS, Types::Standard...
Basic::Types::XS: 2.10176 wallclock secs ( 1.93 usr + 0.17 sys = 2.10 CPU) @ 476190.48/s (n=1000000)
Types::Standard: 3.15881 wallclock secs ( 3.15 usr + 0.00 sys = 3.15 CPU) @ 317460.32/s (n=1000000)
Rate Types::Standard Basic::Types::XS
Types::Standard 317460/s -- -33%
Basic::Types::XS 476190/s 50% --AUTHOR
LNATION, <email at lnation.org>
BUGS
Please report any bugs or feature requests to bug-basic-types-xs at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Basic-Types-XS. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Basic::Types::XSYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
Search CPAN
ACKNOWLEDGEMENTS
LICENSE AND COPYRIGHT
This software is Copyright (c) 2025 by LNATION.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)