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