use strict;
use warnings;
-our $VERSION = '0.13';
+our $VERSION = '0.21';
+our $AUTHORITY = 'cpan:STEVAN';
use Scalar::Util 'blessed', 'reftype';
use Carp 'confess';
use Sub::Name 'subname';
use B 'svref_2object';
-use UNIVERSAL::require;
use Sub::Exporter;
use Class::MOP;
subtype $class
=> as 'Object'
=> where { $_->isa($class) }
+ => optimize_as { blessed($_[0]) && $_[0]->isa($class) }
unless find_type_constraint($class);
my $meta;
my $class = $CALLER;
return subname 'Moose::extends' => sub (@) {
confess "Must derive at least one class" unless @_;
- _load_all_classes(@_);
+ Class::MOP::load_class($_) for @_;
# this checks the metaclass to make sure
# it is correct, sometimes it can get out
# of sync when the classes are being built
return subname 'Moose::with' => sub (@) {
my (@roles) = @_;
confess "Must specify at least one role" unless @roles;
- _load_all_classes(@roles);
+ Class::MOP::load_class($_) for @roles;
$class->meta->_apply_all_roles(@roles);
};
},
has => sub {
my $class = $CALLER;
return subname 'Moose::has' => sub ($;%) {
- my ($name, %options) = @_;
- $class->meta->_process_attribute($name, %options);
+ my ($name, %options) = @_;
+ my $attrs = (ref($name) eq 'ARRAY') ? $name : [($name)];
+ $class->meta->_process_attribute($_, %options) for @$attrs;
};
},
before => sub {
};
},
super => sub {
+ {
+ our %SUPER_SLOT;
+ no strict 'refs';
+ $SUPER_SLOT{$CALLER} = \*{"${CALLER}::super"};
+ }
return subname 'Moose::super' => sub {};
},
override => sub {
};
},
inner => sub {
+ {
+ our %INNER_SLOT;
+ no strict 'refs';
+ $INNER_SLOT{$CALLER} = \*{"${CALLER}::inner"};
+ }
return subname 'Moose::inner' => sub {};
},
augment => sub {
},
# NOTE:
- # this is experimental for now ...
- self => sub {
- return subname 'Moose::self' => sub {};
- },
- method => sub {
- my $class = $CALLER;
- return subname 'Moose::method' => sub {
- my ($name, $method) = @_;
- $class->meta->add_method($name, sub {
- my $self = shift;
- no strict 'refs';
- no warnings 'redefine';
- local *{$class->meta->name . '::self'} = sub { $self };
- $method->(@_);
- });
- };
- },
+ # this is experimental, but I am not
+ # happy with it. If you want to try
+ # it, you will have to uncomment it
+ # yourself.
+ # There is a really good chance that
+ # this will be deprecated, dont get
+ # too attached
+ # self => sub {
+ # return subname 'Moose::self' => sub {};
+ # },
+ # method => sub {
+ # my $class = $CALLER;
+ # return subname 'Moose::method' => sub {
+ # my ($name, $method) = @_;
+ # $class->meta->add_method($name, sub {
+ # my $self = shift;
+ # no strict 'refs';
+ # no warnings 'redefine';
+ # local *{$class->meta->name . '::self'} = sub { $self };
+ # $method->(@_);
+ # });
+ # };
+ # },
confess => sub {
return \&Carp::confess;
my $class = caller();
# loop through the exports ...
foreach my $name (keys %exports) {
- next if $name =~ /inner|super|self/;
# if we find one ...
if (defined &{$class . '::' . $name}) {
}
}
}
+
+
}
-## Utility functions
-
-sub _load_all_classes {
- foreach my $super (@_) {
- # see if this is already
- # loaded in the symbol table
- next if _is_class_already_loaded($super);
- # otherwise require it ...
- # NOTE:
- # just in case the class we are
- # loading has a locally defined
- # &require, we make sure that we
- # use the on in UNIVERSAL
- ($super->UNIVERSAL::require)
- || confess "Could not load module '$super' because : " . $UNIVERSAL::require::ERROR;
- }
-}
+## make 'em all immutable
-sub _is_class_already_loaded {
- my $name = shift;
- no strict 'refs';
- return 1 if defined ${"${name}::VERSION"} || defined @{"${name}::ISA"};
- foreach (keys %{"${name}::"}) {
- next if substr($_, -2, 2) eq '::';
- return 1 if defined &{"${name}::$_"};
- }
- return 0;
-}
+$_->meta->make_immutable(
+ inline_constructor => 0,
+ inline_accessors => 0,
+) for (
+ 'Moose::Meta::Attribute',
+ 'Moose::Meta::Class',
+ 'Moose::Meta::Instance',
+
+ 'Moose::Meta::TypeConstraint',
+ 'Moose::Meta::TypeConstraint::Union',
+ 'Moose::Meta::TypeCoercion',
+
+ 'Moose::Meta::Method',
+ 'Moose::Meta::Method::Accessor',
+ 'Moose::Meta::Method::Constructor',
+ 'Moose::Meta::Method::Overriden',
+);
1;
after 'clear' => sub {
my $self = shift;
$self->z(0);
- };
-
-=head1 CAVEAT
-
-Moose is a rapidly maturing module, and is already being used by
-a number of people. It's test suite is growing larger by the day,
-and the docs should soon follow.
-
-This said, Moose is not yet finished, and should still be considered
-to be evolving. Much of the outer API is stable, but the internals
-are still subject to change (although not without serious thought
-given to it).
-
-For more details, please refer to the L<FUTURE PLANS> section of
-this document.
+ };
=head1 DESCRIPTION
Perl 5 objects better, but it also provides the power of metaclass
programming.
-=head2 Can I use this in production? Or is this just an experiment?
+=head2 Is this for real? Or is this just an experiment?
Moose is I<based> on the prototypes and experiments I did for the Perl 6
meta-model; however Moose is B<NOT> an experiment/prototype, it is
-for B<real>. I will be deploying Moose into production environments later
-this year, and I have every intentions of using it as my de facto class
-builder from now on.
+for B<real>.
+
+=head2 Is this ready for use in production?
+
+Yes, I believe that it is.
+
+I have two medium-to-large-ish web applications which use Moose heavily
+and have been in production (without issue) for several months now. At
+$work, we are re-writing our core offering in it. And several people on
+#moose have been using it (in production) for several months now as well.
+
+Of course, in the end, you need to make this call yourself. If you have
+any questions or concerns, please feel free to email me, or even the list
+or just stop by #moose and ask away.
=head2 Is Moose just Perl 6 in Perl 5?
This will apply a given set of C<@roles> to the local class. Role support
is currently under heavy development; see L<Moose::Role> for more details.
-=item B<has ($name, %options)>
+=item B<has $name =E<gt> %options>
This will install an attribute of a given C<$name> into the current class.
The list of C<%options> are the same as those provided by
This tells the accessor whether to automatically dereference the value returned.
This is only legal if your C<isa> option is either an C<ArrayRef> or C<HashRef>.
+=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. I will try and write a
+recipe on it soon.
+
+The default behavior here is to just load C<$metaclass_name>, however, we also
+have a way to alias to a shorter name. This will first look to see if
+B<Moose::Meta::Attribute::Custom::$metaclass_name> exists, if it does it will
+then check to see if that has the method C<register_implemenetation> which
+should return the actual name of the custom attribute metaclass. If there is
+no C<register_implemenetation> method, it will just default to using
+B<Moose::Meta::Attribute::Custom::$metaclass_name> as the metaclass name.
+
=item I<trigger =E<gt> $code>
The trigger option is a CODE reference which will be called after the value of
and can typically be ignored in most cases). You B<cannot> have a trigger on
a read-only attribute.
-=item I<handles =E<gt> [ @handles ]>
+=item I<handles =E<gt> ARRAY | HASH | REGEXP | CODE>
+
+The handles option provides Moose classes with automated delegation features.
+This is a pretty complex and powerful option, it accepts many different option
+formats, each with it's own benefits and drawbacks.
+
+B<NOTE:> This features is no longer experimental, but it still may have subtle
+bugs lurking in the deeper corners. So if you think you have found a bug, you
+probably have, so please report it to me right away.
+
+B<NOTE:> The class being delegated to does not need to be a Moose based class.
+Which is why this feature is especially useful when wrapping non-Moose classes.
+
+All handles option formats share the following traits.
+
+You cannot override a locally defined method with a delegated method, an
+exception will be thrown if you try. Meaning, if you define C<foo> in your
+class, you cannot override it with a delegated C<foo>. This is almost never
+something you would want to do, and if it is, you should do it by hand and
+not use Moose.
+
+You cannot override any of the methods found in Moose::Object as well as
+C<BUILD> or C<DEMOLISH> methods. These will not throw an exception, but will
+silently move on to the next method in the list. My reasoning for this is that
+you would almost never want to do this because it usually tends to break your
+class. And as with overriding locally defined methods, if you do want to do this,
+you should do it manually and not with Moose.
+
+Below is the documentation for each option format:
+
+=over 4
+
+=item C<ARRAY>
+
+This is the most common usage for handles. You basically pass a list of
+method names to be delegated, and Moose will install a delegation method
+for each one in the list.
+
+=item C<HASH>
+
+This is the second most common usage for handles. Instead of a list of
+method names, you pass a HASH ref where the key is the method name you
+want installed locally, and the value is the name of the original method
+in the class being delegated to.
+
+This can be very useful for recursive classes like trees, here is a
+quick example (soon to be expanded into a Moose::Cookbook::Recipe):
+
+ pacakge Tree;
+ use Moose;
+
+ has 'node' => (is => 'rw', isa => 'Any');
+
+ has 'children' => (
+ is => 'ro',
+ isa => 'ArrayRef',
+ default => sub { [] }
+ );
+
+ has 'parent' => (
+ is => 'rw',
+ isa => 'Tree',
+ is_weak_ref => 1,
+ handles => {
+ parent_node => 'node',
+ siblings => 'children',
+ }
+ );
+
+In this example, the Tree package gets the C<parent_node> and C<siblings> methods
+which delegate to the C<node> and C<children> methods of the Tree instance stored
+in the parent slot.
+
+=item C<REGEXP>
+
+The regexp option works very similar to the ARRAY option, except that it builds
+the list of methods for you. It starts by collecting all possible methods of the
+class being delegated to, then filters that list using the regexp supplied here.
+
+B<NOTE:> An I<isa> option is required when using the regexp option format. This
+is so that we can determine (at compile time) the method list from the class.
+Without an I<isa> this is just not possible.
+
+=item C<CODE>
+
+This is the option to use when you really want to do something funky. You should
+only use it if you really know what you are doing as it involves manual metaclass
+twiddling.
+
+This takes a code reference, which should expect two arguments. The first is
+the attribute meta-object this I<handles> is attached to. The second is the metaclass
+of the class being delegated to. It expects you to return a hash (not a HASH ref)
+of the methods you want mapped.
+
+=back
+
+=back
+
+=item B<has +$name =E<gt> %options>
+
+This is variation on the normal attibute creator C<has>, which allows you to
+clone and extend an attribute from a superclass. Here is a quick example:
+
+ package Foo;
+ use Moose;
+
+ has 'message' => (
+ is => 'rw',
+ isa => 'Str',
+ default => 'Hello, I am a Foo'
+ );
+
+ package My::Foo;
+ use Moose;
+
+ extends 'Foo';
+
+ has '+message' => (default => 'Hello I am My::Foo');
+
+What is happening here is that B<My::Foo> is cloning the C<message> attribute
+from it's parent class B<Foo>, retaining the is =E<gt> 'rw' and isa =E<gt> 'Str'
+characteristics, but changing the value in C<default>.
+
+This feature is restricted somewhat, so as to try and enfore at least I<some>
+sanity into it. You are only allowed to change the following attributes:
+
+=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<documentation>
+
+Change the documentation string associated with the attribute.
+
+=item I<isa>
-There is experimental support for attribute delegation using the C<handles>
-option. More docs to come later.
+You I<are> allowed to change the type, but if and B<only if> the new type is
+a subtype of the old type.
=back
originally, I just ran with it.
=item Thanks to mst & chansen and the whole #moose poose for all the
-ideas/feature-requests/encouragement
+ideas/feature-requests/encouragement/bug-finding.
=item Thanks to David "Theory" Wheeler for meta-discussions and spelling fixes.
=head1 COPYRIGHT AND LICENSE
-Copyright 2006 by Infinity Interactive, Inc.
+Copyright 2006, 2007 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>