1 package MooseX::Types::Structured;
5 use Moose::Util::TypeConstraints;
6 use MooseX::Meta::TypeConstraint::Structured;
7 use MooseX::Meta::TypeConstraint::Structured::Optional;
8 use MooseX::Types::Structured::OverflowHandler;
9 use MooseX::Types -declare => [qw(Dict Tuple Optional)];
10 use Sub::Exporter -setup => { exports => [ qw(Dict Tuple Optional slurpy) ] };
11 use Devel::PartialDump;
12 use Scalar::Util qw(blessed);
14 our $VERSION = '0.19';
15 our $AUTHORITY = 'cpan:JJNAPIORK';
19 MooseX::Types::Structured - Structured Type Constraints for Moose
23 The following is example usage for this module.
28 use MooseX::Types::Moose qw(Str Int HashRef);
29 use MooseX::Types::Structured qw(Dict Tuple Optional);
31 ## A name has a first and last part, but middle names are not required
36 middle => Optional[Str],
40 ## description is a string field followed by a HashRef of tagged data.
48 ## Remainder of your class attributes and methods
50 Then you can instantiate this class with something like:
52 my $john = Person->new(
56 last => 'Napiorkowski',
59 'A cool guy who loves Perl and Moose.', {
60 married_to => 'Vanessa Li',
68 my $vanessa = Person->new(
73 description => ['A great student!'],
76 But all of these would cause a constraint error for the 'name' attribute:
78 ## Value for 'name' not a HashRef
79 Person->new( name => 'John' );
81 ## Value for 'name' has incorrect hash key and missing required keys
82 Person->new( name => {
86 ## Also incorrect keys
87 Person->new( name => {
92 ## key 'middle' incorrect type, should be a Str not a ArrayRef
93 Person->new( name => {
99 And these would cause a constraint error for the 'description' attribute:
101 ## Should be an ArrayRef
102 Person->new( description => 'Hello I am a String' );
104 ## First element must be a string not a HashRef.
105 Person->new (description => [{
110 Please see the test cases for more examples.
114 A structured type constraint is a standard container L<Moose> type constraint,
115 such as an ArrayRef or HashRef, which has been enhanced to allow you to
116 explicitly name all the allowed type constraints inside the structure. The
119 TypeConstraint[@TypeParameters or %TypeParameters]
121 Where 'TypeParameters' is an array reference or hash references of
122 L<Moose::Meta::TypeConstraint> objects.
124 This type library enables structured type constraints. It is built on top of the
125 L<MooseX::Types> library system, so you should review the documentation for that
126 if you are not familiar with it.
128 =head2 Comparing Parameterized types to Structured types
130 Parameterized constraints are built into core Moose and you are probably already
131 familar with the type constraints 'HashRef' and 'ArrayRef'. Structured types
132 have similar functionality, so their syntax is likewise similar. For example,
133 you could define a parameterized constraint like:
138 which would constrain a value to something like [1,2,3,...] and so on. On the
139 other hand, a structured type constraint explicitly names all it's allowed
140 'internal' type parameter constraints. For the example:
142 subtype StringFollowedByInt,
145 would constrain it's value to things like ['hello', 111] but ['hello', 'world']
146 would fail, as well as ['hello', 111, 'world'] and so on. Here's another
149 package MyApp::Types;
151 use MooseX::Types -declare [qw(StringIntOptionalHashRef)];
152 use MooseX::Types::Moose qw(Str Int);
153 use MooseX::Types::Structured qw(Tuple Optional);
155 subtype StringIntOptionalHashRef,
161 This defines a type constraint that validates values like:
163 ['Hello', 100, {key1 => 'value1', key2 => 'value2'}];
166 Notice that the last type constraint in the structure is optional. This is
167 enabled via the helper Optional type constraint, which is a variation of the
168 core Moose type constraint 'Maybe'. The main difference is that Optional type
169 constraints are required to validate if they exist, while 'Maybe' permits
170 undefined values. So the following example would not validate:
172 StringIntOptionalHashRef->validate(['Hello Undefined', 1000, undef]);
174 Please note the subtle difference between undefined and null. If you wish to
175 allow both null and undefined, you should use the core Moose 'Maybe' type
178 package MyApp::Types;
180 use MooseX::Types -declare [qw(StringIntMaybeHashRef)];
181 use MooseX::Types::Moose qw(Str Int Maybe);
182 use MooseX::Types::Structured qw(Tuple);
184 subtype StringIntMaybeHashRef,
186 Str, Int, Maybe[HashRef]
189 This would validate the following:
191 ['Hello', 100, {key1 => 'value1', key2 => 'value2'}];
192 ['World', 200, undef];
195 Structured constraints are not limited to arrays. You can define a structure
196 against a HashRef with the 'Dict' type constaint as in this example:
198 subtype FirstNameLastName,
204 This would constrain a HashRef that validates something like:
206 {firstname => 'Christopher', lastname => 'Parsons'};
208 but all the following would fail validation:
211 {first => 'Christopher', last => 'Parsons'};
214 {firstname => 'Christopher', lastname => 'Parsons', middlename => 'Allen'};
217 ['Christopher', 'Parsons'];
219 These structures can be as simple or elaborate as you wish. You can even
220 combine various structured, parameterized and simple constraints all together:
225 Dict[name=>Str, age=>Int],
231 [1, {name=>'John', age=>25},[10,11,12]];
233 Please notice how the type parameters can be visually arranged to your liking
234 and to improve the clarity of your meaning. You don't need to run then
235 altogether onto a single line. Additionally, since the 'Dict' type constraint
236 defines a hash constraint, the key order is not meaningful. For example:
247 {key1 => 1, key2 => "Hi!", key3 => 2};
248 {key2 => "Hi!", key1 => 100, key3 => 300};
250 As you would expect, since underneath its just a plain old Perl hash at work.
254 You should exercise some care as to whether or not your complex structured
255 constraints would be better off contained by a real object as in the following
258 package MyApp::MyStruct;
261 ## lazy way to make a bunch of attributes
262 has $_ for qw(full_name age_in_years);
264 package MyApp::MyClass;
267 has person => (isa => 'MyApp::MyStruct');
269 my $instance = MyApp::MyClass->new(
270 person=>MyApp::MyStruct->new(
276 This method may take some additional time to setup but will give you more
277 flexibility. However, structured constraints are highly compatible with this
278 method, granting some interesting possibilities for coercion. Try:
280 package MyApp::MyClass;
285 ## It's recommended your type declarations live in a separate class in order
286 ## to promote reusability and clarity. Inlined here for brevity.
288 use MooseX::Types::DateTime qw(DateTime);
289 use MooseX::Types -declare [qw(MyStruct)];
290 use MooseX::Types::Moose qw(Str Int);
291 use MooseX::Types::Structured qw(Dict);
293 ## Use class_type to create an ISA type constraint if your object doesn't
294 ## inherit from Moose::Object.
295 class_type 'MyApp::MyStruct';
297 ## Just a shorter version really.
299 as 'MyApp::MyStruct';
301 ## Add the coercions.
307 MyApp::MyStruct->new(%$_);
314 my $name = $_->{firstname} .' '. $_->{lastname};
315 my $age = DateTime->now - $_->{dob};
317 MyApp::MyStruct->new(
319 age_in_years=>$age->years,
323 has person => (isa=>MyStruct);
325 This would allow you to instantiate with something like:
327 my $obj = MyApp::MyClass->new( person => {
328 full_name=>'John Napiorkowski',
334 my $obj = MyApp::MyClass->new( person => {
336 firstname=>'Napiorkowski',
337 dob=>DateTime->new(year=>1969),
340 If you are not familiar with how coercions work, check out the L<Moose> cookbook
341 entry L<Moose::Cookbook::Recipe5> for an explanation. The section L</Coercions>
342 has additional examples and discussion.
344 =head2 Subtyping a Structured type constraint
346 You need to exercise some care when you try to subtype a structured type as in
350 as Dict[name => Str];
352 subtype FriendlyPerson,
355 total_friends => Int,
358 This will actually work BUT you have to take care that the subtype has a
359 structure that does not contradict the structure of it's parent. For now the
360 above works, but I will clarify the syntax for this at a future point, so
361 it's recommended to avoid (should not really be needed so much anyway). For
362 now this is supported in an EXPERIMENTAL way. Your thoughts, test cases and
363 patches are welcomed for discussion. If you find a good use for this, please
368 Coercions currently work for 'one level' deep. That is you can do:
383 ## Coerce an object of a particular class
384 from BlessedPersonObject, via {
391 ## Coerce from [$name, $age]
398 ## Coerce from {fullname=>{first=>...,last=>...}, dob=>$DateTimeObject}
399 from Dict[fullname=>Fullname, dob=>DateTime], via {
400 my $age = $_->dob - DateTime->now;
401 my $firstn = $_->{fullname}->{first};
402 my $lastn = $_->{fullname}->{last}
404 name => $_->{fullname}->{first} .' '. ,
409 And that should just work as expected. However, if there are any 'inner'
410 coercions, such as a coercion on 'Fullname' or on 'DateTime', that coercion
411 won't currently get activated.
413 Please see the test '07-coerce.t' for a more detailed example. Discussion on
414 extending coercions to support this welcome on the Moose development channel or
419 Newer versions of L<MooseX::Types> support recursive type constraints. That is
420 you can include a type constraint as a contained type constraint of itself. For
431 This would declare a Person subtype that contains a name and an optional
432 ArrayRef of Persons who are friends as in:
438 { name => 'Vincent' },
442 { name => 'Stephenie' },
449 Please take care to make sure the recursion node is either Optional, or declare
450 a Union with an non recursive option such as:
471 Otherwise you will define a subtype thatis impossible to validate since it is
472 infinitely recursive. For more information about defining recursive types,
473 please see the documentation in L<MooseX::Types> and the test cases.
475 =head1 TYPE CONSTRAINTS
477 This type library defines the following constraints.
479 =head2 Tuple[@constraints]
481 This defines an ArrayRef based constraint which allows you to validate a specific
482 list of contained constraints. For example:
484 Tuple[Int,Str]; ## Validates [1,'hello']
485 Tuple[Str|Object, Int]; ## Validates ['hello', 1] or [$object, 2]
487 The Values of @constraints should ideally be L<MooseX::Types> declared type
488 constraints. We do support 'old style' L<Moose> string based constraints to a
489 limited degree but these string type constraints are considered deprecated.
490 There will be limited support for bugs resulting from mixing string and
491 L<MooseX::Types> in your structures. If you encounter such a bug and really
492 need it fixed, we will required a detailed test case at the minimum.
494 =head2 Dict[%constraints]
496 This defines a HashRef based constraint which allowed you to validate a specific
497 hashref. For example:
499 Dict[name=>Str, age=>Int]; ## Validates {name=>'John', age=>39}
501 The keys in %constraints follow the same rules as @constraints in the above
504 =head2 Optional[$constraint]
506 This is primarily a helper constraint for Dict and Tuple type constraints. What
507 this allows is for you to assert that a given type constraint is allowed to be
508 null (but NOT undefined). If the value is null, then the type constraint passes
509 but if the value is defined it must validate against the type constraint. This
510 makes it easy to make a Dict where one or more of the keys doesn't have to exist
511 or a tuple where some of the values are not required. For example:
513 subtype Name() => as Dict[
516 middle=>Optional[Str],
519 Creates a constraint that validates against a hashref with the keys 'first' and
520 'last' being strings and required while an optional key 'middle' is must be a
521 string if it appears but doesn't have to appear. So in this case both the
524 {first=>'John', middle=>'James', last=>'Napiorkowski'}
525 {first=>'Vanessa', last=>'Li'}
527 If you use the 'Maybe' type constraint instead, your values will also validate
528 against 'undef', which may be incorrect for you.
530 =head1 EXPORTABLE SUBROUTINES
532 This type library makes available for export the following subroutines
536 Structured type constraints by their nature are closed; that is validation will
537 depend on an exact match between your structure definition and the arguments to
538 be checked. Sometimes you might wish for a slightly looser amount of validation.
539 For example, you may wish to validate the first 3 elements of an array reference
540 and allow for an arbitrary number of additional elements. At first thought you
541 might think you could do it this way:
543 # I want to validate stuff like: [1,"hello", $obj, 2,3,4,5,6,...]
544 subtype AllowTailingArgs,
552 However what this will actually validate are structures like this:
554 [10,"Hello", $obj, [11,12,13,...] ]; # Notice element 4 is an ArrayRef
556 In order to allow structured validation of, "and then some", arguments, you can
557 use the L</slurpy> method against a type constraint. For example:
559 use MooseX::Types::Structured qw(Tuple slurpy);
561 subtype AllowTailingArgs,
566 slurpy ArrayRef[Int],
569 This will now work as expected, validating ArrayRef structures such as:
571 [1,"hello", $obj, 2,3,4,5,6,...]
573 A few caveats apply. First, the slurpy type constraint must be the last one in
574 the list of type constraint parameters. Second, the parent type of the slurpy
575 type constraint must match that of the containing type constraint. That means
576 that a Tuple can allow a slurpy ArrayRef (or children of ArrayRefs, including
577 another Tuple) and a Dict can allow a slurpy HashRef (or children/subtypes of
578 HashRef, also including other Dict constraints).
580 Please note the the technical way this works 'under the hood' is that the
581 slurpy keyword transforms the target type constraint into a coderef. Please do
582 not try to create your own custom coderefs; always use the slurpy method. The
583 underlying technology may change in the future but the slurpy keyword will be
586 =head1 ERROR MESSAGES
588 Error reporting has been improved to return more useful debugging messages. Now
589 I will stringify the incoming check value with L<Devel::PartialDump> so that you
590 can see the actual structure that is tripping up validation. Also, I report the
591 'internal' validation error, so that if a particular element inside the
592 Structured Type is failing validation, you will see that. There's a limit to
593 how deep this internal reporting goes, but you shouldn't see any of the "failed
594 with ARRAY(XXXXXX)" that we got with earlier versions of this module.
596 This support is continuing to expand, so it's best to use these messages for
597 debugging purposes and not for creating messages that 'escape into the wild'
598 such as error messages sent to the user.
600 Please see the test '12-error.t' for a more lengthy example. Your thoughts and
601 preferable tests or code patches very welcome!
605 Here are some additional example usage for structured types. All examples can
606 be found also in the 't/examples.t' test. Your contributions are also welcomed.
608 =head2 Normalize a HashRef
610 You need a hashref to conform to a canonical structure but are required accept a
611 bunch of different incoming structures. You can normalize using the Dict type
612 constraint and coercions. This example also shows structured types mixed which
613 other MooseX::Types libraries.
615 package Test::MooseX::Meta::TypeConstraint::Structured::Examples::Normalize;
620 use MooseX::Types::Structured qw(Dict Tuple);
621 use MooseX::Types::DateTime qw(DateTime);
622 use MooseX::Types::Moose qw(Int Str Object);
623 use MooseX::Types -declare => [qw(Name Age Person)];
637 name => "$_->{first} $_->{last}",
647 ## DateTime needs to be inside of single quotes here to disambiguate the
648 ## class package from the DataTime type constraint imported via the
649 ## line "use MooseX::Types::DateTime qw(DateTime);"
651 name => "$_->{fullname}{first} $_->{fullname}{last}",
652 age => ($_->{dob} - 'DateTime'->now)->years,
655 has person => (is=>'rw', isa=>Person, coerce=>1);
657 And now you can instantiate with all the following:
661 name=>'John Napiorkowski',
669 last=>'Napiorkowski',
680 dob => 'DateTime'->new(
688 This technique is a way to support various ways to instantiate your class in a
689 clean and declarative way.
693 my $Optional = MooseX::Meta::TypeConstraint::Structured::Optional->new(
694 name => 'MooseX::Types::Structured::Optional',
695 package_defined_in => __PACKAGE__,
696 parent => find_type_constraint('Item'),
697 constraint => sub { 1 },
698 constraint_generator => sub {
699 my ($type_parameter, @args) = @_;
700 my $check = $type_parameter->_compiled_type_constraint();
703 ## Does the arg exist? Something exists if it's a 'real' value
704 ## or if it is set to undef.
705 if(exists($args[0])) {
706 ## If it exists, we need to validate it
709 ## But it's is okay if the value doesn't exists
716 Moose::Util::TypeConstraints::register_type_constraint($Optional);
717 Moose::Util::TypeConstraints::add_parameterizable_type($Optional);
719 Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
720 MooseX::Meta::TypeConstraint::Structured->new(
721 name => "MooseX::Types::Structured::Tuple" ,
722 parent => find_type_constraint('ArrayRef'),
723 constraint_generator=> sub {
724 ## Get the constraints and values to check
725 my ($type_constraints, $values) = @_;
726 my @type_constraints = defined $type_constraints ?
727 @$type_constraints : ();
729 my $overflow_handler;
730 if($type_constraints[-1] && blessed $type_constraints[-1]
731 && $type_constraints[-1]->isa('MooseX::Types::Structured::OverflowHandler')) {
732 $overflow_handler = pop @type_constraints;
735 my @values = defined $values ? @$values: ();
736 ## Perform the checking
737 while(@type_constraints) {
738 my $type_constraint = shift @type_constraints;
740 my $value = shift @values;
741 unless($type_constraint->check($value)) {
742 $_[2]->{message} = $type_constraint->get_message($value)
747 ## Test if the TC supports null values
748 unless ($type_constraint->is_subtype_of($Optional)) {
749 $_[2]->{message} = $type_constraint->get_message('NULL')
755 ## Make sure there are no leftovers.
757 if($overflow_handler) {
758 return $overflow_handler->check([@values], $_[2]);
760 $_[2]->{message} = "More values than Type Constraints!"
764 } elsif(@type_constraints) {
766 "Not enough values for all defined type constraints. Remaining: ". join(', ',@type_constraints)
776 Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
777 MooseX::Meta::TypeConstraint::Structured->new(
778 name => "MooseX::Types::Structured::Dict",
779 parent => find_type_constraint('HashRef'),
780 constraint_generator=> sub {
781 ## Get the constraints and values to check
782 my ($type_constraints, $values) = @_;
783 my @type_constraints = defined $type_constraints ?
784 @$type_constraints : ();
786 my $overflow_handler;
787 if($type_constraints[-1] && blessed $type_constraints[-1]
788 && $type_constraints[-1]->isa('MooseX::Types::Structured::OverflowHandler')) {
789 $overflow_handler = pop @type_constraints;
791 my (%type_constraints) = @type_constraints;
792 my %values = defined $values ? %$values: ();
793 ## Perform the checking
794 while(%type_constraints) {
795 my($key, $type_constraint) = each %type_constraints;
796 delete $type_constraints{$key};
797 if(exists $values{$key}) {
798 my $value = $values{$key};
799 delete $values{$key};
800 unless($type_constraint->check($value)) {
801 $_[2]->{message} = $type_constraint->get_message($value)
806 ## Test to see if the TC supports null values
807 unless ($type_constraint->is_subtype_of($Optional)) {
808 $_[2]->{message} = $type_constraint->get_message('NULL')
814 ## Make sure there are no leftovers.
816 if($overflow_handler) {
817 return $overflow_handler->check(+{%values});
819 $_[2]->{message} = "More values than Type Constraints!"
823 } elsif(%type_constraints) {
825 "Not enough values for all defined type constraints. Remaining: ". join(', ',values %values)
837 return MooseX::Types::Structured::OverflowHandler->new(
838 type_constraint => $tc,
844 The following modules or resources may be of interest.
846 L<Moose>, L<MooseX::Types>, L<Moose::Meta::TypeConstraint>,
847 L<MooseX::Meta::TypeConstraint::Structured>
851 Here's a list of stuff I would be happy to get volunteers helping with:
853 * All POD examples need test cases in t/documentation/*.t
854 * Want to break out the examples section to a separate cookbook style POD.
855 * Want more examples and best practice / usage guidance for authors
856 * Need to clarify deep coercions,
860 John Napiorkowski <jjnapiork@cpan.org>
864 The following people have contributed to this module and agree with the listed
865 Copyright & license information included below:
867 Florian Ragwitz, <rafl@debian.org>
868 Yuval Kogman, <nothingmuch@woobling.org>
869 Tomas Doran, <bobtfish@bobtfish.net>
871 =head1 COPYRIGHT & LICENSE
873 Copyright 2008-2009, John Napiorkowski <jjnapiork@cpan.org>
875 This program is free software; you can redistribute it and/or modify it under
876 the same terms as Perl itself.