package Mouse::Util::TypeConstraints;
use strict;
use warnings;
+use base 'Exporter';
use Carp ();
use Scalar::Util qw/blessed looks_like_number openhandle/;
+use Mouse::Util;
+use Mouse::Meta::TypeConstraint;
+
+our @EXPORT = qw(
+ as where message from via type subtype coerce class_type role_type enum
+ find_type_constraint
+);
+
my %TYPE;
+my %TYPE_SOURCE;
my %COERCE;
my %COERCE_KEYS;
-#find_type_constraint register_type_constraint
-sub import {
- my $class = shift;
- my %args = @_;
- my $caller = $args{callee} || caller(0);
-
- no strict 'refs';
- *{"$caller\::as"} = \&_as;
- *{"$caller\::where"} = \&_where;
- *{"$caller\::message"} = \&_message;
- *{"$caller\::from"} = \&_from;
- *{"$caller\::via"} = \&_via;
- *{"$caller\::type"} = \&_type;
- *{"$caller\::subtype"} = \&_subtype;
- *{"$caller\::coerce"} = \&_coerce;
- *{"$caller\::class_type"} = \&_class_type;
- *{"$caller\::role_type"} = \&_role_type;
+sub as ($) {
+ return(as => $_[0]);
}
-
-
-sub _as ($) {
- as => $_[0]
+sub where (&) {
+ return(where => $_[0])
}
-sub _where (&) {
- where => $_[0]
-}
-sub _message ($) {
- message => $_[0]
+sub message (&) {
+ return(message => $_[0])
}
-sub _from { @_ }
-sub _via (&) {
- $_[0]
-}
+sub from { @_ }
+sub via (&) { $_[0] }
-my $optimized_constraints;
-my $optimized_constraints_base;
-{
+BEGIN {
no warnings 'uninitialized';
%TYPE = (
Any => sub { 1 },
Item => sub { 1 },
Bool => sub {
- !defined($_) || $_ eq "" || "$_" eq '1' || "$_" eq '0'
+ !defined($_[0]) || $_[0] eq "" || "$_[0]" eq '1' || "$_[0]" eq '0'
},
- Undef => sub { !defined($_) },
- Defined => sub { defined($_) },
- Value => sub { defined($_) && !ref($_) },
- Num => sub { !ref($_) && looks_like_number($_) },
- Int => sub { defined($_) && !ref($_) && /^-?[0-9]+$/ },
- Str => sub { defined($_) && !ref($_) },
- ClassName => sub { Mouse::is_class_loaded($_) },
- Ref => sub { ref($_) },
-
- ScalarRef => sub { ref($_) eq 'SCALAR' },
- ArrayRef => sub { ref($_) eq 'ARRAY' },
- HashRef => sub { ref($_) eq 'HASH' },
- CodeRef => sub { ref($_) eq 'CODE' },
- RegexpRef => sub { ref($_) eq 'Regexp' },
- GlobRef => sub { ref($_) eq 'GLOB' },
+ Undef => sub { !defined($_[0]) },
+ Defined => sub { defined($_[0]) },
+ Value => sub { defined($_[0]) && !ref($_[0]) },
+ Num => sub { !ref($_[0]) && looks_like_number($_[0]) },
+ Int => sub { defined($_[0]) && !ref($_[0]) && $_[0] =~ /^-?[0-9]+$/ },
+ Str => sub { defined($_[0]) && !ref($_[0]) },
+ ClassName => sub { Mouse::is_class_loaded($_[0]) },
+ Ref => sub { ref($_[0]) },
+
+ ScalarRef => sub { ref($_[0]) eq 'SCALAR' },
+ ArrayRef => sub { ref($_[0]) eq 'ARRAY' },
+ HashRef => sub { ref($_[0]) eq 'HASH' },
+ CodeRef => sub { ref($_[0]) eq 'CODE' },
+ RegexpRef => sub { ref($_[0]) eq 'Regexp' },
+ GlobRef => sub { ref($_[0]) eq 'GLOB' },
FileHandle => sub {
- ref($_) eq 'GLOB'
- && openhandle($_)
+ ref($_[0]) eq 'GLOB' && openhandle($_[0])
or
- blessed($_)
- && $_->isa("IO::Handle")
- },
+ blessed($_[0]) && $_[0]->isa("IO::Handle")
+ },
- Object => sub { blessed($_) && blessed($_) ne 'Regexp' },
+ Object => sub { blessed($_[0]) && blessed($_[0]) ne 'Regexp' },
);
+ while (my ($name, $code) = each %TYPE) {
+ $TYPE{$name} = Mouse::Meta::TypeConstraint->new( _compiled_type_constraint => $code, name => $name );
+ }
sub optimized_constraints { \%TYPE }
my @TYPE_KEYS = keys %TYPE;
sub list_all_builtin_type_constraints { @TYPE_KEYS }
+
+ @TYPE_SOURCE{@TYPE_KEYS} = (__PACKAGE__) x @TYPE_KEYS;
}
-sub _type {
+sub type {
my $pkg = caller(0);
my($name, %conf) = @_;
- if (my $type = $TYPE{$name}) {
- Carp::croak "The type constraint '$name' has already been created, cannot be created again in $pkg";
+
+ if ($TYPE{$name} && $TYPE_SOURCE{$name} ne $pkg) {
+ Carp::croak "The type constraint '$name' has already been created in $TYPE_SOURCE{$name} and cannot be created again in $pkg";
+ }
+ my $constraint = $conf{where} || do {
+ my $as = delete $conf{as} || 'Any';
+ if (! exists $TYPE{$as}) {
+ $TYPE{$as} = _build_type_constraint($as);
+ }
+ $TYPE{$as};
};
- my $stuff = $conf{where} || do { $TYPE{delete $conf{as} || 'Any' } };
- $TYPE{$name} = $stuff;
+
+ $TYPE_SOURCE{$name} = $pkg;
+ $TYPE{$name} = Mouse::Meta::TypeConstraint->new(
+ name => $name,
+ _compiled_type_constraint => sub {
+ local $_ = $_[0];
+ if (ref $constraint eq 'CODE') {
+ $constraint->($_[0])
+ } else {
+ $constraint->check($_[0])
+ }
+ }
+ );
}
-sub _subtype {
- my $pkg = caller(0);
- my($name, %conf) = @_;
- if (my $type = $TYPE{$name}) {
- Carp::croak "The type constraint '$name' has already been created, cannot be created again in $pkg";
- };
- my $stuff = $conf{where} || do { $TYPE{delete $conf{as} || 'Any' } };
- my $as = $conf{as} || '';
- if ($as = $TYPE{$as}) {
- $TYPE{$name} = sub { $as->($_) && $stuff->($_) };
- } else {
- $TYPE{$name} = $stuff;
+sub subtype {
+ my $pkg = caller;
+
+ my $name;
+ my %conf;
+
+ if(@_ % 2){ # odd number of arguments
+ $name = shift;
+ %conf = @_;
+ }
+ else{
+ %conf = @_;
+ $name = $conf{name} || '__ANON__';
}
+
+ if ($TYPE{$name} && $TYPE_SOURCE{$name} ne $pkg) {
+ Carp::croak "The type constraint '$name' has already been created in $TYPE_SOURCE{$name} and cannot be created again in $pkg";
+ };
+ my $constraint = delete $conf{where};
+ my $as_constraint = find_or_create_isa_type_constraint(delete $conf{as} || 'Any');
+
+ $TYPE_SOURCE{$name} = $pkg;
+ $TYPE{$name} = Mouse::Meta::TypeConstraint->new(
+ name => $name,
+ _compiled_type_constraint => (
+ $constraint ?
+ sub {
+ local $_ = $_[0];
+ $as_constraint->check($_[0]) && $constraint->($_[0])
+ } :
+ sub {
+ local $_ = $_[0];
+ $as_constraint->check($_[0]);
+ }
+ ),
+ %conf
+ );
+
+ return $name;
}
-sub _coerce {
- my($name, %conf) = @_;
+sub coerce {
+ my $name = shift;
Carp::croak "Cannot find type '$name', perhaps you forgot to load it."
unless $TYPE{$name};
$COERCE{$name} = {};
$COERCE_KEYS{$name} = [];
}
- while (my($type, $code) = each %conf) {
+
+ while (my($type, $code) = splice @_, 0, 2) {
Carp::croak "A coercion action already exists for '$type'"
if $COERCE{$name}->{$type};
- Carp::croak "Could not find the type constraint ($type) to coerce from"
- unless $TYPE{$type};
+ if (! $TYPE{$type}) {
+ # looks parameterized
+ if ($type =~ /^[^\[]+\[.+\]$/) {
+ $TYPE{$type} = _build_type_constraint($type);
+ } else {
+ Carp::croak "Could not find the type constraint ($type) to coerce from"
+ }
+ }
push @{ $COERCE_KEYS{$name} }, $type;
$COERCE{$name}->{$type} = $code;
}
+ return;
}
-sub _class_type {
- my $pkg = caller(0);
+sub class_type {
my($name, $conf) = @_;
- my $class = $conf->{class};
- Mouse::load_class($class);
- _subtype(
- $name => where => sub { $_->isa($class) }
- );
+ if ($conf && $conf->{class}) {
+ # No, you're using this wrong
+ warn "class_type() should be class_type(ClassName). Perhaps you're looking for subtype $name => as '$conf->{class}'?";
+ subtype($name, as => $conf->{class});
+ } else {
+ subtype(
+ $name => where => sub { $_->isa($name) }
+ );
+ }
}
-sub _role_type {
+sub role_type {
my($name, $conf) = @_;
my $role = $conf->{role};
- _subtype(
+ subtype(
$name => where => sub {
return unless defined $_ && ref($_) && $_->isa('Mouse::Object');
$_->meta->does_role($role);
);
}
+# this is an original method for Mouse
sub typecast_constraints {
- my($class, $pkg, $type_constraint, $types, $value) = @_;
+ my($class, $pkg, $types, $value) = @_;
+ Carp::croak("wrong arguments count") unless @_==4;
local $_;
- for my $type (ref($types) eq 'ARRAY' ? @{ $types } : ( $types )) {
+ for my $type ( split /\|/, $types ) {
next unless $COERCE{$type};
for my $coerce_type (@{ $COERCE_KEYS{$type}}) {
$_ = $value;
- next unless $TYPE{$coerce_type}->();
+ next unless $TYPE{$coerce_type}->check($value);
$_ = $value;
- $_ = $COERCE{$type}->{$coerce_type}->();
- return $_ if $type_constraint->();
+ $_ = $COERCE{$type}->{$coerce_type}->($value);
+ return $_ if $types->check($_);
}
}
return $value;
}
+my $serial_enum = 0;
+sub enum {
+ # enum ['small', 'medium', 'large']
+ if (ref($_[0]) eq 'ARRAY') {
+ my @elements = @{ shift @_ };
+
+ my $name = 'Mouse::Util::TypeConstaints::Enum::Serial::'
+ . ++$serial_enum;
+ enum($name, @elements);
+ return $name;
+ }
+
+ # enum size => 'small', 'medium', 'large'
+ my $name = shift;
+ my %is_valid = map { $_ => 1 } @_;
+
+ subtype(
+ $name => where => sub { $is_valid{$_} }
+ );
+}
+
+sub _build_type_constraint {
+
+ my $spec = shift;
+ my $code;
+ $spec =~ s/\s+//g;
+ if ($spec =~ /^([^\[]+)\[(.+)\]$/) {
+ # parameterized
+ my $constraint = $1;
+ my $param = $2;
+ my $parent;
+ if ($constraint eq 'Maybe') {
+ $parent = _build_type_constraint('Undef');
+ } else {
+ $parent = _build_type_constraint($constraint);
+ }
+ my $child = _build_type_constraint($param);
+ if ($constraint eq 'ArrayRef') {
+ my $code_str =
+ "#line " . __LINE__ . ' "' . __FILE__ . "\"\n" .
+ "sub {\n" .
+ " if (\$parent->check(\$_[0])) {\n" .
+ " foreach my \$e (\@{\$_[0]}) {\n" .
+ " return () unless \$child->check(\$e);\n" .
+ " }\n" .
+ " return 1;\n" .
+ " }\n" .
+ " return ();\n" .
+ "};\n"
+ ;
+ $code = eval $code_str or Carp::confess("Failed to generate inline type constraint: $@");
+ } elsif ($constraint eq 'HashRef') {
+ my $code_str =
+ "#line " . __LINE__ . ' "' . __FILE__ . "\"\n" .
+ "sub {\n" .
+ " if (\$parent->check(\$_[0])) {\n" .
+ " foreach my \$e (values \%{\$_[0]}) {\n" .
+ " return () unless \$child->check(\$e);\n" .
+ " }\n" .
+ " return 1;\n" .
+ " }\n" .
+ " return ();\n" .
+ "};\n"
+ ;
+ $code = eval $code_str or Carp::confess($@);
+ } elsif ($constraint eq 'Maybe') {
+ my $code_str =
+ "#line " . __LINE__ . ' "' . __FILE__ . "\"\n" .
+ "sub {\n" .
+ " return \$child->check(\$_[0]) || \$parent->check(\$_[0]);\n" .
+ "};\n"
+ ;
+ $code = eval $code_str or Carp::confess($@);
+ } else {
+ Carp::confess("Support for parameterized types other than Maybe, ArrayRef or HashRef is not implemented yet");
+ }
+ $TYPE{$spec} = Mouse::Meta::TypeConstraint->new( _compiled_type_constraint => $code, name => $spec );
+ } else {
+ $code = $TYPE{ $spec };
+ if (! $code) {
+ # is $spec a known role? If so, constrain with 'does' instead of 'isa'
+ require Mouse::Meta::Role;
+ my $check = Mouse::Meta::Role->_metaclass_cache($spec)?
+ 'does' : 'isa';
+ my $code_str =
+ "#line " . __LINE__ . ' "' . __FILE__ . "\"\n" .
+ "sub {\n" .
+ " Scalar::Util::blessed(\$_[0]) && \$_[0]->$check('$spec');\n" .
+ "}"
+ ;
+ $code = eval $code_str or Carp::confess($@);
+ $TYPE{$spec} = Mouse::Meta::TypeConstraint->new( _compiled_type_constraint => $code, name => $spec );
+ }
+ }
+ return Mouse::Meta::TypeConstraint->new( _compiled_type_constraint => $code, name => $spec );
+}
+
+sub find_type_constraint {
+ my $type_constraint = shift;
+ return $TYPE{$type_constraint};
+}
+
+sub find_or_create_isa_type_constraint {
+ my $type_constraint = shift;
+
+ Carp::confess("Got isa => type_constraints, but Mouse does not yet support parameterized types for containers other than ArrayRef and HashRef and Maybe (rt.cpan.org #39795)")
+ if $type_constraint =~ /\A ( [^\[]+ ) \[\.+\] \z/xms &&
+ $1 ne 'ArrayRef' &&
+ $1 ne 'HashRef' &&
+ $1 ne 'Maybe'
+ ;
+
+ my $code;
+
+ $type_constraint =~ s/\s+//g;
+
+ $code = $TYPE{$type_constraint};
+ if (! $code) {
+ my @type_constraints = split /\|/, $type_constraint;
+ if (@type_constraints == 1) {
+ $code = $TYPE{$type_constraints[0]} ||
+ _build_type_constraint($type_constraints[0]);
+ } else {
+ my @code_list = map {
+ $TYPE{$_} || _build_type_constraint($_)
+ } @type_constraints;
+ $code = Mouse::Meta::TypeConstraint->new(
+ _compiled_type_constraint => sub {
+ my $i = 0;
+ for my $code (@code_list) {
+ return 1 if $code->check($_[0]);
+ }
+ return 0;
+ },
+ name => $type_constraint,
+ );
+ }
+ }
+ return $code;
+}
+
1;
__END__
=head1 NAME
-Mouse::Util::TypeConstraints - simple type constraints
+Mouse::Util::TypeConstraints - Type constraint system for Mouse
+
+=head2 SYNOPSIS
+
+ use Mouse::Util::TypeConstraints;
+
+ subtype 'Natural'
+ => as 'Int'
+ => where { $_ > 0 };
+
+ subtype 'NaturalLessThanTen'
+ => as 'Natural'
+ => where { $_ < 10 }
+ => message { "This number ($_) is not less than ten!" };
+
+ coerce 'Num'
+ => from 'Str'
+ => via { 0+$_ };
+
+ enum 'RGBColors' => qw(red green blue);
+
+ no Mouse::Util::TypeConstraints;
+
+=head1 DESCRIPTION
+
+This module provides Mouse with the ability to create custom type
+constraints to be used in attribute definition.
+
+=head2 Important Caveat
+
+This is B<NOT> a type system for Perl 5. These are type constraints,
+and they are not used by Mouse unless you tell it to. No type
+inference is performed, expressions are not typed, etc. etc. etc.
+
+A type constraint is at heart a small "check if a value is valid"
+function. A constraint can be associated with an attribute. This
+simplifies parameter validation, and makes your code clearer to read,
+because you can refer to constraints by name.
+
+=head2 Slightly Less Important Caveat
+
+It is B<always> a good idea to quote your type names.
+
+This prevents Perl from trying to execute the call as an indirect
+object call. This can be an issue when you have a subtype with the
+same name as a valid class.
+
+For instance:
+
+ subtype DateTime => as Object => where { $_->isa('DateTime') };
+
+will I<just work>, while this:
+
+ use DateTime;
+ subtype DateTime => as Object => where { $_->isa('DateTime') };
+
+will fail silently and cause many headaches. The simple way to solve
+this, as well as future proof your subtypes from classes which have
+yet to have been created, is to quote the type name:
+
+ use DateTime;
+ subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') };
+
+=head2 Default Type Constraints
+
+This module also provides a simple hierarchy for Perl 5 types, here is
+that hierarchy represented visually.
+
+ Any
+ Item
+ Bool
+ Maybe[`a]
+ Undef
+ Defined
+ Value
+ Num
+ Int
+ Str
+ ClassName
+ RoleName
+ Ref
+ ScalarRef
+ ArrayRef[`a]
+ HashRef[`a]
+ CodeRef
+ RegexpRef
+ GlobRef
+ FileHandle
+ Object
+ Role
+
+B<NOTE:> Any type followed by a type parameter C<[`a]> can be
+parameterized, this means you can say:
+
+ ArrayRef[Int] # an array of integers
+ HashRef[CodeRef] # a hash of str to CODE ref mappings
+ Maybe[Str] # value may be a string, may be undefined
+
+If Mouse finds a name in brackets that it does not recognize as an
+existing type, it assumes that this is a class name, for example
+C<ArrayRef[DateTime]>.
+
+B<NOTE:> Unless you parameterize a type, then it is invalid to include
+the square brackets. I.e. C<ArrayRef[]> will be treated as a new type
+name, I<not> as a parameterization of C<ArrayRef>.
+
+B<NOTE:> The C<Undef> type constraint for the most part works
+correctly now, but edge cases may still exist, please use it
+sparingly.
+
+B<NOTE:> The C<ClassName> type constraint does a complex package
+existence check. This means that your class B<must> be loaded for this
+type constraint to pass.
+
+B<NOTE:> The C<RoleName> constraint checks a string is a I<package
+name> which is a role, like C<'MyApp::Role::Comparable'>. The C<Role>
+constraint checks that an I<object does> the named role.
+
+=head2 Type Constraint Naming
+
+Type name declared via this module can only contain alphanumeric
+characters, colons (:), and periods (.).
+
+Since the types created by this module are global, it is suggested
+that you namespace your types just as you would namespace your
+modules. So instead of creating a I<Color> type for your
+B<My::Graphics> module, you would call the type
+I<My::Graphics::Types::Color> instead.
+
+=head2 Use with Other Constraint Modules
+
+This module can play nicely with other constraint modules with some
+slight tweaking. The C<where> clause in types is expected to be a
+C<CODE> reference which checks it's first argument and returns a
+boolean. Since most constraint modules work in a similar way, it
+should be simple to adapt them to work with Mouse.
+
+For instance, this is how you could use it with
+L<Declare::Constraints::Simple> to declare a completely new type.
+
+ type 'HashOfArrayOfObjects',
+ {
+ where => IsHashRef(
+ -keys => HasLength,
+ -values => IsArrayRef(IsObject)
+ )
+ };
+
+Here is an example of using L<Test::Deep> and it's non-test
+related C<eq_deeply> function.
+
+ type 'ArrayOfHashOfBarsAndRandomNumbers'
+ => where {
+ eq_deeply($_,
+ array_each(subhashof({
+ bar => isa('Bar'),
+ random_number => ignore()
+ })))
+ };
=head1 METHODS
Returns the simple type constraints that Mouse understands.
+=head1 FUNCTIONS
+
+=over 4
+
+=item B<subtype 'Name' => as 'Parent' => where { } ...>
+
+=item B<subtype as 'Parent' => where { } ...>
+
+=item B<class_type ($class, ?$options)>
+
+=item B<role_type ($role, ?$options)>
+
+=item B<enum (\@values)>
+
+=back
+
+=head1 THANKS
+
+Much of this documentation was taken from L<Moose::Util::TypeConstraints>
+
=cut
projects / gitmo/Mouse.git / blobdiff