From: Dave Rolsky Date: Thu, 21 Apr 2011 18:54:47 +0000 (-0500) Subject: Docs, Delta, and Changes for inline constraints X-Git-Tag: 2.0100~52 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=7142d232c25d135bf8c0751e78adbf892886d04b;hp=7c047a36d2be28fe82672471038c182d33144a9b;p=gitmo%2FMoose.git Docs, Delta, and Changes for inline constraints --- diff --git a/Changes b/Changes index 1d75086..b5ed29f 100644 --- a/Changes +++ b/Changes @@ -75,6 +75,15 @@ for, noteworthy changes. Class::MOP::Package. This means that anonymous packages are now also possible. (Shawn M Moore, doy) + * Type constraints can now inline their constraint checks. This replaces the + existing hand-optimized constraint feature. + + [DEPRECATIONS] + + * Using a hand-optimized type constraint is now deprecated. In keeping with + our release policy, this won't actually start warning until the 2.0200 + release. + [BUG FIXES] * No longer call XSLoader from multiple places, as this causes issues on diff --git a/lib/Moose/Manual/Delta.pod b/lib/Moose/Manual/Delta.pod index a21bd80..c76aff6 100644 --- a/lib/Moose/Manual/Delta.pod +++ b/lib/Moose/Manual/Delta.pod @@ -18,6 +18,22 @@ feature. If you encounter a problem and have a solution but don't see it documented here, or think we missed an important feature, please send us a patch. +=head1 $NEXT + +=over 4 + +=item Hand-optimized type constraint code is deprecated in favor of inlining + +Moose allows you to provide a hand-optimized version of a type constraint's +subroutine reference. This version allows type constraints to generate inline +code, and you should use this inlining instead of providing a hand-optimized +subroutine reference. + +This affects the C sub exported by +L. Use C instead. + +This will start warning in the 2.0200 release. + =head1 2.0002 =over 4 diff --git a/lib/Moose/Meta/TypeConstraint.pm b/lib/Moose/Meta/TypeConstraint.pm index 2d5bda1..95e89de 100644 --- a/lib/Moose/Meta/TypeConstraint.pm +++ b/lib/Moose/Meta/TypeConstraint.pm @@ -425,8 +425,24 @@ the constraint fails. This is optional. A L object representing the coercions to the type. This is optional. +=item * inlined + +A subroutine which returns a string suitable for inlining this type +constraint. It will be called as a method on the type constraint object, and +will receive a single additional parameter, a variable name to be tested +(usually C<"$_"> or C<"$_[0]">. + +This is optional. + +=item * inline_environment + +A hash reference of variables to close over. The keys are variables names, and +the values are I to the variables. + =item * optimized +B + 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 @@ -524,13 +540,23 @@ exists. Returns true if the type has a coercion. +=item B<< $constraint->can_be_inlined >> + +Returns true if this type constraint can be inlined. A type constraint which +subtypes an inlinable constraint and does not add an additional constraint +"inherits" its parent type's inlining. + =item B<< $constraint->hand_optimized_type_constraint >> +B + Returns the type's hand optimized constraint, as provided to the constructor via the C option. =item B<< $constraint->has_hand_optimized_type_constraint >> +B + Returns true if the type has an optimized constraint. =item B<< $constraint->create_child_type(%options) >> diff --git a/lib/Moose/Util/TypeConstraints.pm b/lib/Moose/Util/TypeConstraints.pm index d7edb02..7947bfd 100644 --- a/lib/Moose/Util/TypeConstraints.pm +++ b/lib/Moose/Util/TypeConstraints.pm @@ -1045,8 +1045,33 @@ constraint fails, then the code block is run with the value provided in C<$_>. This reference should return a string, which will be used in the text of the exception thrown. +=item B + +This can be used to define a "hand optimized" inlinable version of your type +constraint. + +You provide a subroutine which will be called I on a +L object. It will receive a single parameter, the +name of the variable to check, typically something like C<"$_"> or C<"$_[0]">. + +The subroutine should return a code string suitable for inlining. You can +assume that the check will be wrapped in parenthese when it is inlined. + +The inlined code should include any checks that your type's parent type's +do. For example, the C type's inlining sub looks like this: + + sub { + '!ref(' . $_[1] . ') ' + . '&& Scalar::Util::looks_like_number(' . $_[1] . ')' + } + +Note that it checks if the variable is a reference, since it is a subtype of +the C type. + =item B +B instead.> + This can be used to define a "hand optimized" version of your type constraint which can be used to avoid traversing a subtype constraint hierarchy. @@ -1065,7 +1090,7 @@ parameters: type( 'Foo', { where => ..., message => ... } ); -The valid hashref keys are C, C, and C. +The valid hashref keys are C, C, and C. =back diff --git a/xt/release/pod-coverage.t b/xt/release/pod-coverage.t index f3bab77..7e37ada 100644 --- a/xt/release/pod-coverage.t +++ b/xt/release/pod-coverage.t @@ -179,7 +179,7 @@ my %trustme = ( ], 'Moose::Meta::TypeCoercion' => ['compile_type_coercion'], 'Moose::Meta::TypeCoercion::Union' => ['compile_type_coercion'], - 'Moose::Meta::TypeConstraint' => ['compile_type_constraint'], + 'Moose::Meta::TypeConstraint' => [qw( compile_type_constraint inlined )], 'Moose::Meta::TypeConstraint::Class' => [qw( equals is_a_type_of is_a_subtype_of )], 'Moose::Meta::TypeConstraint::Enum' => [qw( constraint equals )],