X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose.pm;h=f21862d3b6212b9f6261fc7dea364abed4d91458;hb=a917d5ae83dc260c6a84fed0ffdc0d1b70c50266;hp=1ffc14a47a8619ed650915fb8329f89373d2dd1f;hpb=63c52045a6e9e316e13d49b4a944310972426f69;p=gitmo%2FMoose.git

diff --git a/lib/Moose.pm b/lib/Moose.pm
index 1ffc14a..f21862d 100644
--- a/lib/Moose.pm
+++ b/lib/Moose.pm
@@ -5,13 +5,19 @@ use warnings;
 use 5.008;
 
 use Scalar::Util 'blessed';
-use Carp         'confess';
+use Carp         'carp', 'confess';
+use Class::Load  'is_class_loaded';
 
 use Moose::Deprecated;
 use Moose::Exporter;
 
 use Class::MOP;
 
+BEGIN {
+    die "Class::MOP version $Moose::VERSION required--this is version $Class::MOP::VERSION"
+        if $Moose::VERSION && $Class::MOP::VERSION ne $Moose::VERSION;
+}
+
 use Moose::Meta::Class;
 use Moose::Meta::TypeConstraint;
 use Moose::Meta::TypeCoercion;
@@ -61,7 +67,10 @@ sub has {
     Moose->throw_error('Usage: has \'name\' => ( key => value, ... )')
         if @_ % 2 == 1;
 
-    my %options = ( definition_context => Moose::Util::_caller_info(), @_ );
+    my %context = Moose::Util::_caller_info;
+    $context{context} = 'has declaration';
+    $context{type} = 'class';
+    my %options = ( definition_context => \%context, @_ );
     my $attrs = ( ref($name) eq 'ARRAY' ) ? $name : [ ($name) ];
     $meta->add_attribute( $_, %options ) for @$attrs;
 }
@@ -83,8 +92,12 @@ our $SUPER_BODY;
 our @SUPER_ARGS;
 
 sub super {
+    if (@_) {
+        carp 'Arguments passed to super() are ignored';
+    }
+
     # This check avoids a recursion loop - see
-    # t/100_bugs/020_super_recursion.t
+    # t/bugs/super_recursion.t
     return if defined $SUPER_PACKAGE && $SUPER_PACKAGE ne caller();
     return unless $SUPER_BODY; $SUPER_BODY->(@SUPER_ARGS);
 }
@@ -127,21 +140,6 @@ Moose::Exporter->setup_import_methods(
 );
 
 sub init_meta {
-    # This used to be called as a function. This hack preserves
-    # backwards compatibility.
-    if ( $_[0] ne __PACKAGE__ ) {
-        Moose::Deprecated::deprecated(
-            feature => 'Moose::init_meta',
-            message => 'Calling Moose::init_meta as a function is deprecated',
-        );
-
-        return __PACKAGE__->init_meta(
-            for_class  => $_[0],
-            base_class => $_[1],
-            metaclass  => $_[2],
-        );
-    }
-
     shift;
     my %args = @_;
 
@@ -151,6 +149,9 @@ sub init_meta {
     my $metaclass  = $args{metaclass}  || 'Moose::Meta::Class';
     my $meta_name  = exists $args{meta_name} ? $args{meta_name} : 'meta';
 
+    Moose->throw_error("The Metaclass $metaclass must be loaded. (Perhaps you forgot to 'use $metaclass'?)")
+        unless is_class_loaded($metaclass);
+
     Moose->throw_error("The Metaclass $metaclass must be a subclass of Moose::Meta::Class.")
         unless $metaclass->isa('Moose::Meta::Class');
 
@@ -240,7 +241,6 @@ $_->make_immutable(
     Moose::Meta::TypeCoercion::Union
 
     Moose::Meta::Method
-    Moose::Meta::Method::Accessor
     Moose::Meta::Method::Constructor
     Moose::Meta::Method::Destructor
     Moose::Meta::Method::Overridden
@@ -261,9 +261,17 @@ $_->make_immutable(
     Moose::Meta::Role::Application::ToInstance
 );
 
-Moose::Meta::Mixin::AttributeCore->meta->make_immutable(
+$_->make_immutable(
     inline_constructor => 0,
     constructor_name   => undef,
+    # these are Class::MOP accessors, so they need inlining
+    inline_accessors => 1
+    ) for grep { $_->is_mutable }
+    map { $_->meta }
+    qw(
+    Moose::Meta::Method::Accessor
+    Moose::Meta::Method::Delegation
+    Moose::Meta::Mixin::AttributeCore
 );
 
 1;
@@ -423,9 +431,10 @@ hash reference as well.
 
 This will install an attribute of a given C<$name> into the current class. If
 the first parameter is an array reference, it will create an attribute for
-every C<$name> in the list. The C<%options> are the same as those provided by
-L<Class::MOP::Attribute>, in addition to the list below which are provided by
-Moose (L<Moose::Meta::Attribute> to be more specific):
+every C<$name> in the list. The C<%options> will be passed to the constructor
+for L<Moose::Meta::Attribute> (which inherits from L<Class::MOP::Attribute>),
+so the full documentation for the valid options can be found there. These are
+the most commonly used options:
 
 =over 4
 
@@ -456,7 +465,7 @@ for information on how to define a new type, and how to retrieve type meta-data)
 This will attempt to use coercion with the supplied type constraint to change
 the value passed into any accessors or constructors. You B<must> supply a type
 constraint, and that type constraint B<must> define a coercion. See
-L<Moose::Cookbook::Basics::Recipe5> for an example.
+L<Moose::Cookbook::Basics::HTTP_SubtypesAndCoercion> for an example.
 
 =item I<does =E<gt> $role_name>
 
@@ -474,23 +483,15 @@ say anything about the attribute's value, which can be C<undef>.
 
 This will tell the class to store the value of this attribute as a weakened
 reference. If an attribute is a weakened reference, it B<cannot> also be
-coerced. Note that when a weak ref expires, the attribute is still considered
-to be set for purposes of predicate, default, etc.
+coerced. Note that when a weak ref expires, the attribute's value becomes
+undefined, and is still considered to be set for purposes of predicate,
+default, etc.
 
 =item I<lazy =E<gt> (1|0)>
 
 This will tell the class to not create this slot until absolutely necessary.
-If an attribute is marked as lazy it B<must> have a default supplied.
-
-=item I<auto_deref =E<gt> (1|0)>
-
-This tells the accessor to automatically dereference the value of this
-attribute when called in list context.  The accessor will still return a
-reference when called in scalar context.  If this behavior isn't desirable,
-L<Moose::Meta::Attribute::Native::Trait::Array/elements> or
-L<Moose::Meta::Attribute::Native::Trait::Hash/elements> may be a better
-choice.  The I<auto_deref> option is only legal if your I<isa> option is
-either C<ArrayRef> or C<HashRef>.
+If an attribute is marked as lazy it B<must> have a default or builder
+supplied.
 
 =item I<trigger =E<gt> $code>
 
@@ -631,35 +632,27 @@ a HASH ref) of the methods you want mapped.
 
 =back
 
-=item I<metaclass =E<gt> $metaclass_name>
-
-This tells the class to use a custom attribute metaclass for this particular
-attribute. Custom attribute metaclasses are useful for extending the
-capabilities of the I<has> keyword: they are the simplest way to extend the MOP,
-but they are still a fairly advanced topic and too much to cover here. See
-L<Moose::Cookbook::Meta::Recipe1> for more information.
-
-See L<Metaclass and Trait Name Resolution> for details on how a metaclass name
-is resolved to a class name.
-
 =item I<traits =E<gt> [ @role_names ]>
 
 This tells Moose to take the list of C<@role_names> and apply them to the
-attribute meta-object. This is very similar to the I<metaclass> option, but
-allows you to use more than one extension at a time.
+attribute meta-object. Custom attribute metaclass traits are useful for
+extending the capabilities of the I<has> keyword: they are the simplest way to
+extend the MOP, but they are still a fairly advanced topic and too much to
+cover here.
 
 See L<Metaclass and Trait Name Resolution> for details on how a trait name is
 resolved to a role name.
 
-Also see L<Moose::Cookbook::Meta::Recipe3> for a metaclass trait
-example.
+Also see L<Moose::Cookbook::Meta::Labeled_AttributeTrait> for a metaclass
+trait example.
 
 =item I<builder> => Str
 
-The value of this key is the name of the method that will be called to
-obtain the value used to initialize the attribute. See the L<builder
-option docs in Class::MOP::Attribute|Class::MOP::Attribute/builder>
-and/or L<Moose::Cookbook::Basics::Recipe8> for more information.
+The value of this key is the name of the method that will be called to obtain
+the value used to initialize the attribute. See the L<builder option docs in
+Class::MOP::Attribute|Class::MOP::Attribute/builder> and/or
+L<Moose::Cookbook::Basics::BinaryTree_BuilderAndLazyBuild> for more
+information.
 
 =item I<default> => SCALAR | CODE
 
@@ -683,23 +676,9 @@ information.
 Creates a method to perform a basic test to see if a value has been set in the
 attribute. See the L<predicate option docs in
 Class::MOP::Attribute|Class::MOP::Attribute/predicate> for more information.
-Note that the predicate will return true even for a C<weak_ref> attribute whose
-value has expired.
-
-=item I<lazy_build> => (0|1)
-
-Automatically define lazy => 1 as well as builder => "_build_$attr", clearer =>
-"clear_$attr', predicate => 'has_$attr' unless they are already defined.
 
-=item I<initializer> => Str
-
-This may be a method name (referring to a method on the class with
-this attribute) or a CODE ref.  The initializer is used to set the
-attribute value on an instance when the attribute is set during
-instance initialization (but not when the value is being assigned
-to). See the L<initializer option docs in
-Class::MOP::Attribute|Class::MOP::Attribute/initializer> for more
-information.
+Note that the predicate will return true even for a C<weak_ref> attribute
+whose value has expired.
 
 =item I<documentation> => $string
 
@@ -763,54 +742,21 @@ another role.
 
 Aside from where the attributes come from (one from superclass, the other
 from a role), this feature works exactly the same. This feature is restricted
-somewhat, so as to try and force at least I<some> sanity into it. You are only
-allowed to change the following attributes:
+somewhat, so as to try and force at least I<some> sanity into it. Most options work the same, but there are some exceptions:
 
 =over 4
 
-=item I<default>
-
-Change the default value of an attribute.
-
-=item I<coerce>
-
-Change whether the attribute attempts to coerce a value passed to it.
-
-=item I<required>
-
-Change if the attribute is required to have a value.
+=item I<reader>
 
-=item I<documentation>
+=item I<writer>
 
-Change the documentation string associated with the attribute.
+=item I<accessor>
 
-=item I<lazy>
+=item I<clearer>
 
-Change if the attribute lazily initializes the slot.
+=item I<predicate>
 
-=item I<isa>
-
-You I<are> allowed to change the type without restriction.
-
-It is recommended that you use this freedom with caution. We used to
-only allow for extension only if the type was a subtype of the parent's
-type, but we felt that was too restrictive and is better left as a
-policy decision.
-
-=item I<handles>
-
-You are allowed to B<add> a new C<handles> definition, but you are B<not>
-allowed to I<change> one.
-
-=item I<builder>
-
-You are allowed to B<add> a new C<builder> definition, but you are B<not>
-allowed to I<change> one.
-
-=item I<metaclass>
-
-You are allowed to B<add> a new C<metaclass> definition, but you are
-B<not> allowed to I<change> one.
+These options can be added, but cannot override a superclass definition.
 
 =item I<traits>
 
@@ -831,12 +777,6 @@ modifier features that L<Class::MOP> provides. More information on these may be
 found in L<Moose::Manual::MethodModifiers> and the
 L<Class::MOP::Class documentation|Class::MOP::Class/"Method Modifiers">.
 
-=item B<super>
-
-The keyword C<super> is a no-op when called outside of an C<override> method. In
-the context of an C<override> method, it will call the next most appropriate
-superclass method with the same arguments as the original method.
-
 =item B<override ($name, &sub)>
 
 An C<override> method is a way of explicitly saying "I am overriding this
@@ -844,39 +784,43 @@ method from my superclass". You can call C<super> within this method, and
 it will work as expected. The same thing I<can> be accomplished with a normal
 method call and the C<SUPER::> pseudo-package; it is really your choice.
 
-=item B<inner>
+=item B<super>
 
-The keyword C<inner>, much like C<super>, is a no-op outside of the context of
-an C<augment> method. You can think of C<inner> as being the inverse of
-C<super>; the details of how C<inner> and C<augment> work is best described in
-the L<Moose::Cookbook::Basics::Recipe6>.
+The keyword C<super> is a no-op when called outside of an C<override> method. In
+the context of an C<override> method, it will call the next most appropriate
+superclass method with the same arguments as the original method.
 
 =item B<augment ($name, &sub)>
 
 An C<augment> method, is a way of explicitly saying "I am augmenting this
 method from my superclass". Once again, the details of how C<inner> and
-C<augment> work is best described in the L<Moose::Cookbook::Basics::Recipe6>.
+C<augment> work is best described in the
+L<Moose::Cookbook::Basics::Document_AugmentAndInner>.
 
-=item B<confess>
+=item B<inner>
 
-This is the C<Carp::confess> function, and exported here because I use it
-all the time.
+The keyword C<inner>, much like C<super>, is a no-op outside of the context of
+an C<augment> method. You can think of C<inner> as being the inverse of
+C<super>; the details of how C<inner> and C<augment> work is best described in
+the L<Moose::Cookbook::Basics::Document_AugmentAndInner>.
 
 =item B<blessed>
 
-This is the C<Scalar::Util::blessed> function. It is exported here because I
-use it all the time. It is highly recommended that this is used instead of
-C<ref> anywhere you need to test for an object's class name.
+This is the C<Scalar::Util::blessed> function. It is highly recommended that
+this is used instead of C<ref> anywhere you need to test for an object's class
+name.
 
-=back
+=item B<confess>
 
-=head1 METACLASS
+This is the C<Carp::confess> function, and exported here for historical
+reasons.
 
-When you use Moose, you can specify which metaclass to use:
+=back
 
-    use Moose -metaclass => 'My::Meta::Class';
+=head1 METACLASS
 
-You can also specify traits which will be applied to your metaclass:
+When you use Moose, you can specify traits which will be applied to your
+metaclass:
 
     use Moose -traits => 'My::Trait';
 
@@ -904,8 +848,8 @@ The lookup method for metaclasses is the same, except that it looks
 for a class matching B<Moose::Meta::$type::Custom::$metaclass_name>.
 
 If all this is confusing, take a look at
-L<Moose::Cookbook::Meta::Recipe3>, which demonstrates how to create an
-attribute trait.
+L<Moose::Cookbook::Meta::Labeled_AttributeTrait>, which demonstrates how to
+create an attribute trait.
 
 =head1 UNIMPORTING FUNCTIONS
 
@@ -932,39 +876,10 @@ to work. Here is an example:
 
 To learn more about extending Moose, we recommend checking out the
 "Extending" recipes in the L<Moose::Cookbook>, starting with
-L<Moose::Cookbook::Extending::Recipe1>, which provides an overview of
-all the different ways you might extend Moose.
-
-=head2 B<< Moose->init_meta(for_class => $class, base_class => $baseclass, metaclass => $metaclass) >>
-
-The C<init_meta> method sets up the metaclass object for the class
-specified by C<for_class>. This method injects a a C<meta> accessor
-into the class so you can get at this object. It also sets the class's
-superclass to C<base_class>, with L<Moose::Object> as the default.
-
-C<init_meta> returns the metaclass object for C<$class>.
-
-You can specify an alternate metaclass with the C<metaclass> option.
-
-For more detail on this topic, see L<Moose::Cookbook::Extending::Recipe2>.
-
-This method used to be documented as a function which accepted
-positional parameters. This calling style will still work for
-backwards compatibility, but is deprecated.
-
-=head2 B<import>
-
-Moose's C<import> method supports the L<Sub::Exporter> form of C<{into =E<gt> $pkg}>
-and C<{into_level =E<gt> 1}>.
-
-B<NOTE>: Doing this is more or less deprecated. Use L<Moose::Exporter>
-instead, which lets you stack multiple C<Moose.pm>-alike modules
-sanely. It handles getting the exported functions into the right place
-for you.
-
-=head2 B<throw_error>
-
-An alias for C<confess>, used internally by Moose.
+L<Moose::Cookbook::Extending::ExtensionOverview>, which provides an overview of
+all the different ways you might extend Moose. L<Moose::Exporter> and
+L<Moose::Util::MetaRole> are the modules which provide the majority of the
+extension functionality, so reading their documentation should also be helpful.
 
 =head2 The MooseX:: namespace
 
@@ -1011,7 +926,7 @@ unresolvable conflict.
 
 It should be noted that C<super> and C<inner> B<cannot> be used in the same
 method. However, they may be combined within the same class hierarchy; see
-F<t/014_override_augment_inner_super.t> for an example.
+F<t/basics/override_augment_inner_super.t> for an example.
 
 The reason for this is that C<super> is only valid within a method
 with the C<override> modifier, and C<inner> will never be valid within an
@@ -1029,9 +944,9 @@ not (UPDATE: so far so good).
 
 We offer both a mailing list and a very active IRC channel.
 
-The mailing list is L<moose@perl.org>. You must be subscribed to send
+The mailing list is L<mailto:moose@perl.org>. You must be subscribed to send
 a message. To subscribe, send an empty message to
-L<moose-subscribe@perl.org>
+L<mailto:moose-subscribe@perl.org>
 
 You can also visit us at C<#moose> on L<irc://irc.perl.org/#moose>
 This channel is quite active, and questions at all levels (on Moose-related
@@ -1064,9 +979,19 @@ early ideas/feature-requests/encouragement/bug-finding.
 
 =item L<http://www.iinteractive.com/moose>
 
-This is the official web home of Moose, it contains links to our public git repository
-as well as links to a number of talks and articles on Moose and Moose related
-technologies.
+This is the official web home of Moose. It contains links to our public git
+repository, as well as links to a number of talks and articles on Moose and
+Moose related technologies.
+
+=item the L<Moose manual|Moose::Manual>
+
+This is an introduction to Moose which covers most of the basics.
+
+=item Modern Perl, by chromatic
+
+This is an introduction to modern Perl programming, which includes a section on
+Moose. It is available in print and as a free download from
+L<http://onyxneon.com/books/modern_perl/>.
 
 =item The Moose is flying, a tutorial by Randal Schwartz
 
@@ -1078,8 +1003,6 @@ Part 2 - L<http://www.stonehenge.com/merlyn/LinuxMag/col95.html>
 
 See L<http://search.cpan.org/search?query=MooseX::> for extensions.
 
-=item Moose stats on ohloh.net - L<http://www.ohloh.net/projects/moose>
-
 =back
 
 =head2 Books
@@ -1155,14 +1078,60 @@ Dave (autarch) Rolsky E<lt>autarch@urth.orgE<gt>
 
 =head1 CONTRIBUTORS
 
-Aankhen
+Moose is a community project, and as such, involves the work of many, many
+members of the community beyond just the members in the cabal. In particular:
 
-Adam (Alias) Kennedy
+Dave (autarch) Rolsky wrote most of the documentation in L<Moose::Manual>.
+
+John (jgoulah) Goulah wrote L<Moose::Cookbook::Snack::Keywords>.
+
+Jess (castaway) Robinson wrote L<Moose::Cookbook::Snack::Types>.
+
+Aran (bluefeet) Clary Deltac wrote
+L<Moose::Cookbook::Basics::Genome_OverloadingSubtypesAndCoercion>.
 
-Anders (Debolaz) Nor Berle
+Anders (Debolaz) Nor Berle contributed L<Test::Moose> and L<Moose::Util>.
+
+Also, the code in L<Moose::Meta::Attribute::Native> is based on code from the
+L<MooseX::AttributeHelpers> distribution, which had contributions from:
 
 Chris (perigrin) Prather
 
+Cory (gphat) Watson
+
+Evan Carroll
+
+Florian (rafl) Ragwitz
+
+Jason May
+
+Jay Hannah
+
+Jesse (doy) Luehrs
+
+Paul (frodwith) Driver
+
+Robert (rlb3) Boone
+
+Robert Buels
+
+Robert (phaylon) Sedlacek
+
+Shawn (Sartak) Moore
+
+Stevan Little
+
+Tom (dec) Lanyon
+
+Yuval Kogman
+
+Finally, these people also contributed various tests, bug fixes,
+documentation, and features to the Moose codebase:
+
+Aankhen
+
+Adam (Alias) Kennedy
+
 Christian (chansen) Hansen
 
 Cory (gphat) Watson
@@ -1173,16 +1142,12 @@ Eric (ewilhelm) Wilhelm
 
 Evan Carroll
 
-Florian (rafl) Ragwitz
-
 Guillermo (groditi) Roditi
 
 Jason May
 
 Jay Hannah
 
-Jess (castaway) Robinson
-
 Jonathan (jrockway) Rockway
 
 Matt (mst) Trout
@@ -1203,8 +1168,6 @@ Sam (mugwump) Vilain
 
 Scott (konobi) McWhirter
 
-Shawn (Sartak) Moore
-
 Shlomi (rindolf) Fish
 
 Tom (dec) Lanyon