document Moo versus Any::Moose in brief with article link

[gitmo/Moo.git] / lib / Moo.pm

diff --git a/lib/Moo.pm b/lib/Moo.pm
index 35c2df6..2fd9419 100644 (file)
--- a/lib/Moo.pm
+++ b/lib/Moo.pm
@@ -5,7 +5,7 @@ use Moo::_Utils;
 use B 'perlstring';
 use Sub::Defer ();
 
-our $VERSION = '0.091014'; # 0.91.14
+our $VERSION = '1.000000'; # 1.0.0
 $VERSION = eval $VERSION;
 
 require Moo::sification;
@@ -185,7 +185,6 @@ Moo - Minimalist Object Orientation (with Moose compatiblity)
  package Cat::Food;
 
  use Moo;
- use Sub::Quote;
 
  sub feed_lion {
    my $self = shift;
@@ -207,7 +206,7 @@ Moo - Minimalist Object Orientation (with Moose compatiblity)
 
  has pounds => (
    is  => 'rw',
-   isa => quote_sub q{ die "$_[0] is too much cat food!" unless $_[0] < 15 },
+   isa => sub { die "$_[0] is too much cat food!" unless $_[0] < 15 },
  );
 
  1;
@@ -299,6 +298,25 @@ to your code before Moose is loaded, but bear in mind that this switch is
 currently global and turns the mechanism off entirely so don't put this
 in library code.
 
+=head1 MOO VERSUS ANY::MOOSE
+
+L<Any::Moose> will load L<Mouse> normally, and L<Moose> in a program using
+L<Moose> - which theoretically allows you to get the startup time of L<Mouse>
+without disadvantaging L<Moose> users.
+
+Sadly, this doesn't entirely work, since the selection is load order dependent
+- L<Moo>'s metaclass inflation system explained above in L</MOO AND MOOSE> is
+significantly more reliable.
+
+So if you want to write a CPAN module that loads fast or has only pure perl
+dependencies but is also fully usable by L<Moose> users, you should be using
+L<Moo>.
+
+For a full explanation, see the article
+L<http://shadow.cat/blog/matt-s-trout/moo-versus-any-moose> which explains
+the differing strategies in more detail and provides a direct example of
+where L<Moo> succeeds and L<Any::Moose> fails.
+
 =head1 IMPORTED METHODS
 
 =head2 new
@@ -418,7 +436,7 @@ Takes a coderef which is meant to validate the attribute.  Unlike L<Moose> Moo
 does not include a basic type system, so instead of doing C<< isa => 'Num' >>,
 one should do
 
- isa => quote_sub q{
+ isa => sub {
    die "$_[0] is not a number!" unless looks_like_number $_[0]
  },
 
@@ -451,7 +469,7 @@ make L<Moose> happy is fine.
 Takes a coderef which is meant to coerce the attribute.  The basic idea is to
 do something like the following:
 
- coerce => quote_sub q{
+ coerce => sub {
    $_[0] + 1 unless $_[0] % 2
  },
 
@@ -605,6 +623,38 @@ L<Sub::Quote/quote_sub> allows us to create coderefs that are "inlineable,"
 giving us a handy, XS-free speed boost.  Any option that is L<Sub::Quote>
 aware can take advantage of this.
 
+To do this, you can write
+
+  use Moo;
+  use Sub::Quote;
+
+  has foo => (
+    is => quote_sub(q{ die "Not <3" unless $_[0] < 3 })
+  );
+
+which will be inlined as
+
+  do {
+    local @_ = ($_[0]->{foo});
+    die "Not <3" unless $_[0] < 3;
+  }
+
+or to avoid localizing @_,
+
+  has foo => (
+    is => quote_sub(q{ my ($val) = @_; die "Not <3" unless $val < 3 })
+  );
+
+which will be inlined as
+
+  do {
+    my ($val) = ($_[0]->{foo});
+    die "Not <3" unless $val < 3;
+  }
+
+See L<Sub::Quote> for more information, including how to pass lexical
+captures that will also be compiled in to the subroutine.
+
 =head1 INCOMPATIBILITIES WITH MOOSE
 
 There is no built in type system.  C<isa> is verified with a coderef, if you