lib/MooseX/Types/Dependent.pm

   1 package MooseX::Types::Dependent;
   2
   3 use 5.008;
   4
   5 use Moose::Util::TypeConstraints;
   6 use MooseX::Meta::TypeConstraint::Dependent;
   7 use MooseX::Types -declare => [qw(Depending)];
   8
   9 our $VERSION = '0.01';
  10 our $AUTHORITY = 'cpan:JJNAPIORK';
  11
  12 =head1 NAME
  13
  14 MooseX::Types::Dependent - L<MooseX::Types> constraints that depend on values.
  15
  16 =head1 SYNOPSIS
  17
  18     subtype UniqueInt,
  19       as Depending[
  20         Int,
  21         sub {
  22           shift->exists(shift) ? 0:1;
  23         },
  24         Set,
  25       ];
  26
  27     subtype UniqueInt,
  28       as Depending {
  29         shift->exists(shift) ? 0:1;
  30       } [Int, Set];
  31
  32 Please see the test cases for more examples.
  33
  34 =head1 DEFINITIONS
  35
  36 The following is a list of terms used in this documentation.
  37
  38 =head2 Dependent Type Constraint
  39
  40 =head2 Check Value
  41
  42 =head2 Constraining Type Constraint
  43
  44 =head2 Constraining Value
  45
  46 =head1 DESCRIPTION
  47
  48 A dependent type is a type constraint whose validity is dependent on a second
  49 value.  You defined the dependent type constraint with a primary type constraint
  50 (such as 'Int') a 'constraining' value type constraint (such as a Set object)
  51 and a coderef which will compare the incoming value to be checked with a value
  52 that conforms to the constraining type constraint.  Typically there should be a
  53 comparision operator between the check value and the constraining value
  54
  55 =head2 Subtyping a Dependent type constraints
  56
  57 TDB: Need discussion and examples.
  58
  59 =head2 Coercions
  60
  61 TBD: Need discussion and example of coercions working for both the
  62 constrainted and dependent type constraint.
  63
  64 =head2 Recursion
  65
  66 Newer versions of L<MooseX::Types> support recursive type constraints.  That is
  67 you can include a type constraint as a contained type constraint of itself.
  68 Recursion is support in both the dependent and constraining type constraint. For
  69 example:
  70
  71 =head1 TYPE CONSTRAINTS
  72
  73 This type library defines the following constraints.
  74
  75 =head2 Depending[$dependent_tc, $codref, $constraining_tc]
  76
  77 Create a subtype of $dependent_tc that is constrainted by a value that is a
  78 valid $constraining_tc using $coderef.  For example:
  79
  80     subtype GreaterThanInt,
  81       as Depending[
  82         Int,
  83         sub {
  84           my($constraining_value, $check_value) = @_;
  85           return $constraining_value > $check_value ? 1:0;
  86         },
  87         Int,
  88       ];
  89
  90 Note that the coderef is passed the constraining value and the check value as an
  91 Array NOT an ArrayRef.
  92
  93 This would create a type constraint that takes an integer and checks it against
  94 a second integer, requiring that the check value is greater.  For example:
  95
  96     GreaterThanInt->check([5,10]);  ## Fails, 5 is less than 10
  97     GreaterThanInt->check(['a',10]); ## Fails, 'a' is not an Int.
  98     GreaterThanInt->check([5,'b']); ## Fails, 'b' is not an Int either.
  99     GreaterThanInt->check([10,5]); ## Success, 10 is greater than 5.
 100
 101 =head1 EXAMPLES
 102
 103 Here are some additional example usage for structured types.  All examples can
 104 be found also in the 't/examples.t' test.  Your contributions are also welcomed.
 105
 106 TBD
 107
 108 =cut
 109
 110 Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
 111     MooseX::Meta::TypeConstraint::Dependent->new(
 112         name => "MooseX::Types::Dependent::Depending" ,
 113         parent => find_type_constraint('ArrayRef'),
 114         constraint_generator=> sub {
 115                         my ($dependent_val, $callback, $constraining_val) = @_;
 116                         return $callback->($dependent_val, $constraining_val);
 117         },
 118     )
 119 );
 120
 121 =head1 SEE ALSO
 122
 123 The following modules or resources may be of interest.
 124
 125 L<Moose>, L<MooseX::Types>, L<Moose::Meta::TypeConstraint>,
 126 L<MooseX::Meta::TypeConstraint::Dependent>
 127
 128 =head1 TODO
 129
 130 Here's a list of stuff I would be happy to get volunteers helping with:
 131
 132 =over 4
 133
 134 =item Examples
 135
 136 Examples of useful code with both POD and ideally a test case to show it
 137 working.
 138
 139 =back
 140
 141 =head1 AUTHOR
 142
 143 John Napiorkowski, C<< <jjnapiork@cpan.org> >>
 144
 145 =head1 COPYRIGHT & LICENSE
 146
 147 This program is free software; you can redistribute it and/or modify
 148 it under the same terms as Perl itself.
 149
 150 =cut
 151
 152 1;