Commit | Line | Data |
87817dcf |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | Moose::Manual::MOP - The Moose (and Class::MOP) Meta API |
6 | |
7 | =head1 INTRODUCTION |
8 | |
9 | Moose provides a powerful introspection API by building on top of |
10 | C<Class::MOP>. "MOP" stands for Meta-Object Protocol. In plainer |
11 | english, a MOP is an API for examing classes, attributes, methods, and |
12 | so on. |
13 | |
14 | In fact, it is C<Class::MOP> that provides many of Moose's core |
15 | features, including attributes, before/after/around method modifiers, |
16 | and immutability. In most cases, Moose subclasses an existing |
17 | C<Class::MOP> class to extend. Moose also adds some entirely new |
18 | features, including roles, method augmentation, and types. |
19 | |
20 | It's important to know about C<Class::MOP> so you know what docs to |
21 | read. Often times, the introspection method that you're looking for is |
22 | defined in a C<Class::MOP> class, rather than Moose itself. |
23 | |
24 | The MOP provides more than just I<read-only> introspection. It also |
25 | lets you add attributes, method, apply roles, and much more. In fact, |
26 | all of the declarative Moose sugar is simply a thin layer on top of |
27 | the MOP API. |
28 | |
29 | The meta API is useful for a lot of things. If you want to write Moose |
30 | extensions, you'll definitely need to learn about the meta API. The |
31 | introspection methods are also handy if you want to do something like |
32 | generate docs or inheritance graphs, or do some other sort of runtime |
33 | reflection. |
34 | |
35 | This document is not a complete reference for the meta API. We're just |
36 | going to cover some of the highlights, and give you a sense of how it |
37 | all works. To really understand it, you'll have to read a lot of other |
38 | docs, and possibly even dig into the Moose guts a bit. |
39 | |
40 | =head1 GETTING STARTED |
41 | |
42 | The typical entry point to the meta API is a class's metaclass object, |
43 | which is a L<Moose::Meta::Class>. This is available by calling the |
44 | C<meta> method on a class or object: |
45 | |
46 | package User; |
47 | |
48 | use Moose; |
49 | |
50 | my $meta = __PACKAGE__->meta; |
51 | |
52 | The C<meta> method is added to a class when it uses Moose. |
53 | |
54 | You can also use C<Class::MOP::get_metaclass_by_name($name)> to get a |
55 | metaclass object for any class. This is safer than calling C<< |
56 | $class->meta >> when you're not sure that the class has a meta method. |
57 | |
58 | If you want a metaclass object for a class that I<isn't> using Moose, |
59 | a good idiom to use is: |
60 | |
61 | my $meta = Class::MOP::Class->initialize($class_name); |
62 | |
63 | The C<< Class::MOP::Class->initialize >> will return an existing |
64 | metaclass if one has already been created (via Moose or some other |
65 | means). If it hasn't, it will return a new C<Class::MOP::Class> |
66 | object. This will work for classes that use Moose, meta API classes, |
67 | and classes which don't use Moose at all. |
68 | |
69 | =head1 USING THE METACLASS OBJECT |
70 | |
71 | The metaclass object can tell you about a class's attributes, methods, |
72 | roles, parents, and more. For example, to look at all of the class's |
73 | attributes: |
74 | |
75 | for my $attr ( $meta->get_all_attributes ) { |
76 | print $attr->name, "\n"; |
77 | } |
78 | |
79 | The C<get_all_attributes> method is documented in |
80 | C<Class::MOP::Class>. It returns a list of L<Moose::Meta::Attribute> |
81 | objects for attributes defined in the class and its parents. |
82 | |
83 | You can also get a list of methods: |
84 | |
85 | for my $method ( $meta->get_all_methods ) { |
86 | print $meth->fully_qualified_name, "\n"; |
87 | } |
88 | |
89 | Now we're looping over a list of L<Moose::Meta::Method> objects. Note |
90 | that some of these objects may actually be a subclass of |
91 | L<Moose::Meta::Method>, as Moose uses different classes to represent |
92 | wrapped methods, delegation methods, constructors, etc. |
93 | |
94 | We can look at a class's parent classes and subclasses: |
95 | |
96 | for my $class ( $meta->linearized_isa ) { |
97 | print "$class\n"; |
98 | } |
99 | |
100 | for my $subclass ( $meta->subclasses ) { |
101 | print "$subclass\n"; |
102 | } |
103 | |
104 | Note that both these methods return class I<names>, not metaclass |
105 | objects. |
106 | |
107 | =head1 CHANGING THE OBJECT |
108 | |
109 | You can also use the metaclass object to change the class directly, by |
110 | adding attributes, methods, etc. |
111 | |
112 | You might remember that we've talked about making classes immutable |
113 | elsewhere in the manual. This is a good practice. However, once a |
114 | class is immutable, calling any of these update methods will throw an |
115 | exception. |
116 | |
117 | You can make a class mutable again simply by calling C<< |
118 | $metaclass->make_mutable >>. Once you're done changing it, you can |
119 | restore immutability by calling C<< $metaclass->make_immutable >>. |
120 | |
121 | However, the most common use for this part of of the meta API is as |
122 | part of Moose extensions. These extensions should assume that they are |
123 | being run before you make a class immutable. |
124 | |
125 | As an example, we can add a method to a class: |
126 | |
127 | $meta->add_method( 'say' => sub { print @_, "\n" } ); |
128 | |
129 | Or an attribute: |
130 | |
131 | $meta->add_attribute( |
132 | name => 'size', |
133 | is => 'rw', |
134 | isa => 'Int', |
135 | ); |
136 | |
137 | Obviously, this is much more cumbersome than the normal way of |
138 | defining methods and attributes, but being able to do this via an API |
139 | makes for very powerful extensions. |
140 | |
141 | =head1 GOING FURTHER |
142 | |
143 | We recommend that you take a look at all of the "Meta" and "Extending" |
144 | recipes in the L<Moose::Cookbook>. These show various practical |
145 | applications of the MOP. |
146 | |
147 | If you'd like to write your own extensions, one of the best ways to |
148 | learn more about this is to look at other similar extensions to see |
149 | how they work. You'll probably also need to read various API docs, |
150 | including the docs for the various Moose::Meta::* classes and the |
151 | C<Class::MOP> distribution. |
152 | |
153 | Finally, we welcome questions on the Moose mailing list and |
154 | IRC. Information on the mailing list, IRC, and more references can be |
155 | found in the L<Moose.pm docs|Moose/SEE ALSO>. |
156 | |
157 | =head1 AUTHOR |
158 | |
159 | Dave Rolsky E<lt>autarch@urth.orgE<gt> and Stevan Little |
160 | E<lt>stevan@iinteractive.comE<gt> |
161 | |
162 | =head1 COPYRIGHT AND LICENSE |
163 | |
164 | Copyright 2008 by Infinity Interactive, Inc. |
165 | |
166 | L<http://www.iinteractive.com> |
167 | |
168 | This library is free software; you can redistribute it and/or modify |
169 | it under the same terms as Perl itself. |
170 | |
171 | =cut |