2 package Moose::Util::TypeConstraints;
5 use List::MoreUtils qw( all any );
6 use Scalar::Util qw( blessed reftype );
9 ## --------------------------------------------------------
10 # Prototyped subs must be predeclared because we have a
11 # circular dependency with Moose::Meta::Attribute et. al.
12 # so in case of us being use'd first the predeclaration
13 # ensures the prototypes are in scope when consumers are
23 ## --------------------------------------------------------
25 use Moose::Deprecated;
26 use Moose::Meta::TypeConstraint;
27 use Moose::Meta::TypeConstraint::Union;
28 use Moose::Meta::TypeConstraint::Parameterized;
29 use Moose::Meta::TypeConstraint::Parameterizable;
30 use Moose::Meta::TypeConstraint::Class;
31 use Moose::Meta::TypeConstraint::Role;
32 use Moose::Meta::TypeConstraint::Enum;
33 use Moose::Meta::TypeConstraint::DuckType;
34 use Moose::Meta::TypeCoercion;
35 use Moose::Meta::TypeCoercion::Union;
36 use Moose::Meta::TypeConstraint::Registry;
38 Moose::Exporter->setup_import_methods(
41 type subtype class_type role_type maybe_type duck_type
42 as where message optimize_as inline_as
46 register_type_constraint
51 ## --------------------------------------------------------
52 ## type registry and some useful functions for it
53 ## --------------------------------------------------------
55 my $REGISTRY = Moose::Meta::TypeConstraint::Registry->new;
57 sub get_type_constraint_registry {$REGISTRY}
58 sub list_all_type_constraints { keys %{ $REGISTRY->type_constraints } }
60 sub export_type_constraints_as_functions {
63 foreach my $constraint ( keys %{ $REGISTRY->type_constraints } ) {
64 my $tc = $REGISTRY->get_type_constraint($constraint)
65 ->_compiled_type_constraint;
66 *{"${pkg}::${constraint}"}
67 = sub { $tc->( $_[0] ) ? 1 : undef }; # the undef is for compat
71 sub create_type_constraint_union {
72 _create_type_constraint_union(\@_);
75 sub create_named_type_constraint_union {
77 _create_type_constraint_union($name, \@_);
80 sub _create_type_constraint_union {
82 $name = shift if @_ > 1;
83 my @tcs = @{ shift() };
85 my @type_constraint_names;
87 if ( scalar @tcs == 1 && _detect_type_constraint_union( $tcs[0] ) ) {
88 @type_constraint_names = _parse_type_constraint_union( $tcs[0] );
91 @type_constraint_names = @tcs;
94 ( scalar @type_constraint_names >= 2 )
95 || __PACKAGE__->_throw_error(
96 "You must pass in at least 2 type names to make a union");
98 my @type_constraints = map {
99 find_or_parse_type_constraint($_)
100 || __PACKAGE__->_throw_error(
101 "Could not locate type constraint ($_) for the union");
102 } @type_constraint_names;
105 type_constraints => \@type_constraints
107 $options{name} = $name if defined $name;
109 return Moose::Meta::TypeConstraint::Union->new(%options);
113 sub create_parameterized_type_constraint {
114 my $type_constraint_name = shift;
115 my ( $base_type, $type_parameter )
116 = _parse_parameterized_type_constraint($type_constraint_name);
118 ( defined $base_type && defined $type_parameter )
119 || __PACKAGE__->_throw_error(
120 "Could not parse type name ($type_constraint_name) correctly");
122 if ( $REGISTRY->has_type_constraint($base_type) ) {
123 my $base_type_tc = $REGISTRY->get_type_constraint($base_type);
124 return _create_parameterized_type_constraint(
130 __PACKAGE__->_throw_error(
131 "Could not locate the base type ($base_type)");
135 sub _create_parameterized_type_constraint {
136 my ( $base_type_tc, $type_parameter ) = @_;
137 if ( $base_type_tc->can('parameterize') ) {
138 return $base_type_tc->parameterize($type_parameter);
141 return Moose::Meta::TypeConstraint::Parameterized->new(
142 name => $base_type_tc->name . '[' . $type_parameter . ']',
143 parent => $base_type_tc,
145 find_or_create_isa_type_constraint($type_parameter),
150 #should we also support optimized checks?
151 sub create_class_type_constraint {
152 my ( $class, $options ) = @_;
154 # too early for this check
155 #find_type_constraint("ClassName")->check($class)
156 # || __PACKAGE__->_throw_error("Can't create a class type constraint because '$class' is not a class name");
158 my $pkg_defined_in = $options->{package_defined_in} || scalar( caller(1) );
160 if (my $type = $REGISTRY->get_type_constraint($class)) {
161 if (!($type->isa('Moose::Meta::TypeConstraint::Class') && $type->class eq $class)) {
163 "The type constraint '$class' has already been created in "
164 . $type->_package_defined_in
165 . " and cannot be created again in "
173 package_defined_in => $pkg_defined_in,
177 $options{name} ||= "__ANON__";
179 my $tc = Moose::Meta::TypeConstraint::Class->new(%options);
180 $REGISTRY->add_type_constraint($tc);
184 sub create_role_type_constraint {
185 my ( $role, $options ) = @_;
187 # too early for this check
188 #find_type_constraint("ClassName")->check($class)
189 # || __PACKAGE__->_throw_error("Can't create a class type constraint because '$class' is not a class name");
191 my $pkg_defined_in = $options->{package_defined_in} || scalar( caller(1) );
193 if (my $type = $REGISTRY->get_type_constraint($role)) {
194 if (!($type->isa('Moose::Meta::TypeConstraint::Role') && $type->role eq $role)) {
196 "The type constraint '$role' has already been created in "
197 . $type->_package_defined_in
198 . " and cannot be created again in "
206 package_defined_in => $pkg_defined_in,
210 $options{name} ||= "__ANON__";
212 my $tc = Moose::Meta::TypeConstraint::Role->new(%options);
213 $REGISTRY->add_type_constraint($tc);
217 sub find_or_create_type_constraint {
218 my ( $type_constraint_name, $options_for_anon_type ) = @_;
221 = find_or_parse_type_constraint($type_constraint_name) ) {
224 elsif ( defined $options_for_anon_type ) {
227 # if there is no $options_for_anon_type
228 # specified, then we assume they don't
229 # want to create one, and return nothing.
231 # otherwise assume that we should create
232 # an ANON type with the $options_for_anon_type
233 # options which can be passed in. It should
234 # be noted that these don't get registered
235 # so we need to return it.
237 return Moose::Meta::TypeConstraint->new(
239 %{$options_for_anon_type}
246 sub find_or_create_isa_type_constraint {
247 my ($type_constraint_name, $options) = @_;
248 find_or_parse_type_constraint($type_constraint_name)
249 || create_class_type_constraint($type_constraint_name, $options);
252 sub find_or_create_does_type_constraint {
253 my ($type_constraint_name, $options) = @_;
254 find_or_parse_type_constraint($type_constraint_name)
255 || create_role_type_constraint($type_constraint_name, $options);
258 sub find_or_parse_type_constraint {
259 my $type_constraint_name = normalize_type_constraint_name(shift);
262 if ( $constraint = find_type_constraint($type_constraint_name) ) {
265 elsif ( _detect_type_constraint_union($type_constraint_name) ) {
266 $constraint = create_type_constraint_union($type_constraint_name);
268 elsif ( _detect_parameterized_type_constraint($type_constraint_name) ) {
270 = create_parameterized_type_constraint($type_constraint_name);
276 $REGISTRY->add_type_constraint($constraint);
280 sub normalize_type_constraint_name {
281 my $type_constraint_name = shift;
282 $type_constraint_name =~ s/\s//g;
283 return $type_constraint_name;
289 local $Carp::CarpLevel = $Carp::CarpLevel + 1;
290 Carp::confess($error);
293 ## --------------------------------------------------------
294 ## exported functions ...
295 ## --------------------------------------------------------
297 sub find_type_constraint {
300 if ( blessed $type and $type->isa("Moose::Meta::TypeConstraint") ) {
304 return unless $REGISTRY->has_type_constraint($type);
305 return $REGISTRY->get_type_constraint($type);
309 sub register_type_constraint {
310 my $constraint = shift;
311 __PACKAGE__->_throw_error("can't register an unnamed type constraint")
312 unless defined $constraint->name;
313 $REGISTRY->add_type_constraint($constraint);
322 my %p = map { %{$_} } @_;
324 return _create_type_constraint(
325 $name, undef, $p{where}, $p{message},
326 $p{optimize_as}, $p{inline_as},
331 if ( @_ == 1 && !ref $_[0] ) {
332 __PACKAGE__->_throw_error(
333 'A subtype cannot consist solely of a name, it must have a parent'
337 # The blessed check is mostly to accommodate MooseX::Types, which
338 # uses an object which overloads stringification as a type name.
339 my $name = ref $_[0] && !blessed $_[0] ? undef : shift;
341 my %p = map { %{$_} } @_;
343 # subtype Str => where { ... };
344 if ( !exists $p{as} ) {
349 return _create_type_constraint(
350 $name, $p{as}, $p{where}, $p{message},
351 $p{optimize_as}, $p{inline_as},
356 create_class_type_constraint(@_);
359 sub role_type ($;$) {
360 create_role_type_constraint(@_);
364 my ($type_parameter) = @_;
366 register_type_constraint(
367 $REGISTRY->get_type_constraint('Maybe')->parameterize($type_parameter)
372 my ( $type_name, @methods ) = @_;
373 if ( ref $type_name eq 'ARRAY' && !@methods ) {
374 @methods = @$type_name;
377 if ( @methods == 1 && ref $methods[0] eq 'ARRAY' ) {
378 @methods = @{ $methods[0] };
381 register_type_constraint(
382 create_duck_type_constraint(
390 my ( $type_name, @coercion_map ) = @_;
391 _install_type_coercions( $type_name, \@coercion_map );
394 # The trick of returning @_ lets us avoid having to specify a
395 # prototype. Perl will parse this:
403 # subtype( 'Foo', as( 'Str', where { ... } ) );
405 # If as() returns all its extra arguments, this just works, and
406 # preserves backwards compatibility.
407 sub as { { as => shift }, @_ }
408 sub where (&) { { where => $_[0] } }
409 sub message (&) { { message => $_[0] } }
410 sub optimize_as (&) { { optimize_as => $_[0] } }
411 sub inline_as (&) { { inline_as => $_[0] } }
414 sub via (&) { $_[0] }
417 my ( $type_name, @values ) = @_;
420 # if only an array-ref is passed then
421 # you get an anon-enum
423 if ( ref $type_name eq 'ARRAY' ) {
425 || __PACKAGE__->_throw_error("enum called with an array reference and additional arguments. Did you mean to parenthesize the enum call's parameters?");
427 @values = @$type_name;
430 if ( @values == 1 && ref $values[0] eq 'ARRAY' ) {
431 @values = @{ $values[0] };
434 register_type_constraint(
435 create_enum_type_constraint(
443 my ( $type_name, @constraints ) = @_;
444 if ( ref $type_name eq 'ARRAY' ) {
446 || __PACKAGE__->_throw_error("union called with an array reference and additional arguments.");
447 @constraints = @$type_name;
450 if ( @constraints == 1 && ref $constraints[0] eq 'ARRAY' ) {
451 @constraints = @{ $constraints[0] };
453 if ( defined $type_name ) {
454 return register_type_constraint(
455 create_named_type_constraint_union( $type_name, @constraints )
458 return create_type_constraint_union( @constraints );
461 sub create_enum_type_constraint {
462 my ( $type_name, $values ) = @_;
464 Moose::Meta::TypeConstraint::Enum->new(
465 name => $type_name || '__ANON__',
470 sub create_duck_type_constraint {
471 my ( $type_name, $methods ) = @_;
473 Moose::Meta::TypeConstraint::DuckType->new(
474 name => $type_name || '__ANON__',
480 my ($to_match, @cases) = @_;
482 if (@cases % 2 != 0) {
483 $default = pop @cases;
484 (ref $default eq 'CODE')
485 || __PACKAGE__->_throw_error("Default case must be a CODE ref, not $default");
488 my ($type, $action) = splice @cases, 0, 2;
490 unless (blessed $type && $type->isa('Moose::Meta::TypeConstraint')) {
491 $type = find_or_parse_type_constraint($type)
492 || __PACKAGE__->_throw_error("Cannot find or parse the type '$type'")
495 (ref $action eq 'CODE')
496 || __PACKAGE__->_throw_error("Match action must be a CODE ref, not $action");
498 if ($type->check($to_match)) {
499 local $_ = $to_match;
500 return $action->($to_match);
504 || __PACKAGE__->_throw_error("No cases matched for $to_match");
506 local $_ = $to_match;
507 return $default->($to_match);
512 ## --------------------------------------------------------
513 ## desugaring functions ...
514 ## --------------------------------------------------------
516 sub _create_type_constraint ($$$;$$) {
521 my $optimized = shift;
524 my $pkg_defined_in = scalar( caller(1) );
526 if ( defined $name ) {
527 my $type = $REGISTRY->get_type_constraint($name);
529 ( $type->_package_defined_in eq $pkg_defined_in )
531 "The type constraint '$name' has already been created in "
532 . $type->_package_defined_in
533 . " and cannot be created again in "
537 $name =~ /^[\w:\.]+$/
538 or die qq{$name contains invalid characters for a type name.}
539 . qq{ Names can contain alphanumeric character, ":", and "."\n};
544 package_defined_in => $pkg_defined_in,
546 ( $check ? ( constraint => $check ) : () ),
547 ( $message ? ( message => $message ) : () ),
548 ( $optimized ? ( optimized => $optimized ) : () ),
549 ( $inlined ? ( inlined => $inlined ) : () ),
558 : find_or_create_isa_type_constraint($parent)
560 $constraint = $parent->create_child_type(%opts);
563 $constraint = Moose::Meta::TypeConstraint->new(%opts);
566 $REGISTRY->add_type_constraint($constraint)
572 sub _install_type_coercions ($$) {
573 my ( $type_name, $coercion_map ) = @_;
574 my $type = find_type_constraint($type_name);
576 || __PACKAGE__->_throw_error(
577 "Cannot find type '$type_name', perhaps you forgot to load it");
578 if ( $type->has_coercion ) {
579 $type->coercion->add_type_coercions(@$coercion_map);
582 my $type_coercion = Moose::Meta::TypeCoercion->new(
583 type_coercion_map => $coercion_map,
584 type_constraint => $type
586 $type->coercion($type_coercion);
590 ## --------------------------------------------------------
591 ## type notation parsing ...
592 ## --------------------------------------------------------
596 # All I have to say is mugwump++ cause I know
597 # do not even have enough regexp-fu to be able
598 # to have written this (I can only barely
599 # understand it as it is)
604 my $valid_chars = qr{[\w:\.]};
605 my $type_atom = qr{ (?>$valid_chars+) }x;
606 my $ws = qr{ (?>\s*) }x;
607 my $op_union = qr{ $ws \| $ws }x;
609 my ($type, $type_capture_parts, $type_with_parameter, $union, $any);
610 if (Class::MOP::IS_RUNNING_ON_5_10) {
612 = q{ (?&type_atom) (?: \[ (?&ws) (?&any) (?&ws) \] )? };
613 my $type_capture_parts_pattern
614 = q{ ((?&type_atom)) (?: \[ (?&ws) ((?&any)) (?&ws) \] )? };
615 my $type_with_parameter_pattern
616 = q{ (?&type_atom) \[ (?&ws) (?&any) (?&ws) \] };
618 = q{ (?&type) (?> (?: (?&op_union) (?&type) )+ ) };
620 = q{ (?&type) | (?&union) };
622 my $defines = qr{(?(DEFINE)
623 (?<valid_chars> $valid_chars)
624 (?<type_atom> $type_atom)
626 (?<op_union> $op_union)
627 (?<type> $type_pattern)
628 (?<type_capture_parts> $type_capture_parts_pattern)
629 (?<type_with_parameter> $type_with_parameter_pattern)
630 (?<union> $union_pattern)
631 (?<any> $any_pattern)
634 $type = qr{ $type_pattern $defines }x;
635 $type_capture_parts = qr{ $type_capture_parts_pattern $defines }x;
636 $type_with_parameter = qr{ $type_with_parameter_pattern $defines }x;
637 $union = qr{ $union_pattern $defines }x;
638 $any = qr{ $any_pattern $defines }x;
642 = qr{ $type_atom (?: \[ $ws (??{$any}) $ws \] )? }x;
644 = qr{ ($type_atom) (?: \[ $ws ((??{$any})) $ws \] )? }x;
646 = qr{ $type_atom \[ $ws (??{$any}) $ws \] }x;
648 = qr{ $type (?> (?: $op_union $type )+ ) }x;
650 = qr{ $type | $union }x;
654 sub _parse_parameterized_type_constraint {
655 { no warnings 'void'; $any; } # force capture of interpolated lexical
656 $_[0] =~ m{ $type_capture_parts }x;
660 sub _detect_parameterized_type_constraint {
661 { no warnings 'void'; $any; } # force capture of interpolated lexical
662 $_[0] =~ m{ ^ $type_with_parameter $ }x;
665 sub _parse_type_constraint_union {
666 { no warnings 'void'; $any; } # force capture of interpolated lexical
669 while ( $given =~ m{ \G (?: $op_union )? ($type) }gcx ) {
672 ( pos($given) eq length($given) )
673 || __PACKAGE__->_throw_error( "'$given' didn't parse (parse-pos="
681 sub _detect_type_constraint_union {
682 { no warnings 'void'; $any; } # force capture of interpolated lexical
683 $_[0] =~ m{^ $type $op_union $type ( $op_union .* )? $}x;
687 ## --------------------------------------------------------
688 # define some basic built-in types
689 ## --------------------------------------------------------
691 # By making these classes immutable before creating all the types in
692 # Moose::Util::TypeConstraints::Builtin , we avoid repeatedly calling the slow
693 # MOP-based accessors.
695 inline_constructor => 1,
696 constructor_name => "_new",
698 # these are Class::MOP accessors, so they need inlining
699 inline_accessors => 1
700 ) for grep { $_->is_mutable }
701 map { Class::MOP::class_of($_) }
703 Moose::Meta::TypeConstraint
704 Moose::Meta::TypeConstraint::Union
705 Moose::Meta::TypeConstraint::Parameterized
706 Moose::Meta::TypeConstraint::Parameterizable
707 Moose::Meta::TypeConstraint::Class
708 Moose::Meta::TypeConstraint::Role
709 Moose::Meta::TypeConstraint::Enum
710 Moose::Meta::TypeConstraint::DuckType
711 Moose::Meta::TypeConstraint::Registry
714 require Moose::Util::TypeConstraints::Builtins;
715 Moose::Util::TypeConstraints::Builtins::define_builtins($REGISTRY);
717 my @PARAMETERIZABLE_TYPES
718 = map { $REGISTRY->get_type_constraint($_) } qw[ScalarRef ArrayRef HashRef Maybe];
720 sub get_all_parameterizable_types {@PARAMETERIZABLE_TYPES}
722 sub add_parameterizable_type {
725 && $type->isa('Moose::Meta::TypeConstraint::Parameterizable') )
726 || __PACKAGE__->_throw_error(
727 "Type must be a Moose::Meta::TypeConstraint::Parameterizable not $type"
729 push @PARAMETERIZABLE_TYPES => $type;
732 ## --------------------------------------------------------
733 # end of built-in types ...
734 ## --------------------------------------------------------
737 my @BUILTINS = list_all_type_constraints();
738 sub list_all_builtin_type_constraints {@BUILTINS}
745 goto &Moose::throw_error;
750 # ABSTRACT: Type constraint system for Moose
758 use Moose::Util::TypeConstraints;
764 subtype 'NaturalLessThanTen',
767 message { "This number ($_) is not less than ten!" };
773 class_type 'DateTimeClass', { class => 'DateTime' };
775 role_type 'Barks', { role => 'Some::Library::Role::Barks' };
777 enum 'RGBColors', [qw(red green blue)];
779 union 'StringOrArray', [qw( String Array )];
781 no Moose::Util::TypeConstraints;
785 This module provides Moose with the ability to create custom type
786 constraints to be used in attribute definition.
788 =head2 Important Caveat
790 This is B<NOT> a type system for Perl 5. These are type constraints,
791 and they are not used by Moose unless you tell it to. No type
792 inference is performed, expressions are not typed, etc. etc. etc.
794 A type constraint is at heart a small "check if a value is valid"
795 function. A constraint can be associated with an attribute. This
796 simplifies parameter validation, and makes your code clearer to read,
797 because you can refer to constraints by name.
799 =head2 Slightly Less Important Caveat
801 It is B<always> a good idea to quote your type names.
803 This prevents Perl from trying to execute the call as an indirect
804 object call. This can be an issue when you have a subtype with the
805 same name as a valid class.
809 subtype DateTime => as Object => where { $_->isa('DateTime') };
811 will I<just work>, while this:
814 subtype DateTime => as Object => where { $_->isa('DateTime') };
816 will fail silently and cause many headaches. The simple way to solve
817 this, as well as future proof your subtypes from classes which have
818 yet to have been created, is to quote the type name:
821 subtype 'DateTime', as 'Object', where { $_->isa('DateTime') };
823 =head2 Default Type Constraints
825 This module also provides a simple hierarchy for Perl 5 types, here is
826 that hierarchy represented visually.
850 B<NOTE:> Any type followed by a type parameter C<[`a]> can be
851 parameterized, this means you can say:
853 ArrayRef[Int] # an array of integers
854 HashRef[CodeRef] # a hash of str to CODE ref mappings
855 ScalarRef[Int] # a reference to an integer
856 Maybe[Str] # value may be a string, may be undefined
858 If Moose finds a name in brackets that it does not recognize as an
859 existing type, it assumes that this is a class name, for example
860 C<ArrayRef[DateTime]>.
862 B<NOTE:> Unless you parameterize a type, then it is invalid to include
863 the square brackets. I.e. C<ArrayRef[]> will be treated as a new type
864 name, I<not> as a parameterization of C<ArrayRef>.
866 B<NOTE:> The C<Undef> type constraint for the most part works
867 correctly now, but edge cases may still exist, please use it
870 B<NOTE:> The C<ClassName> type constraint does a complex package
871 existence check. This means that your class B<must> be loaded for this
872 type constraint to pass.
874 B<NOTE:> The C<RoleName> constraint checks a string is a I<package
875 name> which is a role, like C<'MyApp::Role::Comparable'>.
877 =head2 Type Constraint Naming
879 Type name declared via this module can only contain alphanumeric
880 characters, colons (:), and periods (.).
882 Since the types created by this module are global, it is suggested
883 that you namespace your types just as you would namespace your
884 modules. So instead of creating a I<Color> type for your
885 B<My::Graphics> module, you would call the type
886 I<My::Graphics::Types::Color> instead.
888 =head2 Use with Other Constraint Modules
890 This module can play nicely with other constraint modules with some
891 slight tweaking. The C<where> clause in types is expected to be a
892 C<CODE> reference which checks its first argument and returns a
893 boolean. Since most constraint modules work in a similar way, it
894 should be simple to adapt them to work with Moose.
896 For instance, this is how you could use it with
897 L<Declare::Constraints::Simple> to declare a completely new type.
899 type 'HashOfArrayOfObjects',
903 -values => IsArrayRef(IsObject)
907 For more examples see the F<t/examples/example_w_DCS.t> test
910 Here is an example of using L<Test::Deep> and its non-test
911 related C<eq_deeply> function.
913 type 'ArrayOfHashOfBarsAndRandomNumbers',
916 array_each(subhashof({
918 random_number => ignore()
922 For a complete example see the
923 F<t/examples/example_w_TestDeep.t> test file.
925 =head2 Error messages
927 Type constraints can also specify custom error messages, for when they fail to
928 validate. This is provided as just another coderef, which receives the invalid
929 value in C<$_>, as in:
931 subtype 'PositiveInt',
934 message { "$_ is not a positive integer!" };
936 If no message is specified, a default message will be used, which indicates
937 which type constraint was being used and what value failed. If
938 L<Devel::PartialDump> (version 0.14 or higher) is installed, it will be used to
939 display the invalid value, otherwise it will just be printed as is.
943 =head2 Type Constraint Constructors
945 The following functions are used to create type constraints. They
946 will also register the type constraints your create in a global
947 registry that is used to look types up by name.
949 See the L</SYNOPSIS> for an example of how to use these.
953 =item B<< subtype 'Name', as 'Parent', where { } ... >>
955 This creates a named subtype.
957 If you provide a parent that Moose does not recognize, it will
958 automatically create a new class type constraint for this name.
960 When creating a named type, the C<subtype> function should either be
961 called with the sugar helpers (C<where>, C<message>, etc), or with a
962 name and a hashref of parameters:
964 subtype( 'Foo', { where => ..., message => ... } );
966 The valid hashref keys are C<as> (the parent), C<where>, C<message>,
969 =item B<< subtype as 'Parent', where { } ... >>
971 This creates an unnamed subtype and will return the type
972 constraint meta-object, which will be an instance of
973 L<Moose::Meta::TypeConstraint>.
975 When creating an anonymous type, the C<subtype> function should either
976 be called with the sugar helpers (C<where>, C<message>, etc), or with
977 just a hashref of parameters:
979 subtype( { where => ..., message => ... } );
981 =item B<class_type ($class, ?$options)>
983 Creates a new subtype of C<Object> with the name C<$class> and the
984 metaclass L<Moose::Meta::TypeConstraint::Class>.
986 # Create a type called 'Box' which tests for objects which ->isa('Box')
989 By default, the name of the type and the name of the class are the same, but
990 you can specify both separately.
992 # Create a type called 'Box' which tests for objects which ->isa('ObjectLibrary::Box');
993 class_type 'Box', { class => 'ObjectLibrary::Box' };
995 =item B<role_type ($role, ?$options)>
997 Creates a C<Role> type constraint with the name C<$role> and the
998 metaclass L<Moose::Meta::TypeConstraint::Role>.
1000 # Create a type called 'Walks' which tests for objects which ->does('Walks')
1003 By default, the name of the type and the name of the role are the same, but
1004 you can specify both separately.
1006 # Create a type called 'Walks' which tests for objects which ->does('MooseX::Role::Walks');
1007 role_type 'Walks', { role => 'MooseX::Role::Walks' };
1009 =item B<maybe_type ($type)>
1011 Creates a type constraint for either C<undef> or something of the
1014 =item B<duck_type ($name, \@methods)>
1016 This will create a subtype of Object and test to make sure the value
1017 C<can()> do the methods in C<\@methods>.
1019 This is intended as an easy way to accept non-Moose objects that
1020 provide a certain interface. If you're using Moose classes, we
1021 recommend that you use a C<requires>-only Role instead.
1023 =item B<duck_type (\@methods)>
1025 If passed an ARRAY reference as the only parameter instead of the
1026 C<$name>, C<\@methods> pair, this will create an unnamed duck type.
1027 This can be used in an attribute definition like so:
1031 isa => duck_type( [qw( get_set )] ),
1034 =item B<enum ($name, \@values)>
1036 This will create a basic subtype for a given set of strings.
1037 The resulting constraint will be a subtype of C<Str> and
1038 will match any of the items in C<\@values>. It is case sensitive.
1039 See the L</SYNOPSIS> for a simple example.
1041 B<NOTE:> This is not a true proper enum type, it is simply
1042 a convenient constraint builder.
1044 =item B<enum (\@values)>
1046 If passed an ARRAY reference as the only parameter instead of the
1047 C<$name>, C<\@values> pair, this will create an unnamed enum. This
1048 can then be used in an attribute definition like so:
1050 has 'sort_order' => (
1052 isa => enum([qw[ ascending descending ]]),
1055 =item B<union ($name, \@constraints)>
1057 This will create a basic subtype where any of the provided constraints
1058 may match in order to satisfy this constraint.
1060 =item B<union (\@constraints)>
1062 If passed an ARRAY reference as the only parameter instead of the
1063 C<$name>, C<\@constraints> pair, this will create an unnamed union.
1064 This can then be used in an attribute definition like so:
1068 isa => union([qw[ Str ArrayRef ]]),
1071 This is similar to the existing string union:
1073 isa => 'Str|ArrayRef'
1075 except that it supports anonymous elements as child constraints:
1079 isa => union([ 'Int', enum([qw[ red green blue ]]) ]),
1082 =item B<as 'Parent'>
1084 This is just sugar for the type constraint construction syntax.
1086 It takes a single argument, which is the name of a parent type.
1088 =item B<where { ... }>
1090 This is just sugar for the type constraint construction syntax.
1092 It takes a subroutine reference as an argument. When the type
1093 constraint is tested, the reference is run with the value to be tested
1094 in C<$_>. This reference should return true or false to indicate
1095 whether or not the constraint check passed.
1097 =item B<message { ... }>
1099 This is just sugar for the type constraint construction syntax.
1101 It takes a subroutine reference as an argument. When the type
1102 constraint fails, then the code block is run with the value provided
1103 in C<$_>. This reference should return a string, which will be used in
1104 the text of the exception thrown.
1106 =item B<inline_as { ... }>
1108 This can be used to define a "hand optimized" inlinable version of your type
1111 You provide a subroutine which will be called I<as a method> on a
1112 L<Moose::Meta::TypeConstraint> object. It will receive a single parameter, the
1113 name of the variable to check, typically something like C<"$_"> or C<"$_[0]">.
1115 The subroutine should return a code string suitable for inlining. You can
1116 assume that the check will be wrapped in parentheses when it is inlined.
1118 The inlined code should include any checks that your type's parent types
1119 do. For example, the C<Value> type's inlining sub looks like this:
1122 'defined(' . $_[1] . ')'
1123 . ' && !ref(' . $_[1] . ')'
1126 Note that it checks if the variable is defined, since it is a subtype of
1127 the C<Defined> type. However, to avoid repeating code, this can be optimized as:
1130 $_[0]->parent()->_inline_check($_[1])
1131 . ' && !ref(' . $_[1] . ')'
1134 =item B<optimize_as { ... }>
1136 B<This feature is deprecated, use C<inline_as> instead.>
1138 This can be used to define a "hand optimized" version of your
1139 type constraint which can be used to avoid traversing a subtype
1140 constraint hierarchy.
1142 B<NOTE:> You should only use this if you know what you are doing.
1143 All the built in types use this, so your subtypes (assuming they
1144 are shallow) will not likely need to use this.
1146 =item B<< type 'Name', where { } ... >>
1148 This creates a base type, which has no parent.
1150 The C<type> function should either be called with the sugar helpers
1151 (C<where>, C<message>, etc), or with a name and a hashref of
1154 type( 'Foo', { where => ..., message => ... } );
1156 The valid hashref keys are C<where>, C<message>, and C<inlined_as>.
1160 =head2 Type Constraint Utilities
1164 =item B<< match_on_type $value => ( $type => \&action, ... ?\&default ) >>
1166 This is a utility function for doing simple type based dispatching similar to
1167 match/case in OCaml and case/of in Haskell. It is not as featureful as those
1168 languages, nor does not it support any kind of automatic destructuring
1169 bind. Here is a simple Perl pretty printer dispatching over the core Moose
1174 match_on_type $x => (
1179 join ", " => map { $_ . ' => ' . ppprint( $hash->{$_} ) }
1185 '[ ' . ( join ", " => map { ppprint($_) } @$array ) . ' ]';
1187 CodeRef => sub {'sub { ... }'},
1188 RegexpRef => sub { 'qr/' . $_ . '/' },
1189 GlobRef => sub { '*' . B::svref_2object($_)->NAME },
1190 Object => sub { $_->can('to_string') ? $_->to_string : $_ },
1191 ScalarRef => sub { '\\' . ppprint( ${$_} ) },
1193 Str => sub { '"' . $_ . '"' },
1194 Undef => sub {'undef'},
1195 => sub { die "I don't know what $_ is" }
1199 Or a simple JSON serializer:
1203 match_on_type $x => (
1209 map { '"' . $_ . '" : ' . to_json( $hash->{$_} ) }
1215 '[ ' . ( join ", " => map { to_json($_) } @$array ) . ' ]';
1218 Str => sub { '"' . $_ . '"' },
1219 Undef => sub {'null'},
1220 => sub { die "$_ is not acceptable json type" }
1224 The matcher is done by mapping a C<$type> to an C<\&action>. The C<$type> can
1225 be either a string type or a L<Moose::Meta::TypeConstraint> object, and
1226 C<\&action> is a subroutine reference. This function will dispatch on the
1227 first match for C<$value>. It is possible to have a catch-all by providing an
1228 additional subroutine reference as the final argument to C<match_on_type>.
1232 =head2 Type Coercion Constructors
1234 You can define coercions for type constraints, which allow you to
1235 automatically transform values to something valid for the type
1236 constraint. If you ask your accessor to coerce, then Moose will run
1237 the type-coercion code first, followed by the type constraint
1238 check. This feature should be used carefully as it is very powerful
1239 and could easily take off a limb if you are not careful.
1241 See the L</SYNOPSIS> for an example of how to use these.
1245 =item B<< coerce 'Name', from 'OtherName', via { ... } >>
1247 This defines a coercion from one type to another. The C<Name> argument
1248 is the type you are coercing I<to>.
1250 To define multiple coercions, supply more sets of from/via pairs:
1253 from 'OtherName', via { ... },
1254 from 'ThirdName', via { ... };
1256 =item B<from 'OtherName'>
1258 This is just sugar for the type coercion construction syntax.
1260 It takes a single type name (or type object), which is the type being
1263 =item B<via { ... }>
1265 This is just sugar for the type coercion construction syntax.
1267 It takes a subroutine reference. This reference will be called with
1268 the value to be coerced in C<$_>. It is expected to return a new value
1269 of the proper type for the coercion.
1273 =head2 Creating and Finding Type Constraints
1275 These are additional functions for creating and finding type
1276 constraints. Most of these functions are not available for
1277 importing. The ones that are importable as specified.
1281 =item B<find_type_constraint($type_name)>
1283 This function can be used to locate the L<Moose::Meta::TypeConstraint>
1284 object for a named type.
1286 This function is importable.
1288 =item B<register_type_constraint($type_object)>
1290 This function will register a L<Moose::Meta::TypeConstraint> with the
1291 global type registry.
1293 This function is importable.
1295 =item B<normalize_type_constraint_name($type_constraint_name)>
1297 This method takes a type constraint name and returns the normalized
1298 form. This removes any whitespace in the string.
1300 =item B<create_type_constraint_union($pipe_separated_types | @type_constraint_names)>
1302 =item B<create_named_type_constraint_union($name, $pipe_separated_types | @type_constraint_names)>
1304 This can take a union type specification like C<'Int|ArrayRef[Int]'>,
1305 or a list of names. It returns a new
1306 L<Moose::Meta::TypeConstraint::Union> object.
1308 =item B<create_parameterized_type_constraint($type_name)>
1310 Given a C<$type_name> in the form of C<'BaseType[ContainerType]'>,
1311 this will create a new L<Moose::Meta::TypeConstraint::Parameterized>
1312 object. The C<BaseType> must exist already exist as a parameterizable
1315 =item B<create_class_type_constraint($class, $options)>
1317 Given a class name this function will create a new
1318 L<Moose::Meta::TypeConstraint::Class> object for that class name.
1320 The C<$options> is a hash reference that will be passed to the
1321 L<Moose::Meta::TypeConstraint::Class> constructor (as a hash).
1323 =item B<create_role_type_constraint($role, $options)>
1325 Given a role name this function will create a new
1326 L<Moose::Meta::TypeConstraint::Role> object for that role name.
1328 The C<$options> is a hash reference that will be passed to the
1329 L<Moose::Meta::TypeConstraint::Role> constructor (as a hash).
1331 =item B<create_enum_type_constraint($name, $values)>
1333 Given a enum name this function will create a new
1334 L<Moose::Meta::TypeConstraint::Enum> object for that enum name.
1336 =item B<create_duck_type_constraint($name, $methods)>
1338 Given a duck type name this function will create a new
1339 L<Moose::Meta::TypeConstraint::DuckType> object for that enum name.
1341 =item B<find_or_parse_type_constraint($type_name)>
1343 Given a type name, this first attempts to find a matching constraint
1344 in the global registry.
1346 If the type name is a union or parameterized type, it will create a
1347 new object of the appropriate, but if given a "regular" type that does
1348 not yet exist, it simply returns false.
1350 When given a union or parameterized type, the member or base type must
1353 If it creates a new union or parameterized type, it will add it to the
1356 =item B<find_or_create_isa_type_constraint($type_name)>
1358 =item B<find_or_create_does_type_constraint($type_name)>
1360 These functions will first call C<find_or_parse_type_constraint>. If
1361 that function does not return a type, a new type object will
1364 The C<isa> variant will use C<create_class_type_constraint> and the
1365 C<does> variant will use C<create_role_type_constraint>.
1367 =item B<get_type_constraint_registry>
1369 Returns the L<Moose::Meta::TypeConstraint::Registry> object which
1370 keeps track of all type constraints.
1372 =item B<list_all_type_constraints>
1374 This will return a list of type constraint names in the global
1375 registry. You can then fetch the actual type object using
1376 C<find_type_constraint($type_name)>.
1378 =item B<list_all_builtin_type_constraints>
1380 This will return a list of builtin type constraints, meaning those
1381 which are defined in this module. See the L<Default Type Constraints>
1382 section for a complete list.
1384 =item B<export_type_constraints_as_functions>
1386 This will export all the current type constraints as functions into
1387 the caller's namespace (C<Int()>, C<Str()>, etc). Right now, this is
1388 mostly used for testing, but it might prove useful to others.
1390 =item B<get_all_parameterizable_types>
1392 This returns all the parameterizable types that have been registered,
1393 as a list of type objects.
1395 =item B<add_parameterizable_type($type)>
1397 Adds C<$type> to the list of parameterizable types
1403 See L<Moose/BUGS> for details on reporting bugs.