document that auto_deref is wantarray-based

[gitmo/Moose.git] / lib / Moose / Manual / Attributes.pod

diff --git a/lib/Moose/Manual/Attributes.pod b/lib/Moose/Manual/Attributes.pod
index 98bfd44..66d9364 100644 (file)
--- a/lib/Moose/Manual/Attributes.pod
+++ b/lib/Moose/Manual/Attributes.pod
@@ -1,8 +1,10 @@
-=pod
+package Moose::Manual::Attributes;
+
+# ABSTRACT: Object attributes with Moose
 
-=head1 NAME
+__END__
 
-Moose::Manual::Attributes - Object attributes with Moose
+=pod
 
 =head1 INTRODUCTION
 
@@ -59,7 +61,7 @@ read and write the value of that attribute for an object.
 
 By default, the accessor method has the same name as the attribute. If
 you declared your attribute as C<ro> then your accessor will be
-read-only. If you declared it read-write, you get a read-write
+read-only. If you declared it as C<rw>, you get a read-write
 accessor. Simple.
 
 Given our C<Person> example above, we now have a single C<first_name>
@@ -394,6 +396,15 @@ C<Scalar::Util::weaken> whenever the attribute is set:
 This is very useful when you're building objects that may contain
 circular references.
 
+When the object in a weak references goes out of scope, the attribute's value
+will become C<undef> "behind the scenes". This is done by the Perl interpreter
+directly, so Moose does not see this change. This means that triggers don't
+fire, coercions aren't applied, etc.
+
+The attribute is not cleared, so a predicate method for that attribute will
+still return true. Similarly, when the attribute is next accessed, a default
+value will not be generated.
+
 =head2 Triggers
 
 A C<trigger> is a subroutine that is called whenever the attribute is
@@ -414,7 +425,7 @@ set:
       }
 
       $msg .= " - size is now $size";
-      warn $msg.
+      warn $msg;
   }
 
 The trigger is called I<after> an attribute's value is set. It is
@@ -430,7 +441,7 @@ writing). Second, it is also called when an attribute's value is
 passed to the constructor.
 
 However, triggers are I<not> called when an attribute is populated
-from a C<default> or C<builder>
+from a C<default> or C<builder>.
 
 =head2 Attribute types
 
@@ -497,10 +508,10 @@ attribute metaclasses and traits. See L<Moose::Manual::MooseX> for
 some examples. You can also write your own metaclasses and traits. See
 the "Meta" and "Extending" recipes in L<Moose::Cookbook> for examples.
 
-=head2 Native Traits
+=head2 Native Delegations
 
-The Native Traits feature allows standard Perl data structures to be treated
-as if they were objects for the purposes of delegation.
+Native delegations allow you to delegate to standard Perl data structures as
+if they were objects.
 
 For example, we can pretend that an array reference has methods like
 C<push()>, C<shift()>, C<map()>, C<count()>, and more.
@@ -519,25 +530,7 @@ C<push()>, C<shift()>, C<map()>, C<count()>, and more.
       },
   );
 
-Moose includes the following native traits:
-
-=over 4
-
-=item * L<Array|Moose::Meta::Attribute::Native::Trait::Array>
-
-=item * L<Bool|Moose::Meta::Attribute::Native::Trait::Bool>
-
-=item * L<Code|Moose::Meta::Attribute::Native::Trait::Code>
-
-=item * L<Counter|Moose::Meta::Attribute::Native::Trait::Counter>
-
-=item * L<Hash|Moose::Meta::Attribute::Native::Trait::Hash>
-
-=item * L<Number|Moose::Meta::Attribute::Native::Trait::Number>
-
-=item * L<String|Moose::Meta::Attribute::Native::Trait::String>
-
-=back
+See L<Moose::Manual::Delegation> for more details.
 
 =head1 ATTRIBUTE INHERITANCE
 
@@ -613,16 +606,18 @@ it.
 
 If your attribute is an array reference or hash reference, the
 C<auto_deref> option will make Moose dereference the value when it is
-returned from the reader method:
+returned from the reader method I<in list context>:
 
   my %map = $object->mapping;
 
 This option only works if your attribute is explicitly typed as an
-C<ArrayRef> or C<HashRef>.
+C<ArrayRef> or C<HashRef>.  When the reader is called in I<scalar> context,
+the reference itself is returned.
 
 However, we recommend that you use L<Moose::Meta::Attribute::Native> traits
 for these types of attributes, which gives you much more control over how
-they are accessed and manipulated.
+they are accessed and manipulated. See also
+L<Moose::Manual::BestPractices#Use_Moose::Meta::Attribute::Native_traits_instead_of_auto_deref>.
 
 =head2 Initializer
 
@@ -630,17 +625,4 @@ Moose provides an attribute option called C<initializer>. This is called when
 the attribute's value is being set in the constructor, and lets you change the
 value before it is set.
 
-=head1 AUTHOR
-
-Dave Rolsky E<lt>autarch@urth.orgE<gt>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2009 by Infinity Interactive, Inc.
-
-L<http://www.iinteractive.com>
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
 =cut