From: Dave Rolsky Date: Sat, 31 Jan 2009 17:32:13 +0000 (+0000) Subject: the last manual page! MOP docs X-Git-Tag: 0.66~27^2~2 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=87817dcf89e2f396078340901f1e337e0cd8ef62;p=gitmo%2FMoose.git the last manual page! MOP docs --- diff --git a/lib/Moose/Manual.pod b/lib/Moose/Manual.pod index 8162f57..b4e8230 100644 --- a/lib/Moose/Manual.pod +++ b/lib/Moose/Manual.pod @@ -151,10 +151,10 @@ is orthogonal to inheritance. Moose's type system lets you strictly define what values an attribute can contain. -=item L +=item L -Moose's introspection system (primarily from C) lets you -ask classes about their parents, children, methods, attributes, etc. +Moose's meta API system lets you ask classes about their parents, +children, methods, attributes, etc. =item L diff --git a/lib/Moose/Manual/MOP.pod b/lib/Moose/Manual/MOP.pod new file mode 100644 index 0000000..9cb977f --- /dev/null +++ b/lib/Moose/Manual/MOP.pod @@ -0,0 +1,171 @@ +=pod + +=head1 NAME + +Moose::Manual::MOP - The Moose (and Class::MOP) Meta API + +=head1 INTRODUCTION + +Moose provides a powerful introspection API by building on top of +C. "MOP" stands for Meta-Object Protocol. In plainer +english, a MOP is an API for examing classes, attributes, methods, and +so on. + +In fact, it is C that provides many of Moose's core +features, including attributes, before/after/around method modifiers, +and immutability. In most cases, Moose subclasses an existing +C class to extend. Moose also adds some entirely new +features, including roles, method augmentation, and types. + +It's important to know about C so you know what docs to +read. Often times, the introspection method that you're looking for is +defined in a C class, rather than Moose itself. + +The MOP provides more than just I introspection. It also +lets you add attributes, method, apply roles, and much more. In fact, +all of the declarative Moose sugar is simply a thin layer on top of +the MOP API. + +The meta API is useful for a lot of things. If you want to write Moose +extensions, you'll definitely need to learn about the meta API. The +introspection methods are also handy if you want to do something like +generate docs or inheritance graphs, or do some other sort of runtime +reflection. + +This document is not a complete reference for the meta API. We're just +going to cover some of the highlights, and give you a sense of how it +all works. To really understand it, you'll have to read a lot of other +docs, and possibly even dig into the Moose guts a bit. + +=head1 GETTING STARTED + +The typical entry point to the meta API is a class's metaclass object, +which is a L. This is available by calling the +C method on a class or object: + + package User; + + use Moose; + + my $meta = __PACKAGE__->meta; + +The C method is added to a class when it uses Moose. + +You can also use C to get a +metaclass object for any class. This is safer than calling C<< +$class->meta >> when you're not sure that the class has a meta method. + +If you want a metaclass object for a class that I using Moose, +a good idiom to use is: + + my $meta = Class::MOP::Class->initialize($class_name); + +The C<< Class::MOP::Class->initialize >> will return an existing +metaclass if one has already been created (via Moose or some other +means). If it hasn't, it will return a new C +object. This will work for classes that use Moose, meta API classes, +and classes which don't use Moose at all. + +=head1 USING THE METACLASS OBJECT + +The metaclass object can tell you about a class's attributes, methods, +roles, parents, and more. For example, to look at all of the class's +attributes: + + for my $attr ( $meta->get_all_attributes ) { + print $attr->name, "\n"; + } + +The C method is documented in +C. It returns a list of L +objects for attributes defined in the class and its parents. + +You can also get a list of methods: + + for my $method ( $meta->get_all_methods ) { + print $meth->fully_qualified_name, "\n"; + } + +Now we're looping over a list of L objects. Note +that some of these objects may actually be a subclass of +L, as Moose uses different classes to represent +wrapped methods, delegation methods, constructors, etc. + +We can look at a class's parent classes and subclasses: + + for my $class ( $meta->linearized_isa ) { + print "$class\n"; + } + + for my $subclass ( $meta->subclasses ) { + print "$subclass\n"; + } + +Note that both these methods return class I, not metaclass +objects. + +=head1 CHANGING THE OBJECT + +You can also use the metaclass object to change the class directly, by +adding attributes, methods, etc. + +You might remember that we've talked about making classes immutable +elsewhere in the manual. This is a good practice. However, once a +class is immutable, calling any of these update methods will throw an +exception. + +You can make a class mutable again simply by calling C<< +$metaclass->make_mutable >>. Once you're done changing it, you can +restore immutability by calling C<< $metaclass->make_immutable >>. + +However, the most common use for this part of of the meta API is as +part of Moose extensions. These extensions should assume that they are +being run before you make a class immutable. + +As an example, we can add a method to a class: + + $meta->add_method( 'say' => sub { print @_, "\n" } ); + +Or an attribute: + + $meta->add_attribute( + name => 'size', + is => 'rw', + isa => 'Int', + ); + +Obviously, this is much more cumbersome than the normal way of +defining methods and attributes, but being able to do this via an API +makes for very powerful extensions. + +=head1 GOING FURTHER + +We recommend that you take a look at all of the "Meta" and "Extending" +recipes in the L. These show various practical +applications of the MOP. + +If you'd like to write your own extensions, one of the best ways to +learn more about this is to look at other similar extensions to see +how they work. You'll probably also need to read various API docs, +including the docs for the various Moose::Meta::* classes and the +C distribution. + +Finally, we welcome questions on the Moose mailing list and +IRC. Information on the mailing list, IRC, and more references can be +found in the L. + +=head1 AUTHOR + +Dave Rolsky Eautarch@urth.orgE and Stevan Little +Estevan@iinteractive.comE + +=head1 COPYRIGHT AND LICENSE + +Copyright 2008 by Infinity Interactive, Inc. + +L + +This library is free software; you can redistribute it and/or modify +it under the same terms as Perl itself. + +=cut