From: Dave Rolsky Date: Wed, 25 Mar 2009 21:44:38 +0000 (-0500) Subject: docs for MM::TypeConstraint X-Git-Tag: 0.72_01~22 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=cfd006f0b8626746aedb71e4fe8fb7de21ec5497;p=gitmo%2FMoose.git docs for MM::TypeConstraint --- diff --git a/lib/Moose/Meta/TypeConstraint.pm b/lib/Moose/Meta/TypeConstraint.pm index 0318f67..876d80c 100644 --- a/lib/Moose/Meta/TypeConstraint.pm +++ b/lib/Moose/Meta/TypeConstraint.pm @@ -301,118 +301,146 @@ Moose::Meta::TypeConstraint - The Moose Type Constraint metaclass =head1 DESCRIPTION -For the most part, the only time you will ever encounter an -instance of this class is if you are doing some serious deep -introspection. This API should not be considered final, but -it is B that this will matter to a regular -Moose user. - -If you wish to use features at this depth, please come to the -#moose IRC channel on irc.perl.org and we can talk :) +This class represents a single type constraint. Moose's built-in type +constraints, as well as constraints you define, are all store in a +L object as objects of this +class. =head1 METHODS =over 4 -=item B +=item B<< Moose::Meta::TypeConstraint->new(%options) >> -=item B +This creates a new type constraint based on the provided C<%options>: -=item B +=over 8 -This checks the current type against the supplied type (only). -Returns false if the two types are not equal. It also returns false if -you provide the type as a name, and the type name isn't found in the -type registry. +=item * name -=item B +The constraint name. If a name is not provided, it will be set to +"__ANON__". -This checks the current type against the supplied type, or if the -current type is a sub-type of the type name or object supplied. It -also returns false if you provide the type as a name, and the type -name isn't found in the type registry. +=item * parent -=item B +A C object which is the parent type for +the type being created. This is optional. -This checks the current type is a sub-type of the type name or object -supplied. It also returns false if you provide the type as a name, and -the type name isn't found in the type registry. +=item * constraint -=item B +This is the subroutine reference that implements the actual constraint +check. This defaults to a subroutine which always returns true. -=item B +=item * message -This will apply the type-coercion if applicable. +A subroutine reference which is used to generate an error message when +the constraint fails. This is optional. -=item B +=item * coercion -This method will return a true (C<1>) if the C<$value> passes the -constraint, and false (C<0>) otherwise. +A L object representing the coercions to +the type. This is optional. -=item B +=item * optimized -This method is similar to C, but it deals with the error -message. If the C<$value> passes the constraint, C will be -returned. If the C<$value> does B pass the constraint, then -the C will be used to construct a custom error message. +This is a variant of the C parameter that is somehow +optimized. Typically, this means incorporating both the type's +constraint and all of its parents' constraints into a single +subroutine reference. -=item B +=back -The name of the type in the global type registry. +=item B<< $constraint->equals($type_name_or_object) >> -=item B +Returns true if the supplied name or type object is the same as the +current type. -This type's parent type. +=item B<< $constraint->is_subtype_of($type_name_or_object) >> -=item B +Returns true if the supplied name or type object is a parent of the +current type. -Returns true if this type has a parent type. +=item B<< $constraint->is_a_type_of($type_name_or_object) >> -=item B +Returns true if the given type is the same as the current type, or is +a parent of the current type. This is a shortcut for checking +C and C. -Synonym for C. +=item B<< $constraint->coerce($value) >> -=item B +This will attempt to coerce the value to the type. If the type does +have any defined coercions this will throw an error. -Returns this type's constraint. This is the value of C provided -when defining a type. +=item B<< $constraint->check($value) >> -=item B +Returns true if the given value passes the constraint for the type. -Returns true if this type has a message. +=item B<< $constraint->validate($value) >> -=item B +This is similar to C. However, if the type I then the +method returns an explicit C. If the type is not valid, we call +C<< $self->get_message($value) >> internally to generate an error +message. -Returns this type's message. +=item B<< $constraint->name >> -=item B +Returns the type's name, as provided to the constructor. -Generate message for $value. +=item B<< $constraint->parent >> -=item B +Returns the type's parent, as provided to the constructor, if any. -Returns true if this type has a coercion. +=item B<< $constraint->has_parent >> -=item B +Returns true if the type has a parent type. -Returns this type's L if one exists. +=item B<< $constraint->parents >> -=item B +A synonym for C. This is useful for polymorphism with types +that can have more than one parent. -=item B +=item B<< $constraint->constraint >> -=item B +Returns the type's constraint, as provided to the constructor. -=back +=item B<< $constraint->get_message($value) >> -=head2 DEPRECATED METHOD +This generates a method for the given value. If the type does not have +an explicit message, we generate a default message. -=over 4 +=item B<< $constraint->has_message >> + +Returns true if the type has a message. + +=item B<< $constraint->message >> + +Returns the type's message as a subroutine reference. + +=item B<< $constraint->coercion >> + +Returns the type's L object, if one +exists. + +=item B<< $constraint->has_coercion >> + +Returns true if the type has a coercion. + +=item B<< $constraint->hand_optimized_type_constraint >> + +Returns the type's hand optimized constraint, as provided to the +constructor via the C option. + +=item B<< $constraint->has_hand_optimized_type_constraint >> + +Returns true if the type has an optimized constraint. + +=item B<< $constraint->create_child_type(%options) >> -=item B +This returns a new type constraint of the same class using the +provided C<%options>. The C option will be the current type. -This was just bad idea on my part,.. use the L -itself instead. +This method exists so that subclasses of this class can override this +behavior and change how child types are created. =back diff --git a/xt/pod_coverage.t b/xt/pod_coverage.t index 0517bf5..38b0a69 100644 --- a/xt/pod_coverage.t +++ b/xt/pod_coverage.t @@ -69,6 +69,7 @@ my %trustme = ( super with ) ], + 'Moose::Meta::TypeConstraint' => [ 'compile_type_constraint', 'union' ], ); for my $module ( sort @modules ) {