package Moose::Util;
-use Exporter qw/import/;
-use Scalar::Util qw/blessed/;
-
use strict;
use warnings;
-our $VERSION = '0.01';
+use Data::OptList;
+use Sub::Exporter;
+use Scalar::Util 'blessed';
+use Class::MOP 0.60;
+
+our $VERSION = '0.84';
+$VERSION = eval $VERSION;
+our $AUTHORITY = 'cpan:STEVAN';
+
+my @exports = qw[
+ find_meta
+ does_role
+ search_class_by_role
+ ensure_all_roles
+ apply_all_roles
+ get_all_init_args
+ get_all_attribute_values
+ resolve_metatrait_alias
+ resolve_metaclass_alias
+ add_method_modifier
+ english_list
+];
+
+Sub::Exporter::setup_exporter({
+ exports => \@exports,
+ groups => { all => \@exports }
+});
+
+## some utils for the utils ...
+
+sub find_meta { Class::MOP::class_of(@_) }
+
+## the functions ...
+
+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);
+ return;
+}
+
+sub search_class_by_role {
+ my ($class_or_obj, $role_name) = @_;
-our $AUTHORITY = 'cpan:BERLE';
+ my $meta = find_meta($class_or_obj);
-our @EXPORT_OK = qw/can_role search_class_by_role/;
+ return unless defined $meta;
-sub can_role {
- my ($class,$does) = @_;
+ foreach my $class ($meta->class_precedence_list) {
- return ((!ref $class && eval { $class->isa ('UNIVERSAL') }) || Scalar::Util::blessed ($class))
- && $class->can ('does')
- && $class->does ($does);
-}
+ my $_meta = find_meta($class);
-sub search_class_by_role {
- my ($obj, $role_name) = @_;
+ next unless defined $_meta;
- for my $class ($obj->meta->class_precedence_list) {
- for my $role (@{ $class->meta->roles || [] }) {
+ foreach my $role (@{ $_meta->roles || [] }) {
return $class if $role->name eq $role_name;
}
}
- return undef;
+ 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, sub { 1 }, @_);
+}
+
+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");
+ }
+
+ my $roles = Data::OptList::mkopt( [@_] );
+
+ 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" );
+ }
+ }
+
+ @$roles = grep { local $_ = $_->[0]; $role_filter->() } @$roles;
+
+ return unless @$roles;
+
+ my $meta = ( blessed $applicant ? $applicant : find_meta($applicant) );
+
+ if ( scalar @$roles == 1 ) {
+ my ( $role, $params ) = @{ $roles->[0] };
+ my $role_meta = Class::MOP::class_of($role);
+ $role_meta->apply( $meta, ( defined $params ? %$params : () ) );
+ }
+ else {
+ Moose::Meta::Role->combine( @$roles )->apply($meta);
+ }
+}
+
+# instance deconstruction ...
+
+sub get_all_attribute_values {
+ my ($class, $instance) = @_;
+ return +{
+ map { $_->name => $_->get_value($instance) }
+ grep { $_->has_value($instance) }
+ $class->get_all_attributes
+ };
+}
+
+sub get_all_init_args {
+ my ($class, $instance) = @_;
+ return +{
+ map { $_->init_arg => $_->get_value($instance) }
+ grep { $_->has_value($instance) }
+ grep { defined($_->init_arg) }
+ $class->get_all_attributes
+ };
+}
+
+sub resolve_metatrait_alias {
+ return resolve_metaclass_alias( @_, trait => 1 );
+}
+
+{
+ my %cache;
+
+ sub resolve_metaclass_alias {
+ my ( $type, $metaclass_name, %options ) = @_;
+
+ my $cache_key = $type . q{ } . ( $options{trait} ? '-Trait' : '' );
+ return $cache{$cache_key}{$metaclass_name}
+ if $cache{$cache_key}{$metaclass_name};
+
+ my $possible_full_name
+ = 'Moose::Meta::'
+ . $type
+ . '::Custom::'
+ . ( $options{trait} ? "Trait::" : "" )
+ . $metaclass_name;
+
+ my $loaded_class = Class::MOP::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 $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->get_all_methods;
+ my @matched_methods
+ = grep { $_->name =~ @{$args}[0] } @all_methods;
+ $meta->$add_modifier_method( $_->name, $code )
+ for @matched_methods;
+ }
+ }
+ 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;
}
1;
=head1 NAME
-Moose::Util - Moose utilities
+Moose::Util - Utilities for working with Moose classes
=head1 SYNOPSIS
- use Moose::Util qw/can_role search_class_by_role/;
+ use Moose::Util qw/find_meta does_role search_class_by_role/;
- if (can_role ($object,'rolename')) {
- print "The object can do rolename!\n";
+ my $meta = find_meta($object) || die "No metaclass found";
+
+ if (does_role($object, $role)) {
+ print "The object can do $role!\n";
}
my $class = search_class_by_role($object, 'FooRole');
print "Nearest class with 'FooRole' is $class\n";
-=head1 FUNCTIONS
+=head1 DESCRIPTION
+
+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 can_role
+=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_name)>
+
+Returns true if C<$class_or_obj> does the given 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)>
+
+Returns the first class in the class's precedence list that does
+C<$role_name>, if any.
+
+The class must already have a metaclass for this to work.
+
+=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.
- can_role ($object,$rolename);
+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<exclude> and
+C<alias>).
-Returns true if $object can do the role $rolename.
+=item B<ensure_all_roles($applicant, @roles)>
-=item search_class_by_role
+This function is similar to L</apply_all_roles>, but only applies roles that
+C<$applicant> does not already consume.
- my $class = search_class_by_role($object, $rolename);
+=item B<get_all_attribute_values($meta, $instance)>
-Returns first class in precedence list that consumed C<$rolename>.
+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 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)>
+
+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",
+ );
+
+The name resolution mechanism is covered in L<Moose/Trait Name
+Resolution>.
+
+=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
+
+=head1 TODO
+
+Here is a list of possible functions to write
+
+=over 4
+
+=item discovering original method from modified method
+
+=item search for origin class of a method or attribute
=back
=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.
Anders Nor Berle E<lt>debolaz@gmail.comE<gt>
+B<with contributions from:>
+
+Robert (phaylon) Sedlacek
+
+Stevan Little
+
=head1 COPYRIGHT AND LICENSE
-Copyright 2007 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
projects / gitmo/Moose.git / blobdiff