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