local-lib5/man/man3/Moose::Meta::Attribute.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::Meta::Attribute 3"
 132 .TH Moose::Meta::Attribute 3 "2009-11-19" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Meta::Attribute \- The Moose attribute metaclass
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 This class is a subclass of Class::MOP::Attribute that provides
 138 additional Moose-specific functionality.
 139 .PP
 140 To really understand this class, you will need to start with the
 141 Class::MOP::Attribute documentation. This class can be understood
 142 as a set of additional features on top of the basic feature provided
 143 by that parent class.
 144 .SH "INHERITANCE"
 145 .IX Header "INHERITANCE"
 146 \&\f(CW\*(C`Moose::Meta::Attribute\*(C'\fR is a subclass of Class::MOP::Attribute.
 147 .SH "METHODS"
 148 .IX Header "METHODS"
 149 Many of the documented below override methods in
 150 Class::MOP::Attribute and add Moose specific features.
 151 .Sh "Creation"
 152 .IX Subsection "Creation"
 153 .IP "\fBMoose::Meta::Attribute\->new(%options)\fR" 4
 154 .IX Item "Moose::Meta::Attribute->new(%options)"
 155 This method overrides the Class::MOP::Attribute constructor.
 156 .Sp
 157 Many of the options below are described in more detail in the
 158 Moose::Manual::Attributes document.
 159 .Sp
 160 It adds the following options to the constructor:
 161 .RS 4
 162 .IP "* is => 'ro', 'rw', 'bare'" 8
 163 .IX Item "is => 'ro', 'rw', 'bare'"
 164 This provides a shorthand for specifying the \f(CW\*(C`reader\*(C'\fR, \f(CW\*(C`writer\*(C'\fR, or
 165 \&\f(CW\*(C`accessor\*(C'\fR names. If the attribute is read-only ('ro') then it will
 166 have a \f(CW\*(C`reader\*(C'\fR method with the same attribute as the name.
 167 .Sp
 168 If it is read-write ('rw') then it will have an \f(CW\*(C`accessor\*(C'\fR method
 169 with the same name. If you provide an explicit \f(CW\*(C`writer\*(C'\fR for a
 170 read-write attribute, then you will have a \f(CW\*(C`reader\*(C'\fR with the same
 171 name as the attribute, and a \f(CW\*(C`writer\*(C'\fR with the name you provided.
 172 .Sp
 173 Use 'bare' when you are deliberately not installing any methods
 174 (accessor, reader, etc.) associated with this attribute; otherwise,
 175 Moose will issue a deprecation warning when this attribute is added to a
 176 metaclass.
 177 .ie n .IP "* isa => $type" 8
 178 .el .IP "* isa => \f(CW$type\fR" 8
 179 .IX Item "isa => $type"
 180 This option accepts a type. The type can be a string, which should be
 181 a type name. If the type name is unknown, it is assumed to be a class
 182 name.
 183 .Sp
 184 This option can also accept a Moose::Meta::TypeConstraint object.
 185 .Sp
 186 If you \fIalso\fR provide a \f(CW\*(C`does\*(C'\fR option, then your \f(CW\*(C`isa\*(C'\fR option must
 187 be a class name, and that class must do the role specified with
 188 \&\f(CW\*(C`does\*(C'\fR.
 189 .ie n .IP "* does => $role" 8
 190 .el .IP "* does => \f(CW$role\fR" 8
 191 .IX Item "does => $role"
 192 This is short-hand for saying that the attribute's type must be an
 193 object which does the named role.
 194 .ie n .IP "* coerce => $bool" 8
 195 .el .IP "* coerce => \f(CW$bool\fR" 8
 196 .IX Item "coerce => $bool"
 197 This option is only valid for objects with a type constraint
 198 (\f(CW\*(C`isa\*(C'\fR). If this is true, then coercions will be applied whenever
 199 this attribute is set.
 200 .Sp
 201 You can make both this and the \f(CW\*(C`weak_ref\*(C'\fR option true.
 202 .ie n .IP "* trigger => $sub" 8
 203 .el .IP "* trigger => \f(CW$sub\fR" 8
 204 .IX Item "trigger => $sub"
 205 This option accepts a subroutine reference, which will be called after
 206 the attribute is set.
 207 .ie n .IP "* required => $bool" 8
 208 .el .IP "* required => \f(CW$bool\fR" 8
 209 .IX Item "required => $bool"
 210 An attribute which is required must be provided to the constructor. An
 211 attribute which is required can also have a \f(CW\*(C`default\*(C'\fR or \f(CW\*(C`builder\*(C'\fR,
 212 which will satisfy its required\-ness.
 213 .Sp
 214 A required attribute must have a \f(CW\*(C`default\*(C'\fR, \f(CW\*(C`builder\*(C'\fR or a
 215 non\-\f(CW\*(C`undef\*(C'\fR \f(CW\*(C`init_arg\*(C'\fR
 216 .ie n .IP "* lazy => $bool" 8
 217 .el .IP "* lazy => \f(CW$bool\fR" 8
 218 .IX Item "lazy => $bool"
 219 A lazy attribute must have a \f(CW\*(C`default\*(C'\fR or \f(CW\*(C`builder\*(C'\fR. When an
 220 attribute is lazy, the default value will not be calculated until the
 221 attribute is read.
 222 .ie n .IP "* weak_ref => $bool" 8
 223 .el .IP "* weak_ref => \f(CW$bool\fR" 8
 224 .IX Item "weak_ref => $bool"
 225 If this is true, the attribute's value will be stored as a weak
 226 reference.
 227 .ie n .IP "* auto_deref => $bool" 8
 228 .el .IP "* auto_deref => \f(CW$bool\fR" 8
 229 .IX Item "auto_deref => $bool"
 230 If this is true, then the reader will dereference the value when it is
 231 called. The attribute must have a type constraint which defines the
 232 attribute as an array or hash reference.
 233 .ie n .IP "* lazy_build => $bool" 8
 234 .el .IP "* lazy_build => \f(CW$bool\fR" 8
 235 .IX Item "lazy_build => $bool"
 236 Setting this to true makes the attribute lazy and provides a number of
 237 default methods.
 238 .Sp
 239 .Vb 4
 240 \&  has 'size' => (
 241 \&      is         => 'ro',
 242 \&      lazy_build => 1,
 243 \&  );
 244 .Ve
 245 .Sp
 246 is equivalent to this:
 247 .Sp
 248 .Vb 7
 249 \&  has 'size' => (
 250 \&      is        => 'ro',
 251 \&      lazy      => 1,
 252 \&      builder   => '_build_size',
 253 \&      clearer   => 'clear_size',
 254 \&      predicate => 'has_size',
 255 \&  );
 256 .Ve
 257 .IP "* documentation" 8
 258 .IX Item "documentation"
 259 An arbitrary string that can be retrieved later by calling \f(CW\*(C`$attr\->documentation\*(C'\fR.
 260 .RE
 261 .RS 4
 262 .RE
 263 .IP "\fB$attr\->clone(%options)\fR" 4
 264 .IX Item "$attr->clone(%options)"
 265 This creates a new attribute based on attribute being cloned. You must
 266 supply a \f(CW\*(C`name\*(C'\fR option to provide a new name for the attribute.
 267 .Sp
 268 The \f(CW%options\fR can only specify options handled by
 269 Class::MOP::Attribute.
 270 .Sh "Value management"
 271 .IX Subsection "Value management"
 272 .ie n .IP "\fB$attr\->initialize_instance_slot($meta_instance, \fB$instance\fB, \f(BI$params\fB)\fR" 4
 273 .el .IP "\fB$attr\->initialize_instance_slot($meta_instance, \f(CB$instance\fB, \f(CB$params\fB)\fR" 4
 274 .IX Item "$attr->initialize_instance_slot($meta_instance, $instance, $params)"
 275 This method is used internally to initialize the attribute's slot in
 276 the object \f(CW$instance\fR.
 277 .Sp
 278 This overrides the Class::MOP::Attribute method to handle lazy
 279 attributes, weak references, and type constraints.
 280 .IP "\fBget_value\fR" 4
 281 .IX Item "get_value"
 282 .PD 0
 283 .IP "\fBset_value\fR" 4
 284 .IX Item "set_value"
 285 .PD
 286 .Vb 4
 287 \&  eval { $point\->meta\->get_attribute('x')\->set_value($point, 'forty\-two') };
 288 \&  if($@) {
 289 \&    print "Oops: $@\en";
 290 \&  }
 291 .Ve
 292 .Sp
 293 \&\fIAttribute (x) does not pass the type constraint (Int) with 'forty\-two'\fR
 294 .Sp
 295 Before setting the value, a check is made on the type constraint of
 296 the attribute, if it has one, to see if the value passes it. If the
 297 value fails to pass, the set operation dies with a throw_error.
 298 .Sp
 299 Any coercion to convert values is done before checking the type constraint.
 300 .Sp
 301 To check a value against a type constraint before setting it, fetch the
 302 attribute instance using \*(L"find_attribute_by_name\*(R" in Class::MOP::Class,
 303 fetch the type_constraint from the attribute using \*(L"type_constraint\*(R" in Moose::Meta::Attribute
 304 and call \*(L"check\*(R" in Moose::Meta::TypeConstraint. See Moose::Cookbook::Basics::Recipe4
 305 for an example.
 306 .Sh "Attribute Accessor generation"
 307 .IX Subsection "Attribute Accessor generation"
 308 .IP "\fB$attr\->install_accessors\fR" 4
 309 .IX Item "$attr->install_accessors"
 310 This method overrides the parent to also install delegation methods.
 311 .Sp
 312 If, after installing all methods, the attribute object has no associated
 313 methods, it throws an error unless \f(CW\*(C`is => 'bare'\*(C'\fR was passed to the
 314 attribute constructor.  (Trying to add an attribute that has no associated
 315 methods is almost always an error.)
 316 .IP "\fB$attr\->remove_accessors\fR" 4
 317 .IX Item "$attr->remove_accessors"
 318 This method overrides the parent to also remove delegation methods.
 319 .IP "\fB$attr\->install_delegation\fR" 4
 320 .IX Item "$attr->install_delegation"
 321 This method adds its delegation methods to the attribute's associated
 322 class, if it has any to add.
 323 .IP "\fB$attr\->remove_delegation\fR" 4
 324 .IX Item "$attr->remove_delegation"
 325 This method remove its delegation methods from the attribute's
 326 associated class.
 327 .IP "\fB$attr\->accessor_metaclass\fR" 4
 328 .IX Item "$attr->accessor_metaclass"
 329 Returns the accessor metaclass name, which defaults to
 330 Moose::Meta::Method::Accessor.
 331 .IP "\fB$attr\->delegation_metaclass\fR" 4
 332 .IX Item "$attr->delegation_metaclass"
 333 Returns the delegation metaclass name, which defaults to
 334 Moose::Meta::Method::Delegation.
 335 .Sh "Additional Moose features"
 336 .IX Subsection "Additional Moose features"
 337 These methods are not found in the superclass. They support features
 338 provided by Moose.
 339 .IP "\fB$attr\->does($role)\fR" 4
 340 .IX Item "$attr->does($role)"
 341 This indicates whether the \fIattribute itself\fR does the given
 342 role. The role can be given as a full class name, or as a resolvable
 343 trait name.
 344 .Sp
 345 Note that this checks the attribute itself, not its type constraint,
 346 so it is checking the attribute's metaclass and any traits applied to
 347 the attribute.
 348 .ie n .IP "\fBMoose::Meta::Class\->interpolate_class_and_new($name, \fB%options\fB)\fR" 4
 349 .el .IP "\fBMoose::Meta::Class\->interpolate_class_and_new($name, \f(CB%options\fB)\fR" 4
 350 .IX Item "Moose::Meta::Class->interpolate_class_and_new($name, %options)"
 351 This is an alternate constructor that handles the \f(CW\*(C`metaclass\*(C'\fR and
 352 \&\f(CW\*(C`traits\*(C'\fR options.
 353 .Sp
 354 Effectively, this method is a factory that finds or creates the
 355 appropriate class for the given \f(CW\*(C`metaclass\*(C'\fR and/or \f(CW\*(C`traits\*(C'\fR.
 356 .Sp
 357 Once it has the appropriate class, it will call \f(CW\*(C`$class\->new($name,
 358 %options)\*(C'\fR on that class.
 359 .IP "\fB$attr\->clone_and_inherit_options(%options)\fR" 4
 360 .IX Item "$attr->clone_and_inherit_options(%options)"
 361 This method supports the \f(CW\*(C`has '+foo'\*(C'\fR feature. It does various bits
 362 of processing on the supplied \f(CW%options\fR before ultimately calling
 363 the \f(CW\*(C`clone\*(C'\fR method.
 364 .Sp
 365 One of its main tasks is to make sure that the \f(CW%options\fR provided
 366 only includes the options returned by the
 367 \&\f(CW\*(C`legal_options_for_inheritance\*(C'\fR method.
 368 .IP "\fB$attr\->legal_options_for_inheritance\fR" 4
 369 .IX Item "$attr->legal_options_for_inheritance"
 370 This returns a whitelist of options that can be overridden in a
 371 subclass's attribute definition.
 372 .Sp
 373 This exists to allow a custom metaclass to change or add to the list
 374 of options which can be changed.
 375 .IP "\fB$attr\->type_constraint\fR" 4
 376 .IX Item "$attr->type_constraint"
 377 Returns the Moose::Meta::TypeConstraint object for this attribute,
 378 if it has one.
 379 .IP "\fB$attr\->has_type_constraint\fR" 4
 380 .IX Item "$attr->has_type_constraint"
 381 Returns true if this attribute has a type constraint.
 382 .IP "\fB$attr\->verify_against_type_constraint($value)\fR" 4
 383 .IX Item "$attr->verify_against_type_constraint($value)"
 384 Given a value, this method returns true if the value is valid for the
 385 attribute's type constraint. If the value is not valid, it throws an
 386 error.
 387 .IP "\fB$attr\->handles\fR" 4
 388 .IX Item "$attr->handles"
 389 This returns the value of the \f(CW\*(C`handles\*(C'\fR option passed to the
 390 constructor.
 391 .IP "\fB$attr\->has_handles\fR" 4
 392 .IX Item "$attr->has_handles"
 393 Returns true if this attribute performs delegation.
 394 .IP "\fB$attr\->is_weak_ref\fR" 4
 395 .IX Item "$attr->is_weak_ref"
 396 Returns true if this attribute stores its value as a weak reference.
 397 .IP "\fB$attr\->is_required\fR" 4
 398 .IX Item "$attr->is_required"
 399 Returns true if this attribute is required to have a value.
 400 .IP "\fB$attr\->is_lazy\fR" 4
 401 .IX Item "$attr->is_lazy"
 402 Returns true if this attribute is lazy.
 403 .IP "\fB$attr\->is_lazy_build\fR" 4
 404 .IX Item "$attr->is_lazy_build"
 405 Returns true if the \f(CW\*(C`lazy_build\*(C'\fR option was true when passed to the
 406 constructor.
 407 .IP "\fB$attr\->should_coerce\fR" 4
 408 .IX Item "$attr->should_coerce"
 409 Returns true if the \f(CW\*(C`coerce\*(C'\fR option passed to the constructor was
 410 true.
 411 .IP "\fB$attr\->should_auto_deref\fR" 4
 412 .IX Item "$attr->should_auto_deref"
 413 Returns true if the \f(CW\*(C`auto_deref\*(C'\fR option passed to the constructor was
 414 true.
 415 .IP "\fB$attr\->trigger\fR" 4
 416 .IX Item "$attr->trigger"
 417 This is the subroutine reference that was in the \f(CW\*(C`trigger\*(C'\fR option
 418 passed to the constructor, if any.
 419 .IP "\fB$attr\->has_trigger\fR" 4
 420 .IX Item "$attr->has_trigger"
 421 Returns true if this attribute has a trigger set.
 422 .IP "\fB$attr\->documentation\fR" 4
 423 .IX Item "$attr->documentation"
 424 Returns the value that was in the \f(CW\*(C`documentation\*(C'\fR option passed to
 425 the constructor, if any.
 426 .IP "\fB$attr\->has_documentation\fR" 4
 427 .IX Item "$attr->has_documentation"
 428 Returns true if this attribute has any documentation.
 429 .IP "\fB$attr\->applied_traits\fR" 4
 430 .IX Item "$attr->applied_traits"
 431 This returns an array reference of all the traits which were applied
 432 to this attribute. If none were applied, this returns \f(CW\*(C`undef\*(C'\fR.
 433 .IP "\fB$attr\->has_applied_traits\fR" 4
 434 .IX Item "$attr->has_applied_traits"
 435 Returns true if this attribute has any traits applied.
 436 .SH "BUGS"
 437 .IX Header "BUGS"
 438 All complex software has bugs lurking in it, and this module is no
 439 exception. If you find a bug please either email me, or add the bug
 440 to cpan\-RT.
 441 .SH "AUTHOR"
 442 .IX Header "AUTHOR"
 443 Stevan Little <stevan@iinteractive.com>
 444 .PP
 445 Yuval Kogman <nothingmuch@woobling.com>
 446 .SH "COPYRIGHT AND LICENSE"
 447 .IX Header "COPYRIGHT AND LICENSE"
 448 Copyright 2006\-2009 by Infinity Interactive, Inc.
 449 .PP
 450 <http://www.iinteractive.com>
 451 .PP
 452 This library is free software; you can redistribute it and/or modify
 453 it under the same terms as Perl itself.