1 package MooseX::Dependent;
9 our $AUTHORITY = 'cpan:JJNAPIORK';
13 MooseX::Dependent - Dependent L<MooseX::Types> constraints and L<Moose> attributes
17 Given some L<MooseX::Types> declared as:
21 use MooseX::Types::Moose qw(Object, Int);
22 use MooseX::Dependent::Types qw(Dependent);
23 use Moosex::Types -declare => [qw(Set UniqueInt)];
28 as class_type("Set::Scalar");
31 as Dependent[Int, Set],
34 return !$set->has($int) ;
37 Assuming 'Set' is a class that creates and manages sets of values (lists of
38 unique but unordered values) with a method '->has($n)', which returns true when
39 $n is a member of the set and which you instantiate like so:
41 my $set_obj = Set->new(1,2,3,4,5); ## 1..5 are member of Set $set_obj'
43 You can then use this $set_obj as a parameter on the previously declared type
44 constraint 'UniqueInt'. This $set_obj become part of the constraint (you can't
45 actually use the constraint without it.)
47 UniqueInt([$set_obj])->check(1); ## Not OK, since one isn't unique in $set_obj
48 UniqueInt([$set_obj])->check('AAA'); ## Not OK, since AAA is not an Int
49 UniqueInt([$set_obj])->check(100); ## OK, since 100 isn't in the set.
51 You can assign the result of a parameterized dependent type to a variable or to
52 another type constraint, as like any other type constraint:
55 my $unique = UniqueInt[$set_obj];
56 $unique->check(10); ## OK
57 $unique->check(2); ## Not OK, '2' is already in the set.
60 subtype UniqueInSet, as UniqueInt[$set_obj];
61 UniqueInSet->check(99); ## OK
62 UniqueInSet->check(3); ## Not OK, '3' is already in the set.
64 However, you can't use a dependent type constraint to check or validate a value
65 until you've parameterized the dependent value:
67 UniqueInt->check(1000); ## Throws exception
68 UniqueInt->validate(1000); ## Throws exception also
70 This is a hard exception, rather than just returning a failure message (via the
71 validate method) or a false boolean (via the check method) since I consider an
72 unparameterized type constraint to be more than just an invalid condition. You
73 will have to catch these in an eval if you think you might have them.
75 Afterward, you can use these dependent types on your L<Moose> based classes
76 and set the dependency target to the value of another attribute or method:
78 TDB: Following is tentative
80 package MyApp::MyClass;
83 use MooseX::Dependent (or maybe a role, or traits...?)
84 use MooseX::Types::Moose qw();
85 use MyApp::Types qw(UniqueInt Set);
87 has people => (is=>'ro', isa=>Set, required=>1);
88 has id => (is=>'ro', dependent_isa=>UniqueInt, required=>1);
90 TODO notes, coerce=>1 should coerce both check value and constraining value
92 Please see the test cases for more examples.
96 A dependent type is a type constraint whose validity is dependent on a second
97 value. You defined the dependent type constraint with a primary type constraint
98 (such as 'Int') a 'constraining' value type constraint (such as a 'Set' object)
99 and a coderef (such as a 'where' clause in your type constraint declaration)
100 which will compare the incoming value to be checked with a value that conforms
101 to the constraining type constraint.
103 Once created, you can use dependent types directly, or in your L<Moose> based
104 attributes and methods (if you are using L<MooseX::Declare>). Attribute traits
105 are available to make it easy to assign the dependency to the value of another
106 attribute or another method.
108 A Dependent Type Constraint should be a 'drop in' replacement for any place you
109 need the parent type (the type constraint being made dependent). For example,
110 if you are expecting an 'Int' type, you can use the 'UniqueInt' type constraint
111 as described above, since a UniqueInt is considered a subtype of Int.
113 =head1 TYPE CONSTRAINTS
115 All type constraints are defined in L<MooseX::Dependent::Types>. Please see
116 that class for more documentation and examples of how to create type constraint
117 libraries using dependent types.
121 =head1 ATTRIBUTE TRAITS
127 L<Moose>, L<Moose::Meta::TypeConstraints>, L<MooseX::Types>
131 John Napiorkowski, C<< <jjnapiork@cpan.org> >>
133 =head1 COPYRIGHT & LICENSE
135 Copyright 2008-2009, John Napiorkowski C<< <jjnapiork@cpan.org> >>
137 This program is free software; you can redistribute it and/or modify
138 it under the same terms as Perl itself.