From: Dave Rolsky <autarch@urth.org>
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;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<optimize_as> sub exported by
+L<Moose::Util::TypeConstraints>. Use C<inline_as> 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<Moose::Meta::TypeCoercion> 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<references> to the variables.
+
 =item * optimized
 
+B<This option is deprecated.>
+
 This is a variant of the C<constraint> 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<This method is deprecated.>
+
 Returns the type's hand optimized constraint, as provided to the
 constructor via the C<optimized> option.
 
 =item B<< $constraint->has_hand_optimized_type_constraint >>
 
+B<This method is deprecated.>
+
 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<inline_as { ... }>
+
+This can be used to define a "hand optimized" inlinable version of your type
+constraint.
+
+You provide a subroutine which will be called I<as a method> on a
+L<Moose::Meta::TypeConstraint> 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<Num> 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<Value> type.
+
 =item B<optimize_as { ... }>
 
+B<This feature is deprecated, use C<inline_as> 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<where>, C<message>, and C<optimize_as>.
+The valid hashref keys are C<where>, C<message>, and C<inlined_as>.
 
 =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 )],