X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FUtil.pm;h=afa630851503c4bc65ca82c835f40e514e938bb1;hb=6054adafab65254735afde889d03384b0146358a;hp=159b7689fc56b2528978736857ea52b996322c26;hpb=07b0f1a5599bf1a0ed99933200ca27290e9a468a;p=gitmo%2FMoose.git

diff --git a/lib/Moose/Util.pm b/lib/Moose/Util.pm
index 159b768..afa6308 100644
--- a/lib/Moose/Util.pm
+++ b/lib/Moose/Util.pm
@@ -3,24 +3,32 @@ package Moose::Util;
 use strict;
 use warnings;
 
+use Class::Load qw(load_class load_first_existing_class);
+use Data::OptList;
+use Params::Util qw( _STRING );
 use Sub::Exporter;
 use Scalar::Util 'blessed';
-use Carp         'confess';
-use Class::MOP   0.56;
-
-our $VERSION   = '0.51';
-our $AUTHORITY = 'cpan:STEVAN';
+use List::Util qw(first);
+use List::MoreUtils qw(any all);
+use overload ();
+use Try::Tiny;
+use Class::MOP;
 
 my @exports = qw[
-    find_meta 
+    find_meta
     does_role
-    search_class_by_role   
+    search_class_by_role
+    ensure_all_roles
     apply_all_roles
+    with_traits
     get_all_init_args
     get_all_attribute_values
     resolve_metatrait_alias
     resolve_metaclass_alias
     add_method_modifier
+    english_list
+    meta_attribute_alias
+    meta_class_alias
 ];
 
 Sub::Exporter::setup_exporter({
@@ -30,18 +38,19 @@ 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 ...
 
 sub does_role {
     my ($class_or_obj, $role) = @_;
 
+    if (try { $class_or_obj->isa('Moose::Object') }) {
+        return $class_or_obj->does($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);
@@ -49,15 +58,17 @@ sub does_role {
 }
 
 sub search_class_by_role {
-    my ($class_or_obj, $role_name) = @_;
-    
+    my ($class_or_obj, $role) = @_;
+
     my $meta = find_meta($class_or_obj);
 
     return unless defined $meta;
 
+    my $role_name = blessed $role ? $role->name : $role;
+
     foreach my $class ($meta->class_precedence_list) {
-        
-        my $_meta = find_meta($class);        
+
+        my $_meta = find_meta($class);
 
         next unless defined $_meta;
 
@@ -69,35 +80,92 @@ 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;
-    
-    confess "Must specify at least one role to apply to $applicant" unless @_;
-    
-    my $roles = Data::OptList::mkopt([ @_ ]);
-    
-    #use Data::Dumper;
-    #warn Dumper $roles;
-    
-    my $meta = (blessed $applicant ? $applicant : find_meta($applicant));
-    
-    foreach my $role_spec (@$roles) {
-        Class::MOP::load_class($role_spec->[0]);
+    _apply_all_roles($applicant, undef, @_);
+}
+
+sub _apply_all_roles {
+    my $applicant = shift;
+    my $role_filter = shift;
+
+    unless (@_) {
+        require Moose;
+        Moose->throw_error("Must specify at least one role to apply to $applicant");
+    }
+
+    # If @_ contains role meta objects, mkopt will think that they're values,
+    # because they're references.  In other words (roleobj1, roleobj2,
+    # roleobj3) will become [ [ roleobj1, roleobj2 ], [ roleobj3, undef ] ]
+    # -- this is no good.  We'll preprocess @_ first to eliminate the potential
+    # bug.
+    # -- rjbs, 2011-04-08
+    my $roles = Data::OptList::mkopt( [@_], {
+      moniker   => 'role',
+      name_test => sub {
+        ! ref $_[0] or blessed($_[0]) && $_[0]->isa('Moose::Meta::Role')
+      }
+    });
+
+    my @role_metas;
+    foreach my $role (@$roles) {
+        my $meta;
+
+        if ( blessed $role->[0] ) {
+            $meta = $role->[0];
+        }
+        else {
+            load_class( $role->[0] , $role->[1] );
+            $meta = find_meta( $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" );
+        }
+
+        push @role_metas, [ $meta, $role->[1] ];
+    }
+
+    if ( defined $role_filter ) {
+        @role_metas = grep { local $_ = $_->[0]; $role_filter->() } @role_metas;
     }
-    
-    ($_->[0]->can('meta') && $_->[0]->meta->isa('Moose::Meta::Role'))
-        || confess "You can only consume roles, " . $_->[0] . " is not a Moose role"
-            foreach @$roles;
-
-    if (scalar @$roles == 1) {
-        my ($role, $params) = @{$roles->[0]};
-        $role->meta->apply($meta, (defined $params ? %$params : ()));
+
+    return unless @role_metas;
+
+    load_class($applicant)
+        unless blessed($applicant)
+            || Class::MOP::class_of($applicant);
+
+    my $meta = ( blessed $applicant ? $applicant : Moose::Meta::Class->initialize($applicant) );
+
+    if ( scalar @role_metas == 1 ) {
+        my ( $role, $params ) = @{ $role_metas[0] };
+        $role->apply( $meta, ( defined $params ? %$params : () ) );
     }
     else {
-        Moose::Meta::Role->combine(
-            @$roles
-        )->apply($meta);
-    }    
+        Moose::Meta::Role->combine(@role_metas)->apply($meta);
+    }
+}
+
+sub with_traits {
+    my ($class, @roles) = @_;
+    return $class unless @roles;
+    return Moose::Meta::Class->create_anon_class(
+        superclasses => [$class],
+        roles        => \@roles,
+        cache        => 1,
+    )->name;
 }
 
 # instance deconstruction ...
@@ -107,7 +175,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
     };
 }
 
@@ -116,63 +184,298 @@ 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
     };
 }
 
 sub resolve_metatrait_alias {
-    resolve_metaclass_alias( @_, trait => 1 );
+    return resolve_metaclass_alias( @_, trait => 1 );
 }
 
-sub resolve_metaclass_alias {
-    my ( $type, $metaclass_name, %options ) = @_;
+sub _build_alias_package_name {
+    my ($type, $name, $trait) = @_;
+    return 'Moose::Meta::'
+         . $type
+         . '::Custom::'
+         . ( $trait ? 'Trait::' : '' )
+         . $name;
+}
+
+{
+    my %cache;
+
+    sub resolve_metaclass_alias {
+        my ( $type, $metaclass_name, %options ) = @_;
 
-    if ( my $resolved = eval {
-        my $possible_full_name = 'Moose::Meta::' . $type . '::Custom::' . ( $options{trait} ? "Trait::" : "" ) . $metaclass_name;
+        my $cache_key = $type . q{ } . ( $options{trait} ? '-Trait' : '' );
+        return $cache{$cache_key}{$metaclass_name}
+            if $cache{$cache_key}{$metaclass_name};
 
-        Class::MOP::load_class($possible_full_name);
+        my $possible_full_name = _build_alias_package_name(
+            $type, $metaclass_name, $options{trait}
+        );
 
-        $possible_full_name->can('register_implementation')
-            ? $possible_full_name->register_implementation
-            : $possible_full_name;
-    } ) {
-        return $resolved;
-    } else {
-        Class::MOP::load_class($metaclass_name);
-        return $metaclass_name;
+        my $loaded_class = load_first_existing_class(
+            $possible_full_name,
+            $metaclass_name
+        );
+
+        return $cache{$cache_key}{$metaclass_name}
+            = $loaded_class->can('register_implementation')
+            ? $loaded_class->register_implementation
+            : $loaded_class;
     }
 }
 
 sub add_method_modifier {
     my ( $class_or_obj, $modifier_name, $args ) = @_;
-    my $meta                = find_meta($class_or_obj);
+    my $meta
+        = $class_or_obj->can('add_before_method_modifier')
+        ? $class_or_obj
+        : find_meta($class_or_obj);
     my $code                = pop @{$args};
     my $add_modifier_method = 'add_' . $modifier_name . '_method_modifier';
     if ( my $method_modifier_type = ref( @{$args}[0] ) ) {
         if ( $method_modifier_type eq 'Regexp' ) {
-            my @all_methods = $meta->compute_all_applicable_methods;
+            my @all_methods = $meta->get_all_methods;
             my @matched_methods
-                = grep { $_->{name} =~ @{$args}[0] } @all_methods;
-            $meta->$add_modifier_method( $_->{name}, $code )
+                = grep { $_->name =~ @{$args}[0] } @all_methods;
+            $meta->$add_modifier_method( $_->name, $code )
                 for @matched_methods;
         }
+        elsif ($method_modifier_type eq 'ARRAY') {
+            $meta->$add_modifier_method( $_, $code ) for @{$args->[0]};
+        }
+        else {
+            $meta->throw_error(
+                sprintf(
+                    "Methods passed to %s must be provided as a list, arrayref or regex, not %s",
+                    $modifier_name,
+                    $method_modifier_type,
+                )
+            );
+        }
     }
     else {
         $meta->$add_modifier_method( $_, $code ) for @{$args};
     }
 }
 
+sub english_list {
+    my @items = sort @_;
+
+    return $items[0] if @items == 1;
+    return "$items[0] and $items[1]" if @items == 2;
+
+    my $tail = pop @items;
+    my $list = join ', ', @items;
+    $list .= ', and ' . $tail;
+
+    return $list;
+}
+
+sub _caller_info {
+    my $level = @_ ? ($_[0] + 1) : 2;
+    my %info;
+    @info{qw(package file line)} = caller($level);
+    return \%info;
+}
+
+sub _create_alias {
+    my ($type, $name, $trait, $for) = @_;
+    my $package = _build_alias_package_name($type, $name, $trait);
+    Class::MOP::Class->initialize($package)->add_method(
+        register_implementation => sub { $for }
+    );
+}
+
+sub meta_attribute_alias {
+    my ($to, $from) = @_;
+    $from ||= caller;
+    my $meta = Class::MOP::class_of($from);
+    my $trait = $meta->isa('Moose::Meta::Role');
+    _create_alias('Attribute', $to, $trait, $from);
+}
+
+sub meta_class_alias {
+    my ($to, $from) = @_;
+    $from ||= caller;
+    my $meta = Class::MOP::class_of($from);
+    my $trait = $meta->isa('Moose::Meta::Role');
+    _create_alias('Class', $to, $trait, $from);
+}
+
+# XXX - this should be added to Params::Util
+sub _STRINGLIKE0 ($) {
+    return _STRING( $_[0] )
+        || ( defined $_[0]
+        && $_[0] eq q{} )
+        || ( blessed $_[0]
+        && overload::Method( $_[0], q{""} )
+        && length "$_[0]" );
+}
+
+sub _reconcile_roles_for_metaclass {
+    my ($class_meta_name, $super_meta_name) = @_;
+
+    my @role_differences = _role_differences(
+        $class_meta_name, $super_meta_name,
+    );
+
+    # handle the case where we need to fix compatibility between a class and
+    # its parent, but all roles in the class are already also done by the
+    # parent
+    # see t/metaclasses/metaclass_compat_no_fixing_bug.t
+    return $super_meta_name
+        unless @role_differences;
+
+    return Moose::Meta::Class->create_anon_class(
+        superclasses => [$super_meta_name],
+        roles        => [map { $_->name } @role_differences],
+        cache        => 1,
+    )->name;
+}
+
+sub _role_differences {
+    my ($class_meta_name, $super_meta_name) = @_;
+    my @super_role_metas
+        = grep { !$_->isa('Moose::Meta::Role::Composite') }
+               $super_meta_name->meta->can('calculate_all_roles_with_inheritance')
+                   ? $super_meta_name->meta->calculate_all_roles_with_inheritance
+                   : $super_meta_name->meta->can('calculate_all_roles')
+                   ? $super_meta_name->meta->calculate_all_roles
+                   : ();
+    my @role_metas
+        = grep { !$_->isa('Moose::Meta::Role::Composite') }
+               $class_meta_name->meta->can('calculate_all_roles_with_inheritance')
+                   ? $class_meta_name->meta->calculate_all_roles_with_inheritance
+                   : $class_meta_name->meta->can('calculate_all_roles')
+                   ? $class_meta_name->meta->calculate_all_roles
+                   : ();
+    my @differences;
+    for my $role_meta (@role_metas) {
+        push @differences, $role_meta
+            unless any { $_->name eq $role_meta->name } @super_role_metas;
+    }
+    return @differences;
+}
+
+sub _classes_differ_by_roles_only {
+    my ( $self_meta_name, $super_meta_name ) = @_;
+
+    my $common_base_name
+        = _find_common_base( $self_meta_name, $super_meta_name );
+
+    return unless defined $common_base_name;
+
+    my @super_meta_name_ancestor_names
+        = _get_ancestors_until( $super_meta_name, $common_base_name );
+    my @class_meta_name_ancestor_names
+        = _get_ancestors_until( $self_meta_name, $common_base_name );
+
+    return
+        unless all { _is_role_only_subclass($_) }
+        @super_meta_name_ancestor_names,
+        @class_meta_name_ancestor_names;
+
+    return 1;
+}
+
+sub _find_common_base {
+    my ($meta1, $meta2) = map { Class::MOP::class_of($_) } @_;
+    return unless defined $meta1 && defined $meta2;
+
+    # FIXME? This doesn't account for multiple inheritance (not sure
+    # if it needs to though). For example, if somewhere in $meta1's
+    # history it inherits from both ClassA and ClassB, and $meta2
+    # inherits from ClassB & ClassA, does it matter? And what crazy
+    # fool would do that anyway?
+
+    my %meta1_parents = map { $_ => 1 } $meta1->linearized_isa;
+
+    return first { $meta1_parents{$_} } $meta2->linearized_isa;
+}
+
+sub _get_ancestors_until {
+    my ($start_name, $until_name) = @_;
+
+    my @ancestor_names;
+    for my $ancestor_name (Class::MOP::class_of($start_name)->linearized_isa) {
+        last if $ancestor_name eq $until_name;
+        push @ancestor_names, $ancestor_name;
+    }
+    return @ancestor_names;
+}
+
+sub _is_role_only_subclass {
+    my ($meta_name) = @_;
+    my $meta = Class::MOP::Class->initialize($meta_name);
+    my @parent_names = $meta->superclasses;
+
+    # XXX: don't feel like messing with multiple inheritance here... what would
+    # that even do?
+    return unless @parent_names == 1;
+    my ($parent_name) = @parent_names;
+    my $parent_meta = Class::MOP::Class->initialize($parent_name);
+
+    # only get the roles attached to this particular class, don't look at
+    # superclasses
+    my @roles = $meta->can('calculate_all_roles')
+                    ? $meta->calculate_all_roles
+                    : ();
+
+    # it's obviously not a role-only subclass if it doesn't do any roles
+    return unless @roles;
+
+    # loop over all methods that are a part of the current class
+    # (not inherited)
+    for my $method ( $meta->_get_local_methods ) {
+        # always ignore meta
+        next if $method->isa('Class::MOP::Method::Meta');
+        # we'll deal with attributes below
+        next if $method->can('associated_attribute');
+        # if the method comes from a role we consumed, ignore it
+        next if $meta->can('does_role')
+             && $meta->does_role($method->original_package_name);
+        # FIXME - this really isn't right. Just because a modifier is
+        # defined in a role doesn't mean it isn't _also_ defined in the
+        # subclass.
+        next if $method->isa('Class::MOP::Method::Wrapped')
+             && (
+                 (!scalar($method->around_modifiers)
+               || any { $_->has_around_method_modifiers($method->name) } @roles)
+              && (!scalar($method->before_modifiers)
+               || any { $_->has_before_method_modifiers($method->name) } @roles)
+              && (!scalar($method->after_modifiers)
+               || any { $_->has_after_method_modifiers($method->name) } @roles)
+                );
+
+        return 0;
+    }
+
+    # loop over all attributes that are a part of the current class
+    # (not inherited)
+    # FIXME - this really isn't right. Just because an attribute is
+    # defined in a role doesn't mean it isn't _also_ defined in the
+    # subclass.
+    for my $attr (map { $meta->get_attribute($_) } $meta->get_attribute_list) {
+        next if any { $_->has_attribute($attr->name) } @roles;
+
+        return 0;
+    }
+
+    return 1;
+}
+
 1;
 
+# ABSTRACT: Utilities for working with Moose classes
+
 __END__
 
 =pod
 
-=head1 NAME
-
-Moose::Util - Utilities for working with Moose classes
-
 =head1 SYNOPSIS
 
   use Moose::Util qw/find_meta does_role search_class_by_role/;
@@ -188,64 +491,98 @@ 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.
+
+=item B<does_role($class_or_obj, $role_or_obj)>
 
-This will attempt to locate a metaclass for the given C<$class_or_obj>
-and return it.
+Returns true if C<$class_or_obj> does the given C<$role_or_obj>. The role can
+be provided as a name or a L<Moose::Meta::Role> object.
 
-=item B<does_role ($class_or_obj, $role_name)>
+The class must already have a metaclass for this to work. If it doesn't, this
+function simply returns false.
 
-Returns true if C<$class_or_obj> can do the role C<$role_name>.
+=item B<search_class_by_role($class_or_obj, $role_or_obj)>
 
-=item B<search_class_by_role ($class_or_obj, $role_name)>
+Returns the first class in the class's precedence list that does
+C<$role_or_obj>, if any. The role can be either a name or a
+L<Moose::Meta::Role> object.
 
-Returns first class in precedence list that consumed C<$role_name>.
+The class must already have a metaclass for this to work.
 
-=item B<apply_all_roles ($applicant, @roles)>
+=item B<apply_all_roles($applicant, @roles)>
 
-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. 
+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 a list of names or L<Moose::Meta::Role> objects,
+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<with_traits($class_name, @role_names)>
+
+This function creates a new class from C<$class_name> with each of
+C<@role_names> applied. It returns the name of the new class.
 
 =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.
+The name resolution mechanism is covered in
+L<Moose/Metaclass and Trait Name Resolution>.
 
-=item B<add_method_modifier ($class_or_obj, $modifier_name, $args)>
+=item B<meta_class_alias($to[, $from])>
+
+=item B<meta_attribute_alias($to[, $from])>
+
+Create an alias from the class C<$from> (or the current package, if
+C<$from> is unspecified), so that
+L<Moose/Metaclass and Trait Name Resolution> works properly.
+
+=item B<english_list(@items)>
+
+Given a list of scalars, turns them into a proper list in English
+("one and two", "one, two, three, and four"). This is used to help us
+make nicer error messages.
 
 =back
 
@@ -263,28 +600,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 
-exception. If you find a bug please either email me, or add the bug
-to cpan-RT.
-
-=head1 AUTHOR
-
-Anders Nor Berle E<lt>debolaz@gmail.comE<gt>
-
-B<with contributions from:>
-
-Robert (phaylon) Sedlacek
-
-Stevan Little
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2007-2008 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. 
+See L<Moose/BUGS> for details on reporting bugs.
 
 =cut