[Moose-commits] r7448 - in Moose/branches/moose-manual/lib/Moose: . Manual

Sat Jan 31 17:32:13 GMT 2009

Author: autarch
Date: 2009-01-31 09:32:13 -0800 (Sat, 31 Jan 2009)
New Revision: 7448

Added:
   Moose/branches/moose-manual/lib/Moose/Manual/MOP.pod
Modified:
   Moose/branches/moose-manual/lib/Moose/Manual.pod
Log:
the last manual page! MOP docs

Added: Moose/branches/moose-manual/lib/Moose/Manual/MOP.pod
===================================================================

--- Moose/branches/moose-manual/lib/Moose/Manual/MOP.pod	                        (rev 0)
+++ Moose/branches/moose-manual/lib/Moose/Manual/MOP.pod	2009-01-31 17:32:13 UTC (rev 7448)
@@ -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<Class::MOP>. "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<Class::MOP> 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::MOP> class to extend. Moose also adds some entirely new
+features, including roles, method augmentation, and types.
+
+It's important to know about C<Class::MOP> so you know what docs to
+read. Often times, the introspection method that you're looking for is
+defined in a C<Class::MOP> class, rather than Moose itself.
+
+The MOP provides more than just I<read-only> 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<Moose::Meta::Class>. This is available by calling the
+C<meta> method on a class or object:
+
+  package User;
+
+  use Moose;
+
+  my $meta = __PACKAGE__->meta;
+
+The C<meta> method is added to a class when it uses Moose.
+
+You can also use C<Class::MOP::get_metaclass_by_name($name)> 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<isn't> 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<Class::MOP::Class>
+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<get_all_attributes> method is documented in
+C<Class::MOP::Class>. It returns a list of L<Moose::Meta::Attribute>
+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<Moose::Meta::Method> objects. Note
+that some of these objects may actually be a subclass of
+L<Moose::Meta::Method>, 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<names>, 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<Moose::Cookbook>. 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<Class::MOP> 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<Moose.pm docs|Moose/SEE ALSO>.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch at urth.orgE<gt> and Stevan Little
+E<lt>stevan at iinteractive.comE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 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.
+
+=cut

Modified: Moose/branches/moose-manual/lib/Moose/Manual.pod
===================================================================
--- Moose/branches/moose-manual/lib/Moose/Manual.pod	2009-01-31 17:21:11 UTC (rev 7447)
+++ Moose/branches/moose-manual/lib/Moose/Manual.pod	2009-01-31 17:32:13 UTC (rev 7448)
@@ -151,10 +151,10 @@
 Moose's type system lets you strictly define what values an attribute
 can contain.
 
-=item L<Moose::Manual::Introspection>
+=item L<Moose::Manual::MOP>
 
-Moose's introspection system (primarily from C<Class::MOP>) 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<Moose::Manual::MooseX>
 


