X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FUtil.pm;h=079ad56d010000a358e041c88c1823e7b6807b81;hb=7250a96871ad8dd771caa728ac9a3051fc38643b;hp=3f6c00c7ccb2340a04983cc32ffe8c862da86054;hpb=df8260e9a27a9d7532a21525223975fcf8e26562;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Util.pm b/lib/Moose/Util.pm
index 3f6c00c..079ad56 100644
--- a/lib/Moose/Util.pm
+++ b/lib/Moose/Util.pm
@@ -3,18 +3,20 @@ package Moose::Util;
 use strict;
 use warnings;
 
+use Data::OptList;
 use Sub::Exporter;
 use Scalar::Util 'blessed';
 use Class::MOP   0.60;
 
-our $VERSION   = '0.63';
+our $VERSION   = '0.88';
 $VERSION = eval $VERSION;
 our $AUTHORITY = 'cpan:STEVAN';
 
 my @exports = qw[
-    find_meta 
+    find_meta
     does_role
-    search_class_by_role   
+    search_class_by_role
+    ensure_all_roles
     apply_all_roles
     get_all_init_args
     get_all_attribute_values
@@ -31,10 +33,7 @@ Sub::Exporter::setup_exporter({
 
 ## some utils for the utils ...
 
-sub find_meta { 
-    return unless $_[0];
-    return Class::MOP::get_metaclass_by_name(blessed($_[0]) || $_[0]);
-}
+sub find_meta { Class::MOP::class_of(@_) }
 
 ## the functions ...
 
@@ -42,7 +41,7 @@ sub does_role {
     my ($class_or_obj, $role) = @_;
 
     my $meta = find_meta($class_or_obj);
-    
+
     return unless defined $meta;
     return unless $meta->can('does_role');
     return 1 if $meta->does_role($role);
@@ -51,14 +50,14 @@ sub does_role {
 
 sub search_class_by_role {
     my ($class_or_obj, $role_name) = @_;
-    
+
     my $meta = find_meta($class_or_obj);
 
     return unless defined $meta;
 
     foreach my $class ($meta->class_precedence_list) {
-        
-        my $_meta = find_meta($class);        
+
+        my $_meta = find_meta($class);
 
         next unless defined $_meta;
 
@@ -70,28 +69,54 @@ sub search_class_by_role {
     return;
 }
 
+# this can possibly behave in unexpected ways because the roles being composed
+# before being applied could differ from call to call; I'm not sure if or how
+# to document this possible quirk.
+sub ensure_all_roles {
+    my $applicant = shift;
+    _apply_all_roles($applicant, sub { !does_role($applicant, $_) }, @_);
+}
+
 sub apply_all_roles {
     my $applicant = shift;
+    _apply_all_roles($applicant, undef, @_);
+}
+
+sub _apply_all_roles {
+    my $applicant = shift;
+    my $role_filter = shift;
 
-    Moose->throw_error("Must specify at least one role to apply to $applicant") unless @_;
+    unless (@_) {
+        require Moose;
+        Moose->throw_error("Must specify at least one role to apply to $applicant");
+    }
 
     my $roles = Data::OptList::mkopt( [@_] );
 
-    my $meta = ( blessed $applicant ? $applicant : find_meta($applicant) );
+    foreach my $role (@$roles) {
+        Class::MOP::load_class( $role->[0] );
+        my $meta = Class::MOP::class_of( $role->[0] );
+
+        unless ($meta && $meta->isa('Moose::Meta::Role') ) {
+            require Moose;
+            Moose->throw_error( "You can only consume roles, "
+                    . $role->[0]
+                    . " is not a Moose role" );
+        }
+    }
 
-    foreach my $role_spec (@$roles) {
-        Class::MOP::load_class( $role_spec->[0] );
+    if ( defined $role_filter ) {
+        @$roles = grep { local $_ = $_->[0]; $role_filter->() } @$roles;
     }
 
-    ( $_->[0]->can('meta') && $_->[0]->meta->isa('Moose::Meta::Role') )
-        || Moose->throw_error("You can only consume roles, "
-        . $_->[0]
-        . " is not a Moose role")
-        foreach @$roles;
+    return unless @$roles;
+
+    my $meta = ( blessed $applicant ? $applicant : find_meta($applicant) );
 
     if ( scalar @$roles == 1 ) {
         my ( $role, $params ) = @{ $roles->[0] };
-        $role->meta->apply( $meta, ( defined $params ? %$params : () ) );
+        my $role_meta = Class::MOP::class_of($role);
+        $role_meta->apply( $meta, ( defined $params ? %$params : () ) );
     }
     else {
         Moose::Meta::Role->combine( @$roles )->apply($meta);
@@ -105,7 +130,7 @@ sub get_all_attribute_values {
     return +{
         map { $_->name => $_->get_value($instance) }
             grep { $_->has_value($instance) }
-                $class->compute_all_applicable_attributes
+                $class->get_all_attributes
     };
 }
 
@@ -114,8 +139,8 @@ sub get_all_init_args {
     return +{
         map { $_->init_arg => $_->get_value($instance) }
             grep { $_->has_value($instance) }
-                grep { defined($_->init_arg) } 
-                    $class->compute_all_applicable_attributes
+                grep { defined($_->init_arg) }
+                    $class->get_all_attributes
     };
 }
 
@@ -134,7 +159,7 @@ sub resolve_metatrait_alias {
             if $cache{$cache_key}{$metaclass_name};
 
         my $possible_full_name
-            = 'Moose::Meta::' 
+            = 'Moose::Meta::'
             . $type
             . '::Custom::'
             . ( $options{trait} ? "Trait::" : "" )
@@ -184,6 +209,13 @@ sub english_list {
     return $list;
 }
 
+sub _caller_info {
+    my $level = @_ ? ($_[0] + 1) : 2;
+    my %info;
+    @info{qw(package file line)} = caller($level);
+    return \%info;
+}
+
 1;
 
 __END__
@@ -209,64 +241,76 @@ Moose::Util - Utilities for working with Moose classes
 
 =head1 DESCRIPTION
 
-This is a set of utility functions to help working with Moose classes, and 
-is used internally by Moose itself. The goal is to provide useful functions
-that for both Moose users and Moose extenders (MooseX:: authors).
-
-This is a relatively new addition to the Moose toolchest, so ideas, 
-suggestions and contributions to this collection are most welcome. 
-See the L<TODO> section below for a list of ideas for possible functions 
-to write.
+This module provides a set of utility functions. Many of these
+functions are intended for use in Moose itself or MooseX modules, but
+some of them may be useful for use in your own code.
 
 =head1 EXPORTED FUNCTIONS
 
 =over 4
 
-=item B<find_meta ($class_or_obj)>
+=item B<find_meta($class_or_obj)>
+
+This method takes a class name or object and attempts to find a
+metaclass for the class, if one exists. It will B<not> create one if it
+does not yet exist.
 
-This will attempt to locate a metaclass for the given C<$class_or_obj>
-and return it.
+=item B<does_role($class_or_obj, $role_name)>
 
-=item B<does_role ($class_or_obj, $role_name)>
+Returns true if C<$class_or_obj> does the given C<$role_name>.
 
-Returns true if C<$class_or_obj> can do the role C<$role_name>.
+The class must already have a metaclass for this to work.
 
-=item B<search_class_by_role ($class_or_obj, $role_name)>
+=item B<search_class_by_role($class_or_obj, $role_name)>
 
-Returns first class in precedence list that consumed C<$role_name>.
+Returns the first class in the class's precedence list that does
+C<$role_name>, if any.
 
-=item B<apply_all_roles ($applicant, @roles)>
+The class must already have a metaclass for this to work.
 
-Given an C<$applicant> (which can somehow be turned into either a 
-metaclass or a metarole) and a list of C<@roles> this will do the 
-right thing to apply the C<@roles> to the C<$applicant>. This is 
-actually used internally by both L<Moose> and L<Moose::Role>, and the
-C<@roles> will be pre-processed through L<Data::OptList::mkopt>
-to allow for the additional arguments to be passed. 
+=item B<apply_all_roles($applicant, @roles)>
+
+This function applies one or more roles to the given C<$applicant> The
+applicant can be a role name, class name, or object.
+
+The C<$applicant> must already have a metaclass object.
+
+The list of C<@roles> should be a list of names, each of which can be
+followed by an optional hash reference of options (C<excludes> and
+C<alias>).
+
+=item B<ensure_all_roles($applicant, @roles)>
+
+This function is similar to L</apply_all_roles>, but only applies roles that
+C<$applicant> does not already consume.
 
 =item B<get_all_attribute_values($meta, $instance)>
 
-Returns the values of the C<$instance>'s fields keyed by the attribute names.
+Returns a hash reference containing all of the C<$instance>'s
+attributes. The keys are attribute names.
 
 =item B<get_all_init_args($meta, $instance)>
 
-Returns a hash reference where the keys are all the attributes' C<init_arg>s
-and the values are the instance's fields. Attributes without an C<init_arg>
-will be skipped.
+Returns a hash reference containing all of the C<init_arg> values for
+the instance's attributes. The values are the associated attribute
+values. If an attribute does not have a defined C<init_arg>, it is
+skipped.
+
+This could be useful in cloning an object.
 
 =item B<resolve_metaclass_alias($category, $name, %options)>
 
 =item B<resolve_metatrait_alias($category, $name, %options)>
 
-Resolve a short name like in e.g.
+Resolves a short name to a full class name. Short names are often used
+when specifying the C<metaclass> or C<traits> option for an attribute:
 
     has foo => (
         metaclass => "Bar",
     );
 
-to a full class name.
-
-=item B<add_method_modifier ($class_or_obj, $modifier_name, $args)>
+The name resolution mechanism is covered in L<Moose/Trait Name
+Resolution>.
 
 =item B<english_list(@items)>
 
@@ -290,7 +334,7 @@ Here is a list of possible functions to write
 
 =head1 BUGS
 
-All complex software has bugs lurking in it, and this module is no 
+All complex software has bugs lurking in it, and this module is no
 exception. If you find a bug please either email me, or add the bug
 to cpan-RT.
 
@@ -306,12 +350,12 @@ Stevan Little
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2007-2008 by Infinity Interactive, Inc.
+Copyright 2007-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. 
+it under the same terms as Perl itself.
 
 =cut