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
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 my @type_constraint_names;
74 if ( scalar @_ == 1 && _detect_type_constraint_union( $_[0] ) ) {
75 @type_constraint_names = _parse_type_constraint_union( $_[0] );
78 @type_constraint_names = @_;
81 ( scalar @type_constraint_names >= 2 )
82 || __PACKAGE__->_throw_error(
83 "You must pass in at least 2 type names to make a union");
85 my @type_constraints = map {
86 find_or_parse_type_constraint($_)
87 || __PACKAGE__->_throw_error(
88 "Could not locate type constraint ($_) for the union");
89 } @type_constraint_names;
91 return Moose::Meta::TypeConstraint::Union->new(
92 type_constraints => \@type_constraints );
95 sub create_parameterized_type_constraint {
96 my $type_constraint_name = shift;
97 my ( $base_type, $type_parameter )
98 = _parse_parameterized_type_constraint($type_constraint_name);
100 ( defined $base_type && defined $type_parameter )
101 || __PACKAGE__->_throw_error(
102 "Could not parse type name ($type_constraint_name) correctly");
104 if ( $REGISTRY->has_type_constraint($base_type) ) {
105 my $base_type_tc = $REGISTRY->get_type_constraint($base_type);
106 return _create_parameterized_type_constraint(
112 __PACKAGE__->_throw_error(
113 "Could not locate the base type ($base_type)");
117 sub _create_parameterized_type_constraint {
118 my ( $base_type_tc, $type_parameter ) = @_;
119 if ( $base_type_tc->can('parameterize') ) {
120 return $base_type_tc->parameterize($type_parameter);
123 return Moose::Meta::TypeConstraint::Parameterized->new(
124 name => $base_type_tc->name . '[' . $type_parameter . ']',
125 parent => $base_type_tc,
127 find_or_create_isa_type_constraint($type_parameter),
132 #should we also support optimized checks?
133 sub create_class_type_constraint {
134 my ( $class, $options ) = @_;
136 # too early for this check
137 #find_type_constraint("ClassName")->check($class)
138 # || __PACKAGE__->_throw_error("Can't create a class type constraint because '$class' is not a class name");
146 $options{name} ||= "__ANON__";
148 Moose::Meta::TypeConstraint::Class->new(%options);
151 sub create_role_type_constraint {
152 my ( $role, $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");
164 $options{name} ||= "__ANON__";
166 Moose::Meta::TypeConstraint::Role->new(%options);
169 sub find_or_create_type_constraint {
170 my ( $type_constraint_name, $options_for_anon_type ) = @_;
173 = find_or_parse_type_constraint($type_constraint_name) ) {
176 elsif ( defined $options_for_anon_type ) {
179 # if there is no $options_for_anon_type
180 # specified, then we assume they don't
181 # want to create one, and return nothing.
183 # otherwise assume that we should create
184 # an ANON type with the $options_for_anon_type
185 # options which can be passed in. It should
186 # be noted that these don't get registered
187 # so we need to return it.
189 return Moose::Meta::TypeConstraint->new(
191 %{$options_for_anon_type}
198 sub find_or_create_isa_type_constraint {
199 my $type_constraint_name = shift;
200 find_or_parse_type_constraint($type_constraint_name)
201 || create_class_type_constraint($type_constraint_name);
204 sub find_or_create_does_type_constraint {
205 my $type_constraint_name = shift;
206 find_or_parse_type_constraint($type_constraint_name)
207 || create_role_type_constraint($type_constraint_name);
210 sub find_or_parse_type_constraint {
211 my $type_constraint_name = normalize_type_constraint_name(shift);
214 if ( $constraint = find_type_constraint($type_constraint_name) ) {
217 elsif ( _detect_type_constraint_union($type_constraint_name) ) {
218 $constraint = create_type_constraint_union($type_constraint_name);
220 elsif ( _detect_parameterized_type_constraint($type_constraint_name) ) {
222 = create_parameterized_type_constraint($type_constraint_name);
228 $REGISTRY->add_type_constraint($constraint);
232 sub normalize_type_constraint_name {
233 my $type_constraint_name = shift;
234 $type_constraint_name =~ s/\s//g;
235 return $type_constraint_name;
241 local $Carp::CarpLevel = $Carp::CarpLevel + 1;
242 Carp::confess($error);
245 ## --------------------------------------------------------
246 ## exported functions ...
247 ## --------------------------------------------------------
249 sub find_type_constraint {
252 if ( blessed $type and $type->isa("Moose::Meta::TypeConstraint") ) {
256 return unless $REGISTRY->has_type_constraint($type);
257 return $REGISTRY->get_type_constraint($type);
261 sub register_type_constraint {
262 my $constraint = shift;
263 __PACKAGE__->_throw_error("can't register an unnamed type constraint")
264 unless defined $constraint->name;
265 $REGISTRY->add_type_constraint($constraint);
273 # back-compat version, called without sugar
274 if ( !any { ( reftype($_) || '' ) eq 'HASH' } @_ ) {
275 Moose::Deprecated::deprecated(
276 feature => 'type without sugar',
278 'Calling type() with a simple list of parameters is deprecated. This will be an error in Moose 2.0200.'
281 return _create_type_constraint( $_[0], undef, $_[1] );
286 my %p = map { %{$_} } @_;
288 return _create_type_constraint(
289 $name, undef, $p{where}, $p{message},
290 $p{optimize_as}, $p{inline_as},
296 # crazy back-compat code for being called without sugar ...
298 # subtype 'Parent', sub { where };
299 if ( scalar @_ == 2 && ( reftype( $_[1] ) || '' ) eq 'CODE' ) {
300 Moose::Deprecated::deprecated(
301 feature => 'subtype without sugar',
303 'Calling subtype() with a simple list of parameters is deprecated. This will be an error in Moose 2.0200.'
306 return _create_type_constraint( undef, @_ );
309 # subtype 'Parent', sub { where }, sub { message };
310 # subtype 'Parent', sub { where }, sub { message }, sub { optimized };
311 if ( scalar @_ >= 3 && all { ( reftype($_) || '' ) eq 'CODE' }
313 Moose::Deprecated::deprecated(
314 feature => 'subtype without sugar',
316 'Calling subtype() with a simple list of parameters is deprecated. This will be an error in Moose 2.0200.'
319 return _create_type_constraint( undef, @_ );
322 # subtype 'Name', 'Parent', ...
323 if ( scalar @_ >= 2 && all { !ref } @_[ 0, 1 ] ) {
324 Moose::Deprecated::deprecated(
325 feature => 'subtype without sugar',
327 'Calling subtype() with a simple list of parameters is deprecated. This will be an error in Moose 2.0200.'
330 return _create_type_constraint(@_);
333 if ( @_ == 1 && !ref $_[0] ) {
334 __PACKAGE__->_throw_error(
335 'A subtype cannot consist solely of a name, it must have a parent'
339 # The blessed check is mostly to accommodate MooseX::Types, which
340 # uses an object which overloads stringification as a type name.
341 my $name = ref $_[0] && !blessed $_[0] ? undef : shift;
343 my %p = map { %{$_} } @_;
345 # subtype Str => where { ... };
346 if ( !exists $p{as} ) {
351 return _create_type_constraint(
352 $name, $p{as}, $p{where}, $p{message},
353 $p{optimize_as}, $p{inline_as},
358 register_type_constraint(
359 create_class_type_constraint(
361 ( defined( $_[1] ) ? $_[1] : () ),
366 sub role_type ($;$) {
367 register_type_constraint(
368 create_role_type_constraint(
370 ( defined( $_[1] ) ? $_[1] : () ),
376 my ($type_parameter) = @_;
378 register_type_constraint(
379 $REGISTRY->get_type_constraint('Maybe')->parameterize($type_parameter)
384 my ( $type_name, @methods ) = @_;
385 if ( ref $type_name eq 'ARRAY' && !@methods ) {
386 @methods = @$type_name;
389 if ( @methods == 1 && ref $methods[0] eq 'ARRAY' ) {
390 @methods = @{ $methods[0] };
393 register_type_constraint(
394 create_duck_type_constraint(
402 my ( $type_name, @coercion_map ) = @_;
403 _install_type_coercions( $type_name, \@coercion_map );
406 # The trick of returning @_ lets us avoid having to specify a
407 # prototype. Perl will parse this:
415 # subtype( 'Foo', as( 'Str', where { ... } ) );
417 # If as() returns all its extra arguments, this just works, and
418 # preserves backwards compatibility.
419 sub as { { as => shift }, @_ }
420 sub where (&) { { where => $_[0] } }
421 sub message (&) { { message => $_[0] } }
422 sub optimize_as (&) { { optimize_as => $_[0] } }
423 sub inline_as (&) { { inline_as => $_[0] } }
426 sub via (&) { $_[0] }
429 my ( $type_name, @values ) = @_;
432 # if only an array-ref is passed then
433 # you get an anon-enum
435 if ( ref $type_name eq 'ARRAY' ) {
437 || __PACKAGE__->_throw_error("enum called with an array reference and additional arguments. Did you mean to parenthesize the enum call's parameters?");
439 @values = @$type_name;
442 if ( @values == 1 && ref $values[0] eq 'ARRAY' ) {
443 @values = @{ $values[0] };
446 register_type_constraint(
447 create_enum_type_constraint(
454 sub create_enum_type_constraint {
455 my ( $type_name, $values ) = @_;
457 Moose::Meta::TypeConstraint::Enum->new(
458 name => $type_name || '__ANON__',
463 sub create_duck_type_constraint {
464 my ( $type_name, $methods ) = @_;
466 Moose::Meta::TypeConstraint::DuckType->new(
467 name => $type_name || '__ANON__',
473 my ($to_match, @cases) = @_;
475 if (@cases % 2 != 0) {
476 $default = pop @cases;
477 (ref $default eq 'CODE')
478 || __PACKAGE__->_throw_error("Default case must be a CODE ref, not $default");
481 my ($type, $action) = splice @cases, 0, 2;
483 unless (blessed $type && $type->isa('Moose::Meta::TypeConstraint')) {
484 $type = find_or_parse_type_constraint($type)
485 || __PACKAGE__->_throw_error("Cannot find or parse the type '$type'")
488 (ref $action eq 'CODE')
489 || __PACKAGE__->_throw_error("Match action must be a CODE ref, not $action");
491 if ($type->check($to_match)) {
492 local $_ = $to_match;
493 return $action->($to_match);
497 || __PACKAGE__->_throw_error("No cases matched for $to_match");
499 local $_ = $to_match;
500 return $default->($to_match);
505 ## --------------------------------------------------------
506 ## desugaring functions ...
507 ## --------------------------------------------------------
509 sub _create_type_constraint ($$$;$$) {
514 my $optimized = shift;
517 my $pkg_defined_in = scalar( caller(1) );
519 if ( defined $name ) {
520 my $type = $REGISTRY->get_type_constraint($name);
522 ( $type->_package_defined_in eq $pkg_defined_in )
524 "The type constraint '$name' has already been created in "
525 . $type->_package_defined_in
526 . " and cannot be created again in "
530 $name =~ /^[\w:\.]+$/
531 or die qq{$name contains invalid characters for a type name.}
532 . qq{ Names can contain alphanumeric character, ":", and "."\n};
537 package_defined_in => $pkg_defined_in,
539 ( $check ? ( constraint => $check ) : () ),
540 ( $message ? ( message => $message ) : () ),
541 ( $optimized ? ( optimized => $optimized ) : () ),
542 ( $inlined ? ( inlined => $inlined ) : () ),
551 : find_or_create_isa_type_constraint($parent)
553 $constraint = $parent->create_child_type(%opts);
556 $constraint = Moose::Meta::TypeConstraint->new(%opts);
559 $REGISTRY->add_type_constraint($constraint)
565 sub _install_type_coercions ($$) {
566 my ( $type_name, $coercion_map ) = @_;
567 my $type = find_type_constraint($type_name);
569 || __PACKAGE__->_throw_error(
570 "Cannot find type '$type_name', perhaps you forgot to load it");
571 if ( $type->has_coercion ) {
572 $type->coercion->add_type_coercions(@$coercion_map);
575 my $type_coercion = Moose::Meta::TypeCoercion->new(
576 type_coercion_map => $coercion_map,
577 type_constraint => $type
579 $type->coercion($type_coercion);
583 ## --------------------------------------------------------
584 ## type notation parsing ...
585 ## --------------------------------------------------------
589 # All I have to say is mugwump++ cause I know
590 # do not even have enough regexp-fu to be able
591 # to have written this (I can only barely
592 # understand it as it is)
597 my $valid_chars = qr{[\w:\.]};
598 my $type_atom = qr{ (?>$valid_chars+) }x;
599 my $ws = qr{ (?>\s*) }x;
600 my $op_union = qr{ $ws \| $ws }x;
602 my ($type, $type_capture_parts, $type_with_parameter, $union, $any);
603 if (Class::MOP::IS_RUNNING_ON_5_10) {
605 = q{ (?&type_atom) (?: \[ (?&ws) (?&any) (?&ws) \] )? };
606 my $type_capture_parts_pattern
607 = q{ ((?&type_atom)) (?: \[ (?&ws) ((?&any)) (?&ws) \] )? };
608 my $type_with_parameter_pattern
609 = q{ (?&type_atom) \[ (?&ws) (?&any) (?&ws) \] };
611 = q{ (?&type) (?> (?: (?&op_union) (?&type) )+ ) };
613 = q{ (?&type) | (?&union) };
615 my $defines = qr{(?(DEFINE)
616 (?<valid_chars> $valid_chars)
617 (?<type_atom> $type_atom)
619 (?<op_union> $op_union)
620 (?<type> $type_pattern)
621 (?<type_capture_parts> $type_capture_parts_pattern)
622 (?<type_with_parameter> $type_with_parameter_pattern)
623 (?<union> $union_pattern)
624 (?<any> $any_pattern)
627 $type = qr{ $type_pattern $defines }x;
628 $type_capture_parts = qr{ $type_capture_parts_pattern $defines }x;
629 $type_with_parameter = qr{ $type_with_parameter_pattern $defines }x;
630 $union = qr{ $union_pattern $defines }x;
631 $any = qr{ $any_pattern $defines }x;
635 = qr{ $type_atom (?: \[ $ws (??{$any}) $ws \] )? }x;
637 = qr{ ($type_atom) (?: \[ $ws ((??{$any})) $ws \] )? }x;
639 = qr{ $type_atom \[ $ws (??{$any}) $ws \] }x;
641 = qr{ $type (?> (?: $op_union $type )+ ) }x;
643 = qr{ $type | $union }x;
647 sub _parse_parameterized_type_constraint {
648 { no warnings 'void'; $any; } # force capture of interpolated lexical
649 $_[0] =~ m{ $type_capture_parts }x;
653 sub _detect_parameterized_type_constraint {
654 { no warnings 'void'; $any; } # force capture of interpolated lexical
655 $_[0] =~ m{ ^ $type_with_parameter $ }x;
658 sub _parse_type_constraint_union {
659 { no warnings 'void'; $any; } # force capture of interpolated lexical
662 while ( $given =~ m{ \G (?: $op_union )? ($type) }gcx ) {
665 ( pos($given) eq length($given) )
666 || __PACKAGE__->_throw_error( "'$given' didn't parse (parse-pos="
674 sub _detect_type_constraint_union {
675 { no warnings 'void'; $any; } # force capture of interpolated lexical
676 $_[0] =~ m{^ $type $op_union $type ( $op_union .* )? $}x;
680 ## --------------------------------------------------------
681 # define some basic built-in types
682 ## --------------------------------------------------------
684 # By making these classes immutable before creating all the types in
685 # Moose::Util::TypeConstraints::Builtin , we avoid repeatedly calling the slow
686 # MOP-based accessors.
688 inline_constructor => 1,
689 constructor_name => "_new",
691 # these are Class::MOP accessors, so they need inlining
692 inline_accessors => 1
693 ) for grep { $_->is_mutable }
694 map { Class::MOP::class_of($_) }
696 Moose::Meta::TypeConstraint
697 Moose::Meta::TypeConstraint::Union
698 Moose::Meta::TypeConstraint::Parameterized
699 Moose::Meta::TypeConstraint::Parameterizable
700 Moose::Meta::TypeConstraint::Class
701 Moose::Meta::TypeConstraint::Role
702 Moose::Meta::TypeConstraint::Enum
703 Moose::Meta::TypeConstraint::DuckType
704 Moose::Meta::TypeConstraint::Registry
707 require Moose::Util::TypeConstraints::Builtins;
708 Moose::Util::TypeConstraints::Builtins::define_builtins($REGISTRY);
710 my @PARAMETERIZABLE_TYPES
711 = map { $REGISTRY->get_type_constraint($_) } qw[ScalarRef ArrayRef HashRef Maybe];
713 sub get_all_parameterizable_types {@PARAMETERIZABLE_TYPES}
715 sub add_parameterizable_type {
718 && $type->isa('Moose::Meta::TypeConstraint::Parameterizable') )
719 || __PACKAGE__->_throw_error(
720 "Type must be a Moose::Meta::TypeConstraint::Parameterizable not $type"
722 push @PARAMETERIZABLE_TYPES => $type;
725 ## --------------------------------------------------------
726 # end of built-in types ...
727 ## --------------------------------------------------------
730 my @BUILTINS = list_all_type_constraints();
731 sub list_all_builtin_type_constraints {@BUILTINS}
738 goto &Moose::throw_error;
743 # ABSTRACT: Type constraint system for Moose
751 use Moose::Util::TypeConstraints;
757 subtype 'NaturalLessThanTen',
760 message { "This number ($_) is not less than ten!" };
766 enum 'RGBColors', [qw(red green blue)];
768 no Moose::Util::TypeConstraints;
772 This module provides Moose with the ability to create custom type
773 constraints to be used in attribute definition.
775 =head2 Important Caveat
777 This is B<NOT> a type system for Perl 5. These are type constraints,
778 and they are not used by Moose unless you tell it to. No type
779 inference is performed, expressions are not typed, etc. etc. etc.
781 A type constraint is at heart a small "check if a value is valid"
782 function. A constraint can be associated with an attribute. This
783 simplifies parameter validation, and makes your code clearer to read,
784 because you can refer to constraints by name.
786 =head2 Slightly Less Important Caveat
788 It is B<always> a good idea to quote your type names.
790 This prevents Perl from trying to execute the call as an indirect
791 object call. This can be an issue when you have a subtype with the
792 same name as a valid class.
796 subtype DateTime => as Object => where { $_->isa('DateTime') };
798 will I<just work>, while this:
801 subtype DateTime => as Object => where { $_->isa('DateTime') };
803 will fail silently and cause many headaches. The simple way to solve
804 this, as well as future proof your subtypes from classes which have
805 yet to have been created, is to quote the type name:
808 subtype 'DateTime', as 'Object', where { $_->isa('DateTime') };
810 =head2 Default Type Constraints
812 This module also provides a simple hierarchy for Perl 5 types, here is
813 that hierarchy represented visually.
837 B<NOTE:> Any type followed by a type parameter C<[`a]> can be
838 parameterized, this means you can say:
840 ArrayRef[Int] # an array of integers
841 HashRef[CodeRef] # a hash of str to CODE ref mappings
842 ScalarRef[Int] # a reference to an integer
843 Maybe[Str] # value may be a string, may be undefined
845 If Moose finds a name in brackets that it does not recognize as an
846 existing type, it assumes that this is a class name, for example
847 C<ArrayRef[DateTime]>.
849 B<NOTE:> Unless you parameterize a type, then it is invalid to include
850 the square brackets. I.e. C<ArrayRef[]> will be treated as a new type
851 name, I<not> as a parameterization of C<ArrayRef>.
853 B<NOTE:> The C<Undef> type constraint for the most part works
854 correctly now, but edge cases may still exist, please use it
857 B<NOTE:> The C<ClassName> type constraint does a complex package
858 existence check. This means that your class B<must> be loaded for this
859 type constraint to pass.
861 B<NOTE:> The C<RoleName> constraint checks a string is a I<package
862 name> which is a role, like C<'MyApp::Role::Comparable'>.
864 =head2 Type Constraint Naming
866 Type name declared via this module can only contain alphanumeric
867 characters, colons (:), and periods (.).
869 Since the types created by this module are global, it is suggested
870 that you namespace your types just as you would namespace your
871 modules. So instead of creating a I<Color> type for your
872 B<My::Graphics> module, you would call the type
873 I<My::Graphics::Types::Color> instead.
875 =head2 Use with Other Constraint Modules
877 This module can play nicely with other constraint modules with some
878 slight tweaking. The C<where> clause in types is expected to be a
879 C<CODE> reference which checks its first argument and returns a
880 boolean. Since most constraint modules work in a similar way, it
881 should be simple to adapt them to work with Moose.
883 For instance, this is how you could use it with
884 L<Declare::Constraints::Simple> to declare a completely new type.
886 type 'HashOfArrayOfObjects',
890 -values => IsArrayRef(IsObject)
894 For more examples see the F<t/examples/example_w_DCS.t> test
897 Here is an example of using L<Test::Deep> and its non-test
898 related C<eq_deeply> function.
900 type 'ArrayOfHashOfBarsAndRandomNumbers',
903 array_each(subhashof({
905 random_number => ignore()
909 For a complete example see the
910 F<t/examples/example_w_TestDeep.t> test file.
912 =head2 Error messages
914 Type constraints can also specify custom error messages, for when they fail to
915 validate. This is provided as just another coderef, which receives the invalid
916 value in C<$_>, as in:
918 subtype 'PositiveInt',
921 message { "$_ is not a positive integer!" };
923 If no message is specified, a default message will be used, which indicates
924 which type constraint was being used and what value failed. If
925 L<Devel::PartialDump> (version 0.14 or higher) is installed, it will be used to
926 display the invalid value, otherwise it will just be printed as is.
930 =head2 Type Constraint Constructors
932 The following functions are used to create type constraints. They
933 will also register the type constraints your create in a global
934 registry that is used to look types up by name.
936 See the L</SYNOPSIS> for an example of how to use these.
940 =item B<< subtype 'Name', as 'Parent', where { } ... >>
942 This creates a named subtype.
944 If you provide a parent that Moose does not recognize, it will
945 automatically create a new class type constraint for this name.
947 When creating a named type, the C<subtype> function should either be
948 called with the sugar helpers (C<where>, C<message>, etc), or with a
949 name and a hashref of parameters:
951 subtype( 'Foo', { where => ..., message => ... } );
953 The valid hashref keys are C<as> (the parent), C<where>, C<message>,
956 =item B<< subtype as 'Parent', where { } ... >>
958 This creates an unnamed subtype and will return the type
959 constraint meta-object, which will be an instance of
960 L<Moose::Meta::TypeConstraint>.
962 When creating an anonymous type, the C<subtype> function should either
963 be called with the sugar helpers (C<where>, C<message>, etc), or with
964 just a hashref of parameters:
966 subtype( { where => ..., message => ... } );
968 =item B<class_type ($class, ?$options)>
970 Creates a new subtype of C<Object> with the name C<$class> and the
971 metaclass L<Moose::Meta::TypeConstraint::Class>.
973 =item B<role_type ($role, ?$options)>
975 Creates a C<Role> type constraint with the name C<$role> and the
976 metaclass L<Moose::Meta::TypeConstraint::Role>.
978 =item B<maybe_type ($type)>
980 Creates a type constraint for either C<undef> or something of the
983 =item B<duck_type ($name, \@methods)>
985 This will create a subtype of Object and test to make sure the value
986 C<can()> do the methods in C<\@methods>.
988 This is intended as an easy way to accept non-Moose objects that
989 provide a certain interface. If you're using Moose classes, we
990 recommend that you use a C<requires>-only Role instead.
992 =item B<duck_type (\@methods)>
994 If passed an ARRAY reference as the only parameter instead of the
995 C<$name>, C<\@methods> pair, this will create an unnamed duck type.
996 This can be used in an attribute definition like so:
1000 isa => duck_type( [qw( get_set )] ),
1003 =item B<enum ($name, \@values)>
1005 This will create a basic subtype for a given set of strings.
1006 The resulting constraint will be a subtype of C<Str> and
1007 will match any of the items in C<\@values>. It is case sensitive.
1008 See the L</SYNOPSIS> for a simple example.
1010 B<NOTE:> This is not a true proper enum type, it is simply
1011 a convenient constraint builder.
1013 =item B<enum (\@values)>
1015 If passed an ARRAY reference as the only parameter instead of the
1016 C<$name>, C<\@values> pair, this will create an unnamed enum. This
1017 can then be used in an attribute definition like so:
1019 has 'sort_order' => (
1021 isa => enum([qw[ ascending descending ]]),
1024 =item B<as 'Parent'>
1026 This is just sugar for the type constraint construction syntax.
1028 It takes a single argument, which is the name of a parent type.
1030 =item B<where { ... }>
1032 This is just sugar for the type constraint construction syntax.
1034 It takes a subroutine reference as an argument. When the type
1035 constraint is tested, the reference is run with the value to be tested
1036 in C<$_>. This reference should return true or false to indicate
1037 whether or not the constraint check passed.
1039 =item B<message { ... }>
1041 This is just sugar for the type constraint construction syntax.
1043 It takes a subroutine reference as an argument. When the type
1044 constraint fails, then the code block is run with the value provided
1045 in C<$_>. This reference should return a string, which will be used in
1046 the text of the exception thrown.
1048 =item B<optimize_as { ... }>
1050 This can be used to define a "hand optimized" version of your
1051 type constraint which can be used to avoid traversing a subtype
1052 constraint hierarchy.
1054 B<NOTE:> You should only use this if you know what you are doing.
1055 All the built in types use this, so your subtypes (assuming they
1056 are shallow) will not likely need to use this.
1058 =item B<< type 'Name', where { } ... >>
1060 This creates a base type, which has no parent.
1062 The C<type> function should either be called with the sugar helpers
1063 (C<where>, C<message>, etc), or with a name and a hashref of
1066 type( 'Foo', { where => ..., message => ... } );
1068 The valid hashref keys are C<where>, C<message>, and C<optimize_as>.
1072 =head2 Type Constraint Utilities
1076 =item B<< match_on_type $value => ( $type => \&action, ... ?\&default ) >>
1078 This is a utility function for doing simple type based dispatching similar to
1079 match/case in OCaml and case/of in Haskell. It is not as featureful as those
1080 languages, nor does not it support any kind of automatic destructuring
1081 bind. Here is a simple Perl pretty printer dispatching over the core Moose
1086 match_on_type $x => (
1091 join ", " => map { $_ . ' => ' . ppprint( $hash->{$_} ) }
1097 '[ ' . ( join ", " => map { ppprint($_) } @$array ) . ' ]';
1099 CodeRef => sub {'sub { ... }'},
1100 RegexpRef => sub { 'qr/' . $_ . '/' },
1101 GlobRef => sub { '*' . B::svref_2object($_)->NAME },
1102 Object => sub { $_->can('to_string') ? $_->to_string : $_ },
1103 ScalarRef => sub { '\\' . ppprint( ${$_} ) },
1105 Str => sub { '"' . $_ . '"' },
1106 Undef => sub {'undef'},
1107 => sub { die "I don't know what $_ is" }
1111 Or a simple JSON serializer:
1115 match_on_type $x => (
1121 map { '"' . $_ . '" : ' . to_json( $hash->{$_} ) }
1127 '[ ' . ( join ", " => map { to_json($_) } @$array ) . ' ]';
1130 Str => sub { '"' . $_ . '"' },
1131 Undef => sub {'null'},
1132 => sub { die "$_ is not acceptable json type" }
1136 The matcher is done by mapping a C<$type> to an C<\&action>. The C<$type> can
1137 be either a string type or a L<Moose::Meta::TypeConstraint> object, and
1138 C<\&action> is a subroutine reference. This function will dispatch on the
1139 first match for C<$value>. It is possible to have a catch-all by providing an
1140 additional subroutine reference as the final argument to C<match_on_type>.
1144 =head2 Type Coercion Constructors
1146 You can define coercions for type constraints, which allow you to
1147 automatically transform values to something valid for the type
1148 constraint. If you ask your accessor to coerce, then Moose will run
1149 the type-coercion code first, followed by the type constraint
1150 check. This feature should be used carefully as it is very powerful
1151 and could easily take off a limb if you are not careful.
1153 See the L</SYNOPSIS> for an example of how to use these.
1157 =item B<< coerce 'Name', from 'OtherName', via { ... } >>
1159 This defines a coercion from one type to another. The C<Name> argument
1160 is the type you are coercing I<to>.
1162 To define multiple coercions, supply more sets of from/via pairs:
1165 from 'OtherName', via { ... },
1166 from 'ThirdName', via { ... };
1168 =item B<from 'OtherName'>
1170 This is just sugar for the type coercion construction syntax.
1172 It takes a single type name (or type object), which is the type being
1175 =item B<via { ... }>
1177 This is just sugar for the type coercion construction syntax.
1179 It takes a subroutine reference. This reference will be called with
1180 the value to be coerced in C<$_>. It is expected to return a new value
1181 of the proper type for the coercion.
1185 =head2 Creating and Finding Type Constraints
1187 These are additional functions for creating and finding type
1188 constraints. Most of these functions are not available for
1189 importing. The ones that are importable as specified.
1193 =item B<find_type_constraint($type_name)>
1195 This function can be used to locate the L<Moose::Meta::TypeConstraint>
1196 object for a named type.
1198 This function is importable.
1200 =item B<register_type_constraint($type_object)>
1202 This function will register a L<Moose::Meta::TypeConstraint> with the
1203 global type registry.
1205 This function is importable.
1207 =item B<normalize_type_constraint_name($type_constraint_name)>
1209 This method takes a type constraint name and returns the normalized
1210 form. This removes any whitespace in the string.
1212 =item B<create_type_constraint_union($pipe_separated_types | @type_constraint_names)>
1214 This can take a union type specification like C<'Int|ArrayRef[Int]'>,
1215 or a list of names. It returns a new
1216 L<Moose::Meta::TypeConstraint::Union> object.
1218 =item B<create_parameterized_type_constraint($type_name)>
1220 Given a C<$type_name> in the form of C<'BaseType[ContainerType]'>,
1221 this will create a new L<Moose::Meta::TypeConstraint::Parameterized>
1222 object. The C<BaseType> must exist already exist as a parameterizable
1225 =item B<create_class_type_constraint($class, $options)>
1227 Given a class name this function will create a new
1228 L<Moose::Meta::TypeConstraint::Class> object for that class name.
1230 The C<$options> is a hash reference that will be passed to the
1231 L<Moose::Meta::TypeConstraint::Class> constructor (as a hash).
1233 =item B<create_role_type_constraint($role, $options)>
1235 Given a role name this function will create a new
1236 L<Moose::Meta::TypeConstraint::Role> object for that role name.
1238 The C<$options> is a hash reference that will be passed to the
1239 L<Moose::Meta::TypeConstraint::Role> constructor (as a hash).
1241 =item B<create_enum_type_constraint($name, $values)>
1243 Given a enum name this function will create a new
1244 L<Moose::Meta::TypeConstraint::Enum> object for that enum name.
1246 =item B<create_duck_type_constraint($name, $methods)>
1248 Given a duck type name this function will create a new
1249 L<Moose::Meta::TypeConstraint::DuckType> object for that enum name.
1251 =item B<find_or_parse_type_constraint($type_name)>
1253 Given a type name, this first attempts to find a matching constraint
1254 in the global registry.
1256 If the type name is a union or parameterized type, it will create a
1257 new object of the appropriate, but if given a "regular" type that does
1258 not yet exist, it simply returns false.
1260 When given a union or parameterized type, the member or base type must
1263 If it creates a new union or parameterized type, it will add it to the
1266 =item B<find_or_create_isa_type_constraint($type_name)>
1268 =item B<find_or_create_does_type_constraint($type_name)>
1270 These functions will first call C<find_or_parse_type_constraint>. If
1271 that function does not return a type, a new type object will
1274 The C<isa> variant will use C<create_class_type_constraint> and the
1275 C<does> variant will use C<create_role_type_constraint>.
1277 =item B<get_type_constraint_registry>
1279 Returns the L<Moose::Meta::TypeConstraint::Registry> object which
1280 keeps track of all type constraints.
1282 =item B<list_all_type_constraints>
1284 This will return a list of type constraint names in the global
1285 registry. You can then fetch the actual type object using
1286 C<find_type_constraint($type_name)>.
1288 =item B<list_all_builtin_type_constraints>
1290 This will return a list of builtin type constraints, meaning those
1291 which are defined in this module. See the L<Default Type Constraints>
1292 section for a complete list.
1294 =item B<export_type_constraints_as_functions>
1296 This will export all the current type constraints as functions into
1297 the caller's namespace (C<Int()>, C<Str()>, etc). Right now, this is
1298 mostly used for testing, but it might prove useful to others.
1300 =item B<get_all_parameterizable_types>
1302 This returns all the parameterizable types that have been registered,
1303 as a list of type objects.
1305 =item B<add_parameterizable_type($type)>
1307 Adds C<$type> to the list of parameterizable types
1313 See L<Moose/BUGS> for details on reporting bugs.