lib/MooseX/Meta/TypeConstraint/Structured/Optional.pm

   1 package MooseX::Meta::TypeConstraint::Structured::Optional;
   2
   3 use Moose;
   4 use Moose::Meta::TypeConstraint ();
   5
   6 extends 'Moose::Meta::TypeConstraint';
   7 with 'MooseX::Meta::TypeConstraint::Role::Structured';
   8
   9 =head1 NAME
  10
  11 MooseX::Meta::TypeConstraint::Structured::Optional - Structured Type Constraints
  12
  13 =head1 SYNOPSIS
  14
  15 The follow is example usage:
  16
  17     use Moose::Util::TypeConstraints;
  18     use MooseX::Meta::TypeConstraint::Structured::Optional;
  19
  20     my @options = ('Str', 'Int');
  21
  22     my $tc = MooseX::Meta::TypeConstraint::Structured::Optional->new(
  23         name => 'Dict',
  24         parent => find_type_constraint('ArrayRef'),
  25         signature => [map {
  26             find_type_constraint($_);
  27         } @options],
  28     );
  29
  30 =head1 DESCRIPTION
  31
  32 Optional Type Constraints are additional constraints on a 'base' structured
  33 type constraint which extends those constraints with additional optional
  34 fields.  Basically this constraint get's it's constraint logic and args
  35 from a a Structured Type Constraint that contains it.  So basically:
  36
  37         MyType[Int,Str,Optional[Int, Int]]
  38
  39 In this example, the structured Type constraint 'MyType' is the container for
  40 this Optional type called 'Optional'.  What will happen here is that the
  41 MyType will get the first elements for validation and a third one will go
  42 to optional.  Optional will 'inline' itself so that you can validate with:
  43
  44         ->validate(1,'hello',2,3);
  45         ->validate(1,'hello',2);
  46         ->validate(1,'hello');
  47
  48 and not:
  49
  50         ->validate(1,'hello',[2,3]]);
  51         ->validate(1,'hello',[2]]);
  52
  53 as you might expect.  Basically it sucks up args to the length of it's declared
  54 type constraints.
  55
  56 Please keep in mind the type constraint names given in this example are for
  57 example use only and any similarity between them, actual Type Constraints and
  58 package names are coincidental.
  59
  60 =head1 ATTRIBUTES
  61
  62 This class defines the following attributes.
  63
  64 =head2 containing_type_constraint ($structured_type_constraint)
  65
  66 This is the type constraint that contains the Optional parameters.
  67
  68 =cut
  69
  70 has 'containing_type_constraint' => (
  71         is=>'ro',
  72         does=>'MooseX::Meta::TypeConstraint::Role::Structured',
  73         required=>1,
  74 );
  75
  76 =head2 signature
  77
  78 This is a signature of internal contraints for the contents of the outer
  79 contraint container.
  80
  81 =cut
  82
  83 has '+signature' => (isa=>'ArrayRef[Moose::Meta::TypeConstraint]');
  84
  85 =head1 METHODS
  86
  87 This class defines the following methods.
  88
  89 =head2 _normalize_args
  90
  91 Get arguments into a known state or die trying.  Ideally we try to make this
  92 into a HashRef so we can match it up with the L</signature> HashRef.  This gets
  93 delegated to the containing class (L</containing_type_constraint>).
  94
  95 =cut
  96
  97 sub _normalize_args {
  98     return shift->containing_type_constraint->_normalize_args(@_);
  99 }
 100
 101 =head2 constraint
 102
 103 The constraint is basically validating the L</signature> against the incoming
 104
 105 =cut
 106
 107 sub constraint {
 108      return shift->containing_type_constraint->constraint(@_);
 109 }
 110
 111 =head2 parse_parameter_str ($str)
 112
 113 Given a $string that is the parameter information part of a parameterized
 114 constraint, parses it for internal constraint information.  This is delegated
 115 to the containing class.
 116
 117 =cut
 118
 119 sub parse_parameter_str {
 120     return shift->containing_type_constraint->parse_parameter_str(@_);
 121 }
 122
 123
 124 =head2 signature_equals
 125
 126 Check that the signature equals another signature.  Delegated to the containing
 127 class.
 128
 129 =cut
 130
 131 sub signature_equals {
 132     return shift->containing_type_constraint->signature_equals(@_);
 133 }
 134
 135 =head1 AUTHOR
 136
 137 John James Napiorkowski <jjnapiork@cpan.org>
 138
 139 =head1 LICENSE
 140
 141 You may distribute this code under the same terms as Perl itself.
 142
 143 =cut
 144
 145 no Moose; 1;