local-lib5/man/man3/Moose::Manual::MOP.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Moose::Manual::MOP 3"
 132 .TH Moose::Manual::MOP 3 "2009-04-18" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Manual::MOP \- The Moose (and Class::MOP) meta API
 135 .SH "INTRODUCTION"
 136 .IX Header "INTRODUCTION"
 137 Moose provides a powerful introspection \s-1API\s0 built on top of
 138 \&\f(CW\*(C`Class::MOP\*(C'\fR. \*(L"\s-1MOP\s0\*(R" stands for Meta-Object Protocol. In plainer
 139 English, a \s-1MOP\s0 is an \s-1API\s0 for performing introspection on classes,
 140 attributes, methods, and so on.
 141 .PP
 142 In fact, it is \f(CW\*(C`Class::MOP\*(C'\fR that provides many of Moose's core
 143 features, including attributes, before/after/around method modifiers,
 144 and immutability. In most cases, Moose takes an existing \f(CW\*(C`Class::MOP\*(C'\fR
 145 class and subclasses it to add additional features. Moose also adds
 146 some entirely new features of its own, such as roles, the augment
 147 modifier, and types.
 148 .PP
 149 If you're interested in the \s-1MOP\s0, it's important to know about
 150 \&\f(CW\*(C`Class::MOP\*(C'\fR so you know what docs to read. Often, the introspection
 151 method that you're looking for is defined in a \f(CW\*(C`Class::MOP\*(C'\fR class,
 152 rather than Moose itself.
 153 .PP
 154 The \s-1MOP\s0 provides more than just \fIread-only\fR introspection. It also
 155 lets you add attributes and methods, apply roles, and much more. In
 156 fact, all of the declarative Moose sugar is simply a thin layer on top
 157 of the \s-1MOP\s0 \s-1API\s0.
 158 .PP
 159 If you want to write Moose extensions, you'll need to learn some of
 160 the \s-1MOP\s0 \s-1API\s0. The introspection methods are also handy if you want to
 161 generate docs or inheritance graphs, or do some other runtime
 162 reflection.
 163 .PP
 164 This document is not a complete reference for the meta \s-1API\s0. We're just
 165 going to cover some of the highlights, and give you a sense of how it
 166 all works. To really understand it, you'll have to read a lot of other
 167 docs, and possibly even dig into the Moose guts a bit.
 168 .SH "GETTING STARTED"
 169 .IX Header "GETTING STARTED"
 170 The usual entry point to the meta \s-1API\s0 is through a class's metaclass
 171 object, which is a Moose::Meta::Class. This is available by calling
 172 the \f(CW\*(C`meta\*(C'\fR method on a class or object:
 173 .PP
 174 .Vb 1
 175 \&  package User;
 176 .Ve
 177 .PP
 178 .Vb 1
 179 \&  use Moose;
 180 .Ve
 181 .PP
 182 .Vb 1
 183 \&  my $meta = __PACKAGE__\->meta;
 184 .Ve
 185 .PP
 186 The \f(CW\*(C`meta\*(C'\fR method is added to a class when it uses Moose.
 187 .PP
 188 You can also use \f(CW\*(C`Class::MOP::Class\->initialize($name)\*(C'\fR to get a
 189 metaclass object for any class. This is safer than calling \f(CW\*(C`$class\->meta\*(C'\fR when you're not sure that the class has a meta method.
 190 .PP
 191 The \f(CW\*(C`Class::MOP::Class\->initialize\*(C'\fR constructor will return an
 192 existing metaclass if one has already been created (via Moose or some
 193 other means). If it hasn't, it will return a new \f(CW\*(C`Class::MOP::Class\*(C'\fR
 194 object. This will work for classes that use Moose, meta \s-1API\s0 classes,
 195 and classes which don't use Moose at all.
 196 .SH "USING THE METACLASS OBJECT"
 197 .IX Header "USING THE METACLASS OBJECT"
 198 The metaclass object can tell you about a class's attributes, methods,
 199 roles, parents, and more. For example, to look at all of the class's
 200 attributes:
 201 .PP
 202 .Vb 3
 203 \&  for my $attr ( $meta\->get_all_attributes ) {
 204 \&      print $attr\->name, "\en";
 205 \&  }
 206 .Ve
 207 .PP
 208 The \f(CW\*(C`get_all_attributes\*(C'\fR method is documented in
 209 \&\f(CW\*(C`Class::MOP::Class\*(C'\fR. For Moose-using classes, it returns a list of
 210 Moose::Meta::Attribute objects for attributes defined in the class
 211 and its parents.
 212 .PP
 213 You can also get a list of methods:
 214 .PP
 215 .Vb 3
 216 \&  for my $method ( $meta\->get_all_methods ) {
 217 \&      print $method\->fully_qualified_name, "\en";
 218 \&  }
 219 .Ve
 220 .PP
 221 Now we're looping over a list of Moose::Meta::Method objects. Note
 222 that some of these objects may actually be a subclass of
 223 Moose::Meta::Method, as Moose uses different classes to represent
 224 wrapped methods, delegation methods, constructors, etc.
 225 .PP
 226 We can look at a class's parent classes and subclasses:
 227 .PP
 228 .Vb 3
 229 \&  for my $class ( $meta\->linearized_isa ) {
 230 \&      print "$class\en";
 231 \&  }
 232 .Ve
 233 .PP
 234 .Vb 3
 235 \&  for my $subclass ( $meta\->subclasses ) {
 236 \&      print "$subclass\en";
 237 \&  }
 238 .Ve
 239 .PP
 240 Note that both these methods return class \fInames\fR, not metaclass
 241 objects.
 242 .SH "ALTERING CLASSES WITH THE MOP"
 243 .IX Header "ALTERING CLASSES WITH THE MOP"
 244 The metaclass object can change the class directly, by adding
 245 attributes, methods, etc.
 246 .PP
 247 As an example, we can add a method to a class:
 248 .PP
 249 .Vb 1
 250 \&  $meta\->add_method( 'say' => sub { print @_, "\en" } );
 251 .Ve
 252 .PP
 253 Or an attribute:
 254 .PP
 255 .Vb 5
 256 \&  $meta\->add_attribute(
 257 \&      name => 'size',
 258 \&      is   => 'rw',
 259 \&      isa  => 'Int',
 260 \&  );
 261 .Ve
 262 .PP
 263 Obviously, this is much more cumbersome than using Perl syntax or
 264 Moose sugar for defining methods and attributes, but this \s-1API\s0 allows
 265 for very powerful extensions.
 266 .PP
 267 You might remember that we've talked about making classes immutable
 268 elsewhere in the manual. This is a good practice. However, once a
 269 class is immutable, calling any of these update methods will throw an
 270 exception.
 271 .PP
 272 You can make a class mutable again simply by calling \f(CW\*(C`$meta\->make_mutable\*(C'\fR. Once you're done changing it, you can
 273 restore immutability by calling \f(CW\*(C`$meta\->make_immutable\*(C'\fR.
 274 .PP
 275 However, the most common use for this part of the meta \s-1API\s0 is as
 276 part of Moose extensions. These extensions should assume that they are
 277 being run before you make a class immutable.
 278 .SH "GOING FURTHER"
 279 .IX Header "GOING FURTHER"
 280 If you're interested in extending Moose, we recommend reading all of
 281 the \*(L"Meta\*(R" and \*(L"Extending\*(R" recipes in the Moose::Cookbook. Those
 282 recipes show various practical applications of the \s-1MOP\s0.
 283 .PP
 284 If you'd like to write your own extensions, one of the best ways to
 285 learn more about this is to look at other similar extensions to see
 286 how they work. You'll probably also need to read various \s-1API\s0 docs,
 287 including the docs for the various Moose::Meta::* classes and the
 288 \&\f(CW\*(C`Class::MOP\*(C'\fR distribution.
 289 .PP
 290 Finally, we welcome questions on the Moose mailing list and
 291 \&\s-1IRC\s0. Information on the mailing list, \s-1IRC\s0, and more references can be
 292 found in the Moose.pm docs.
 293 .SH "AUTHOR"
 294 .IX Header "AUTHOR"
 295 Dave Rolsky <autarch@urth.org> and Stevan Little
 296 <stevan@iinteractive.com>
 297 .SH "COPYRIGHT AND LICENSE"
 298 .IX Header "COPYRIGHT AND LICENSE"
 299 Copyright 2009 by Infinity Interactive, Inc.
 300 .PP
 301 <http://www.iinteractive.com>
 302 .PP
 303 This library is free software; you can redistribute it and/or modify
 304 it under the same terms as Perl itself.