2 package Moose::Util::TypeConstraints;
5 use List::MoreUtils qw( all any );
6 use Scalar::Util qw( blessed reftype );
10 $VERSION = eval $VERSION;
11 our $AUTHORITY = 'cpan:STEVAN';
13 ## --------------------------------------------------------
14 # Prototyped subs must be predeclared because we have a
15 # circular dependency with Moose::Meta::Attribute et. al.
16 # so in case of us being use'd first the predeclaration
17 # ensures the prototypes are in scope when consumers are
26 ## --------------------------------------------------------
28 use Moose::Meta::TypeConstraint;
29 use Moose::Meta::TypeConstraint::Union;
30 use Moose::Meta::TypeConstraint::Parameterized;
31 use Moose::Meta::TypeConstraint::Parameterizable;
32 use Moose::Meta::TypeConstraint::Class;
33 use Moose::Meta::TypeConstraint::Role;
34 use Moose::Meta::TypeConstraint::Enum;
35 use Moose::Meta::TypeConstraint::DuckType;
36 use Moose::Meta::TypeCoercion;
37 use Moose::Meta::TypeCoercion::Union;
38 use Moose::Meta::TypeConstraint::Registry;
39 use Moose::Util::TypeConstraints::OptimizedConstraints;
41 Moose::Exporter->setup_import_methods(
44 type subtype class_type role_type maybe_type duck_type
45 as where message optimize_as
49 register_type_constraint )
54 ## --------------------------------------------------------
55 ## type registry and some useful functions for it
56 ## --------------------------------------------------------
58 my $REGISTRY = Moose::Meta::TypeConstraint::Registry->new;
60 sub get_type_constraint_registry {$REGISTRY}
61 sub list_all_type_constraints { keys %{ $REGISTRY->type_constraints } }
63 sub export_type_constraints_as_functions {
66 foreach my $constraint ( keys %{ $REGISTRY->type_constraints } ) {
67 my $tc = $REGISTRY->get_type_constraint($constraint)
68 ->_compiled_type_constraint;
69 *{"${pkg}::${constraint}"}
70 = sub { $tc->( $_[0] ) ? 1 : undef }; # the undef is for compat
74 sub create_type_constraint_union {
75 my @type_constraint_names;
77 if ( scalar @_ == 1 && _detect_type_constraint_union( $_[0] ) ) {
78 @type_constraint_names = _parse_type_constraint_union( $_[0] );
81 @type_constraint_names = @_;
84 ( scalar @type_constraint_names >= 2 )
85 || __PACKAGE__->_throw_error(
86 "You must pass in at least 2 type names to make a union");
88 my @type_constraints = map {
89 find_or_parse_type_constraint($_)
90 || __PACKAGE__->_throw_error(
91 "Could not locate type constraint ($_) for the union");
92 } @type_constraint_names;
94 return Moose::Meta::TypeConstraint::Union->new(
95 type_constraints => \@type_constraints );
98 sub create_parameterized_type_constraint {
99 my $type_constraint_name = shift;
100 my ( $base_type, $type_parameter )
101 = _parse_parameterized_type_constraint($type_constraint_name);
103 ( defined $base_type && defined $type_parameter )
104 || __PACKAGE__->_throw_error(
105 "Could not parse type name ($type_constraint_name) correctly");
107 if ( $REGISTRY->has_type_constraint($base_type) ) {
108 my $base_type_tc = $REGISTRY->get_type_constraint($base_type);
109 return _create_parameterized_type_constraint(
115 __PACKAGE__->_throw_error(
116 "Could not locate the base type ($base_type)");
120 sub _create_parameterized_type_constraint {
121 my ( $base_type_tc, $type_parameter ) = @_;
122 if ( $base_type_tc->can('parameterize') ) {
123 return $base_type_tc->parameterize($type_parameter);
126 return Moose::Meta::TypeConstraint::Parameterized->new(
127 name => $base_type_tc->name . '[' . $type_parameter . ']',
128 parent => $base_type_tc,
130 find_or_create_isa_type_constraint($type_parameter),
135 #should we also support optimized checks?
136 sub create_class_type_constraint {
137 my ( $class, $options ) = @_;
139 # too early for this check
140 #find_type_constraint("ClassName")->check($class)
141 # || __PACKAGE__->_throw_error("Can't create a class type constraint because '$class' is not a class name");
149 $options{name} ||= "__ANON__";
151 Moose::Meta::TypeConstraint::Class->new(%options);
154 sub create_role_type_constraint {
155 my ( $role, $options ) = @_;
157 # too early for this check
158 #find_type_constraint("ClassName")->check($class)
159 # || __PACKAGE__->_throw_error("Can't create a class type constraint because '$class' is not a class name");
167 $options{name} ||= "__ANON__";
169 Moose::Meta::TypeConstraint::Role->new(%options);
172 sub find_or_create_type_constraint {
173 my ( $type_constraint_name, $options_for_anon_type ) = @_;
176 = find_or_parse_type_constraint($type_constraint_name) ) {
179 elsif ( defined $options_for_anon_type ) {
182 # if there is no $options_for_anon_type
183 # specified, then we assume they don't
184 # want to create one, and return nothing.
186 # otherwise assume that we should create
187 # an ANON type with the $options_for_anon_type
188 # options which can be passed in. It should
189 # be noted that these don't get registered
190 # so we need to return it.
192 return Moose::Meta::TypeConstraint->new(
194 %{$options_for_anon_type}
201 sub find_or_create_isa_type_constraint {
202 my $type_constraint_name = shift;
203 find_or_parse_type_constraint($type_constraint_name)
204 || create_class_type_constraint($type_constraint_name);
207 sub find_or_create_does_type_constraint {
208 my $type_constraint_name = shift;
209 find_or_parse_type_constraint($type_constraint_name)
210 || create_role_type_constraint($type_constraint_name);
213 sub find_or_parse_type_constraint {
214 my $type_constraint_name = normalize_type_constraint_name(shift);
217 if ( $constraint = find_type_constraint($type_constraint_name) ) {
220 elsif ( _detect_type_constraint_union($type_constraint_name) ) {
221 $constraint = create_type_constraint_union($type_constraint_name);
223 elsif ( _detect_parameterized_type_constraint($type_constraint_name) ) {
225 = create_parameterized_type_constraint($type_constraint_name);
231 $REGISTRY->add_type_constraint($constraint);
235 sub normalize_type_constraint_name {
236 my $type_constraint_name = shift;
237 $type_constraint_name =~ s/\s//g;
238 return $type_constraint_name;
244 local $Carp::CarpLevel = $Carp::CarpLevel + 1;
245 Carp::confess($error);
248 ## --------------------------------------------------------
249 ## exported functions ...
250 ## --------------------------------------------------------
252 sub find_type_constraint {
255 if ( blessed $type and $type->isa("Moose::Meta::TypeConstraint") ) {
259 return unless $REGISTRY->has_type_constraint($type);
260 return $REGISTRY->get_type_constraint($type);
264 sub register_type_constraint {
265 my $constraint = shift;
266 __PACKAGE__->_throw_error("can't register an unnamed type constraint")
267 unless defined $constraint->name;
268 $REGISTRY->add_type_constraint($constraint);
276 # back-compat version, called without sugar
277 if ( !any { ( reftype($_) || '' ) eq 'HASH' } @_ ) {
278 return _create_type_constraint( $_[0], undef, $_[1] );
283 my %p = map { %{$_} } @_;
285 return _create_type_constraint(
286 $name, undef, $p{where}, $p{message},
293 # crazy back-compat code for being called without sugar ...
295 # subtype 'Parent', sub { where };
296 if ( scalar @_ == 2 && ( reftype( $_[1] ) || '' ) eq 'CODE' ) {
297 return _create_type_constraint( undef, @_ );
300 # subtype 'Parent', sub { where }, sub { message };
301 # subtype 'Parent', sub { where }, sub { message }, sub { optimized };
302 if ( scalar @_ >= 3 && all { ( reftype($_) || '' ) eq 'CODE' }
304 return _create_type_constraint( undef, @_ );
307 # subtype 'Name', 'Parent', ...
308 if ( scalar @_ >= 2 && all { !ref } @_[ 0, 1 ] ) {
309 return _create_type_constraint(@_);
312 if ( @_ == 1 && !ref $_[0] ) {
313 __PACKAGE__->_throw_error(
314 'A subtype cannot consist solely of a name, it must have a parent'
318 # The blessed check is mostly to accommodate MooseX::Types, which
319 # uses an object which overloads stringification as a type name.
320 my $name = ref $_[0] && !blessed $_[0] ? undef : shift;
322 my %p = map { %{$_} } @_;
324 # subtype Str => where { ... };
325 if ( !exists $p{as} ) {
330 return _create_type_constraint(
331 $name, $p{as}, $p{where}, $p{message},
337 register_type_constraint(
338 create_class_type_constraint(
340 ( defined( $_[1] ) ? $_[1] : () ),
345 sub role_type ($;$) {
346 register_type_constraint(
347 create_role_type_constraint(
349 ( defined( $_[1] ) ? $_[1] : () ),
355 my ($type_parameter) = @_;
357 register_type_constraint(
358 $REGISTRY->get_type_constraint('Maybe')->parameterize($type_parameter)
363 my ( $type_name, @methods ) = @_;
364 if ( ref $type_name eq 'ARRAY' && !@methods ) {
365 @methods = @$type_name;
369 register_type_constraint(
370 create_duck_type_constraint(
378 my ( $type_name, @coercion_map ) = @_;
379 _install_type_coercions( $type_name, \@coercion_map );
382 # The trick of returning @_ lets us avoid having to specify a
383 # prototype. Perl will parse this:
391 # subtype( 'Foo', as( 'Str', where { ... } ) );
393 # If as() returns all it's extra arguments, this just works, and
394 # preserves backwards compatibility.
395 sub as { { as => shift }, @_ }
396 sub where (&) { { where => $_[0] } }
397 sub message (&) { { message => $_[0] } }
398 sub optimize_as (&) { { optimize_as => $_[0] } }
401 sub via (&) { $_[0] }
404 my ( $type_name, @values ) = @_;
407 # if only an array-ref is passed then
408 # you get an anon-enum
410 if ( ref $type_name eq 'ARRAY' && !@values ) {
411 @values = @$type_name;
414 ( scalar @values >= 2 )
415 || __PACKAGE__->_throw_error(
416 "You must have at least two values to enumerate through");
417 my %valid = map { $_ => 1 } @values;
419 register_type_constraint(
420 create_enum_type_constraint(
427 sub create_enum_type_constraint {
428 my ( $type_name, $values ) = @_;
430 Moose::Meta::TypeConstraint::Enum->new(
431 name => $type_name || '__ANON__',
436 sub create_duck_type_constraint {
437 my ( $type_name, $methods ) = @_;
439 Moose::Meta::TypeConstraint::DuckType->new(
440 name => $type_name || '__ANON__',
445 ## --------------------------------------------------------
446 ## desugaring functions ...
447 ## --------------------------------------------------------
449 sub _create_type_constraint ($$$;$$) {
454 my $optimized = shift;
456 my $pkg_defined_in = scalar( caller(1) );
458 if ( defined $name ) {
459 my $type = $REGISTRY->get_type_constraint($name);
461 ( $type->_package_defined_in eq $pkg_defined_in )
463 "The type constraint '$name' has already been created in "
464 . $type->_package_defined_in
465 . " and cannot be created again in "
469 $name =~ /^[\w:\.]+$/
470 or die qq{$name contains invalid characters for a type name.}
471 . qq{ Names can contain alphanumeric character, ":", and "."\n};
476 package_defined_in => $pkg_defined_in,
478 ( $check ? ( constraint => $check ) : () ),
479 ( $message ? ( message => $message ) : () ),
480 ( $optimized ? ( optimized => $optimized ) : () ),
489 : find_or_create_isa_type_constraint($parent)
491 $constraint = $parent->create_child_type(%opts);
494 $constraint = Moose::Meta::TypeConstraint->new(%opts);
497 $REGISTRY->add_type_constraint($constraint)
503 sub _install_type_coercions ($$) {
504 my ( $type_name, $coercion_map ) = @_;
505 my $type = find_type_constraint($type_name);
507 || __PACKAGE__->_throw_error(
508 "Cannot find type '$type_name', perhaps you forgot to load it");
509 if ( $type->has_coercion ) {
510 $type->coercion->add_type_coercions(@$coercion_map);
513 my $type_coercion = Moose::Meta::TypeCoercion->new(
514 type_coercion_map => $coercion_map,
515 type_constraint => $type
517 $type->coercion($type_coercion);
521 ## --------------------------------------------------------
522 ## type notation parsing ...
523 ## --------------------------------------------------------
527 # All I have to say is mugwump++ cause I know
528 # do not even have enough regexp-fu to be able
529 # to have written this (I can only barely
530 # understand it as it is)
535 my $valid_chars = qr{[\w:\.]};
536 my $type_atom = qr{ $valid_chars+ };
540 my $type = qr{ $valid_chars+ (?: \[ \s* (??{$any}) \s* \] )? }x;
541 my $type_capture_parts
542 = qr{ ($valid_chars+) (?: \[ \s* ((??{$any})) \s* \] )? }x;
543 my $type_with_parameter
544 = qr{ $valid_chars+ \[ \s* (??{$any}) \s* \] }x;
546 my $op_union = qr{ \s* \| \s* }x;
547 my $union = qr{ $type (?: $op_union $type )+ }x;
549 $any = qr{ $type | $union }x;
551 sub _parse_parameterized_type_constraint {
552 { no warnings 'void'; $any; } # force capture of interpolated lexical
553 $_[0] =~ m{ $type_capture_parts }x;
557 sub _detect_parameterized_type_constraint {
558 { no warnings 'void'; $any; } # force capture of interpolated lexical
559 $_[0] =~ m{ ^ $type_with_parameter $ }x;
562 sub _parse_type_constraint_union {
563 { no warnings 'void'; $any; } # force capture of interpolated lexical
566 while ( $given =~ m{ \G (?: $op_union )? ($type) }gcx ) {
569 ( pos($given) eq length($given) )
570 || __PACKAGE__->_throw_error( "'$given' didn't parse (parse-pos="
578 sub _detect_type_constraint_union {
579 { no warnings 'void'; $any; } # force capture of interpolated lexical
580 $_[0] =~ m{^ $type $op_union $type ( $op_union .* )? $}x;
584 ## --------------------------------------------------------
585 # define some basic built-in types
586 ## --------------------------------------------------------
588 # By making these classes immutable before creating all the types we
589 # below, we avoid repeatedly calling the slow MOP-based accessors.
591 inline_constructor => 1,
592 constructor_name => "_new",
594 # these are Class::MOP accessors, so they need inlining
595 inline_accessors => 1
596 ) for grep { $_->is_mutable }
597 map { Class::MOP::class_of($_) }
599 Moose::Meta::TypeConstraint
600 Moose::Meta::TypeConstraint::Union
601 Moose::Meta::TypeConstraint::Parameterized
602 Moose::Meta::TypeConstraint::Parameterizable
603 Moose::Meta::TypeConstraint::Class
604 Moose::Meta::TypeConstraint::Role
605 Moose::Meta::TypeConstraint::Enum
606 Moose::Meta::TypeConstraint::DuckType
607 Moose::Meta::TypeConstraint::Registry
610 type 'Any' => where {1}; # meta-type including all
611 subtype 'Item' => as 'Any'; # base-type
613 subtype 'Undef' => as 'Item' => where { !defined($_) };
614 subtype 'Defined' => as 'Item' => where { defined($_) };
616 subtype 'Bool' => as 'Item' =>
617 where { !defined($_) || $_ eq "" || "$_" eq '1' || "$_" eq '0' };
619 subtype 'Value' => as 'Defined' => where { !ref($_) } =>
620 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::Value;
622 subtype 'Ref' => as 'Defined' => where { ref($_) } =>
623 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::Ref;
625 subtype 'Str' => as 'Value' => where {1} =>
626 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::Str;
628 subtype 'Num' => as 'Str' =>
629 where { Scalar::Util::looks_like_number($_) } =>
630 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::Num;
632 subtype 'Int' => as 'Num' => where { "$_" =~ /^-?[0-9]+$/ } =>
633 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::Int;
635 subtype 'ScalarRef' => as 'Ref' => where { ref($_) eq 'SCALAR' } =>
637 \&Moose::Util::TypeConstraints::OptimizedConstraints::ScalarRef;
638 subtype 'CodeRef' => as 'Ref' => where { ref($_) eq 'CODE' } =>
639 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::CodeRef;
640 subtype 'RegexpRef' => as 'Ref' => where { ref($_) eq 'Regexp' } =>
642 \&Moose::Util::TypeConstraints::OptimizedConstraints::RegexpRef;
643 subtype 'GlobRef' => as 'Ref' => where { ref($_) eq 'GLOB' } =>
644 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::GlobRef;
647 # scalar filehandles are GLOB refs,
648 # but a GLOB ref is not always a filehandle
649 subtype 'FileHandle' => as 'GlobRef' => where {
650 Scalar::Util::openhandle($_) || ( blessed($_) && $_->isa("IO::Handle") );
652 \&Moose::Util::TypeConstraints::OptimizedConstraints::FileHandle;
655 # blessed(qr/.../) returns true,.. how odd
656 subtype 'Object' => as 'Ref' =>
657 where { blessed($_) && blessed($_) ne 'Regexp' } =>
658 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::Object;
660 # This type is deprecated.
661 subtype 'Role' => as 'Object' => where { $_->can('does') } =>
662 optimize_as \&Moose::Util::TypeConstraints::OptimizedConstraints::Role;
664 my $_class_name_checker = sub { };
666 subtype 'ClassName' => as 'Str' =>
667 where { Class::MOP::is_class_loaded($_) } => optimize_as
668 \&Moose::Util::TypeConstraints::OptimizedConstraints::ClassName;
670 subtype 'RoleName' => as 'ClassName' => where {
671 (Class::MOP::class_of($_) || return)->isa('Moose::Meta::Role');
673 \&Moose::Util::TypeConstraints::OptimizedConstraints::RoleName;
675 ## --------------------------------------------------------
676 # parameterizable types ...
678 $REGISTRY->add_type_constraint(
679 Moose::Meta::TypeConstraint::Parameterizable->new(
681 package_defined_in => __PACKAGE__,
682 parent => find_type_constraint('Ref'),
683 constraint => sub { ref($_) eq 'ARRAY' },
685 \&Moose::Util::TypeConstraints::OptimizedConstraints::ArrayRef,
686 constraint_generator => sub {
687 my $type_parameter = shift;
688 my $check = $type_parameter->_compiled_type_constraint;
690 foreach my $x (@$_) {
691 ( $check->($x) ) || return;
699 $REGISTRY->add_type_constraint(
700 Moose::Meta::TypeConstraint::Parameterizable->new(
702 package_defined_in => __PACKAGE__,
703 parent => find_type_constraint('Ref'),
704 constraint => sub { ref($_) eq 'HASH' },
706 \&Moose::Util::TypeConstraints::OptimizedConstraints::HashRef,
707 constraint_generator => sub {
708 my $type_parameter = shift;
709 my $check = $type_parameter->_compiled_type_constraint;
711 foreach my $x ( values %$_ ) {
712 ( $check->($x) ) || return;
720 $REGISTRY->add_type_constraint(
721 Moose::Meta::TypeConstraint::Parameterizable->new(
723 package_defined_in => __PACKAGE__,
724 parent => find_type_constraint('Item'),
725 constraint => sub {1},
726 constraint_generator => sub {
727 my $type_parameter = shift;
728 my $check = $type_parameter->_compiled_type_constraint;
730 return 1 if not( defined($_) ) || $check->($_);
737 my @PARAMETERIZABLE_TYPES
738 = map { $REGISTRY->get_type_constraint($_) } qw[ArrayRef HashRef Maybe];
740 sub get_all_parameterizable_types {@PARAMETERIZABLE_TYPES}
742 sub add_parameterizable_type {
745 && $type->isa('Moose::Meta::TypeConstraint::Parameterizable') )
746 || __PACKAGE__->_throw_error(
747 "Type must be a Moose::Meta::TypeConstraint::Parameterizable not $type"
749 push @PARAMETERIZABLE_TYPES => $type;
752 ## --------------------------------------------------------
753 # end of built-in types ...
754 ## --------------------------------------------------------
757 my @BUILTINS = list_all_type_constraints();
758 sub list_all_builtin_type_constraints {@BUILTINS}
765 goto &Moose::throw_error;
776 Moose::Util::TypeConstraints - Type constraint system for Moose
780 use Moose::Util::TypeConstraints;
786 subtype 'NaturalLessThanTen'
789 => message { "This number ($_) is not less than ten!" };
795 enum 'RGBColors' => qw(red green blue);
797 no Moose::Util::TypeConstraints;
801 This module provides Moose with the ability to create custom type
802 constraints to be used in attribute definition.
804 =head2 Important Caveat
806 This is B<NOT> a type system for Perl 5. These are type constraints,
807 and they are not used by Moose unless you tell it to. No type
808 inference is performed, expressions are not typed, etc. etc. etc.
810 A type constraint is at heart a small "check if a value is valid"
811 function. A constraint can be associated with an attribute. This
812 simplifies parameter validation, and makes your code clearer to read,
813 because you can refer to constraints by name.
815 =head2 Slightly Less Important Caveat
817 It is B<always> a good idea to quote your type names.
819 This prevents Perl from trying to execute the call as an indirect
820 object call. This can be an issue when you have a subtype with the
821 same name as a valid class.
825 subtype DateTime => as Object => where { $_->isa('DateTime') };
827 will I<just work>, while this:
830 subtype DateTime => as Object => where { $_->isa('DateTime') };
832 will fail silently and cause many headaches. The simple way to solve
833 this, as well as future proof your subtypes from classes which have
834 yet to have been created, is to quote the type name:
837 subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') };
839 =head2 Default Type Constraints
841 This module also provides a simple hierarchy for Perl 5 types, here is
842 that hierarchy represented visually.
866 B<NOTE:> Any type followed by a type parameter C<[`a]> can be
867 parameterized, this means you can say:
869 ArrayRef[Int] # an array of integers
870 HashRef[CodeRef] # a hash of str to CODE ref mappings
871 Maybe[Str] # value may be a string, may be undefined
873 If Moose finds a name in brackets that it does not recognize as an
874 existing type, it assumes that this is a class name, for example
875 C<ArrayRef[DateTime]>.
877 B<NOTE:> Unless you parameterize a type, then it is invalid to include
878 the square brackets. I.e. C<ArrayRef[]> will be treated as a new type
879 name, I<not> as a parameterization of C<ArrayRef>.
881 B<NOTE:> The C<Undef> type constraint for the most part works
882 correctly now, but edge cases may still exist, please use it
885 B<NOTE:> The C<ClassName> type constraint does a complex package
886 existence check. This means that your class B<must> be loaded for this
887 type constraint to pass.
889 B<NOTE:> The C<RoleName> constraint checks a string is a I<package
890 name> which is a role, like C<'MyApp::Role::Comparable'>.
892 =head2 Type Constraint Naming
894 Type name declared via this module can only contain alphanumeric
895 characters, colons (:), and periods (.).
897 Since the types created by this module are global, it is suggested
898 that you namespace your types just as you would namespace your
899 modules. So instead of creating a I<Color> type for your
900 B<My::Graphics> module, you would call the type
901 I<My::Graphics::Types::Color> instead.
903 =head2 Use with Other Constraint Modules
905 This module can play nicely with other constraint modules with some
906 slight tweaking. The C<where> clause in types is expected to be a
907 C<CODE> reference which checks it's first argument and returns a
908 boolean. Since most constraint modules work in a similar way, it
909 should be simple to adapt them to work with Moose.
911 For instance, this is how you could use it with
912 L<Declare::Constraints::Simple> to declare a completely new type.
914 type 'HashOfArrayOfObjects',
918 -values => IsArrayRef(IsObject)
922 For more examples see the F<t/200_examples/004_example_w_DCS.t> test
925 Here is an example of using L<Test::Deep> and it's non-test
926 related C<eq_deeply> function.
928 type 'ArrayOfHashOfBarsAndRandomNumbers'
931 array_each(subhashof({
933 random_number => ignore()
937 For a complete example see the
938 F<t/200_examples/005_example_w_TestDeep.t> test file.
942 =head2 Type Constraint Constructors
944 The following functions are used to create type constraints. They
945 will also register the type constraints your create in a global
946 registry that is used to look types up by name.
948 See the L<SYNOPSIS> for an example of how to use these.
952 =item B<< subtype 'Name' => as 'Parent' => where { } ... >>
954 This creates a named subtype.
956 If you provide a parent that Moose does not recognize, it will
957 automatically create a new class type constraint for this name.
959 When creating a named type, the C<subtype> function should either be
960 called with the sugar helpers (C<where>, C<message>, etc), or with a
961 name and a hashref of parameters:
963 subtype( 'Foo', { where => ..., message => ... } );
965 The valid hashref keys are C<as> (the parent), C<where>, C<message>,
968 =item B<< subtype as 'Parent' => where { } ... >>
970 This creates an unnamed subtype and will return the type
971 constraint meta-object, which will be an instance of
972 L<Moose::Meta::TypeConstraint>.
974 When creating an anonymous type, the C<subtype> function should either
975 be called with the sugar helpers (C<where>, C<message>, etc), or with
976 just a hashref of parameters:
978 subtype( { where => ..., message => ... } );
980 =item B<class_type ($class, ?$options)>
982 Creates a new subtype of C<Object> with the name C<$class> and the
983 metaclass L<Moose::Meta::TypeConstraint::Class>.
985 =item B<role_type ($role, ?$options)>
987 Creates a C<Role> type constraint with the name C<$role> and the
988 metaclass L<Moose::Meta::TypeConstraint::Role>.
990 =item B<maybe_type ($type)>
992 Creates a type constraint for either C<undef> or something of the
995 =item B<duck_type ($name, @methods)>
997 This will create a subtype of Object and test to make sure the value
998 C<can()> do the methods in C<@methods>.
1000 This is intended as an easy way to accept non-Moose objects that
1001 provide a certain interface. If you're using Moose classes, we
1002 recommend that you use a C<requires>-only Role instead.
1004 =item B<duck_type (\@methods)>
1006 If passed an ARRAY reference instead of the C<$name>, C<@methods>
1007 pair, this will create an unnamed duck type. This can be used in an
1008 attribute definition like so:
1012 isa => duck_type( [qw( get_set )] ),
1015 =item B<enum ($name, @values)>
1017 This will create a basic subtype for a given set of strings.
1018 The resulting constraint will be a subtype of C<Str> and
1019 will match any of the items in C<@values>. It is case sensitive.
1020 See the L<SYNOPSIS> for a simple example.
1022 B<NOTE:> This is not a true proper enum type, it is simply
1023 a convenient constraint builder.
1025 =item B<enum (\@values)>
1027 If passed an ARRAY reference instead of the C<$name>, C<@values> pair,
1028 this will create an unnamed enum. This can then be used in an attribute
1031 has 'sort_order' => (
1033 isa => enum([qw[ ascending descending ]]),
1036 =item B<as 'Parent'>
1038 This is just sugar for the type constraint construction syntax.
1040 It takes a single argument, which is the name of a parent type.
1042 =item B<where { ... }>
1044 This is just sugar for the type constraint construction syntax.
1046 It takes a subroutine reference as an argument. When the type
1047 constraint is tested, the reference is run with the value to be tested
1048 in C<$_>. This reference should return true or false to indicate
1049 whether or not the constraint check passed.
1051 =item B<message { ... }>
1053 This is just sugar for the type constraint construction syntax.
1055 It takes a subroutine reference as an argument. When the type
1056 constraint fails, then the code block is run with the value provided
1057 in C<$_>. This reference should return a string, which will be used in
1058 the text of the exception thrown.
1060 =item B<optimize_as { ... }>
1062 This can be used to define a "hand optimized" version of your
1063 type constraint which can be used to avoid traversing a subtype
1064 constraint hierarchy.
1066 B<NOTE:> You should only use this if you know what you are doing,
1067 all the built in types use this, so your subtypes (assuming they
1068 are shallow) will not likely need to use this.
1070 =item B<type 'Name' => where { } ... >
1072 This creates a base type, which has no parent.
1074 The C<type> function should either be called with the sugar helpers
1075 (C<where>, C<message>, etc), or with a name and a hashref of
1078 type( 'Foo', { where => ..., message => ... } );
1080 The valid hashref keys are C<where>, C<message>, and C<optimize_as>.
1084 =head2 Type Coercion Constructors
1086 You can define coercions for type constraints, which allow you to
1087 automatically transform values to something valid for the type
1088 constraint. If you ask your accessor to coerce, then Moose will run
1089 the type-coercion code first, followed by the type constraint
1090 check. This feature should be used carefully as it is very powerful
1091 and could easily take off a limb if you are not careful.
1093 See the L<SYNOPSIS> for an example of how to use these.
1097 =item B<< coerce 'Name' => from 'OtherName' => via { ... } >>
1099 This defines a coercion from one type to another. The C<Name> argument
1100 is the type you are coercing I<to>.
1102 =item B<from 'OtherName'>
1104 This is just sugar for the type coercion construction syntax.
1106 It takes a single type name (or type object), which is the type being
1109 =item B<via { ... }>
1111 This is just sugar for the type coercion construction syntax.
1113 It takes a subroutine reference. This reference will be called with
1114 the value to be coerced in C<$_>. It is expected to return a new value
1115 of the proper type for the coercion.
1119 =head2 Creating and Finding Type Constraints
1121 These are additional functions for creating and finding type
1122 constraints. Most of these functions are not available for
1123 importing. The ones that are importable as specified.
1127 =item B<find_type_constraint($type_name)>
1129 This function can be used to locate the L<Moose::Meta::TypeConstraint>
1130 object for a named type.
1132 This function is importable.
1134 =item B<register_type_constraint($type_object)>
1136 This function will register a L<Moose::Meta::TypeConstraint> with the
1137 global type registry.
1139 This function is importable.
1141 =item B<normalize_type_constraint_name($type_constraint_name)>
1143 This method takes a type constraint name and returns the normalized
1144 form. This removes any whitespace in the string.
1146 =item B<create_type_constraint_union($pipe_separated_types | @type_constraint_names)>
1148 This can take a union type specification like C<'Int|ArrayRef[Int]'>,
1149 or a list of names. It returns a new
1150 L<Moose::Meta::TypeConstraint::Union> object.
1152 =item B<create_parameterized_type_constraint($type_name)>
1154 Given a C<$type_name> in the form of C<'BaseType[ContainerType]'>,
1155 this will create a new L<Moose::Meta::TypeConstraint::Parameterized>
1156 object. The C<BaseType> must exist already exist as a parameterizable
1159 =item B<create_class_type_constraint($class, $options)>
1161 Given a class name this function will create a new
1162 L<Moose::Meta::TypeConstraint::Class> object for that class name.
1164 The C<$options> is a hash reference that will be passed to the
1165 L<Moose::Meta::TypeConstraint::Class> constructor (as a hash).
1167 =item B<create_role_type_constraint($role, $options)>
1169 Given a role name this function will create a new
1170 L<Moose::Meta::TypeConstraint::Role> object for that role name.
1172 The C<$options> is a hash reference that will be passed to the
1173 L<Moose::Meta::TypeConstraint::Role> constructor (as a hash).
1175 =item B<create_enum_type_constraint($name, $values)>
1177 Given a enum name this function will create a new
1178 L<Moose::Meta::TypeConstraint::Enum> object for that enum name.
1180 =item B<create_duck_type_constraint($name, $methods)>
1182 Given a duck type name this function will create a new
1183 L<Moose::Meta::TypeConstraint::DuckType> object for that enum name.
1185 =item B<find_or_parse_type_constraint($type_name)>
1187 Given a type name, this first attempts to find a matching constraint
1188 in the global registry.
1190 If the type name is a union or parameterized type, it will create a
1191 new object of the appropriate, but if given a "regular" type that does
1192 not yet exist, it simply returns false.
1194 When given a union or parameterized type, the member or base type must
1197 If it creates a new union or parameterized type, it will add it to the
1200 =item B<find_or_create_isa_type_constraint($type_name)>
1202 =item B<find_or_create_does_type_constraint($type_name)>
1204 These functions will first call C<find_or_parse_type_constraint>. If
1205 that function does not return a type, a new anonymous type object will
1208 The C<isa> variant will use C<create_class_type_constraint> and the
1209 C<does> variant will use C<create_role_type_constraint>.
1211 =item B<get_type_constraint_registry>
1213 Returns the L<Moose::Meta::TypeConstraint::Registry> object which
1214 keeps track of all type constraints.
1216 =item B<list_all_type_constraints>
1218 This will return a list of type constraint names in the global
1219 registry. You can then fetch the actual type object using
1220 C<find_type_constraint($type_name)>.
1222 =item B<list_all_builtin_type_constraints>
1224 This will return a list of builtin type constraints, meaning those
1225 which are defined in this module. See the L<Default Type Constraints>
1226 section for a complete list.
1228 =item B<export_type_constraints_as_functions>
1230 This will export all the current type constraints as functions into
1231 the caller's namespace (C<Int()>, C<Str()>, etc). Right now, this is
1232 mostly used for testing, but it might prove useful to others.
1234 =item B<get_all_parameterizable_types>
1236 This returns all the parameterizable types that have been registered,
1237 as a list of type objects.
1239 =item B<add_parameterizable_type($type)>
1241 Adds C<$type> to the list of parameterizable types
1247 All complex software has bugs lurking in it, and this module is no
1248 exception. If you find a bug please either email me, or add the bug
1253 Stevan Little E<lt>stevan@iinteractive.comE<gt>
1255 =head1 COPYRIGHT AND LICENSE
1257 Copyright 2006-2009 by Infinity Interactive, Inc.
1259 L<http://www.iinteractive.com>
1261 This library is free software; you can redistribute it and/or modify
1262 it under the same terms as Perl itself.