local-lib5/man/man3/Class::MOP::Instance.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 "Class::MOP::Instance 3"
 132 .TH Class::MOP::Instance 3 "2009-11-18" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Class::MOP::Instance \- Instance Meta Object
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 The Instance Protocol controls the creation of object instances, and
 138 the storage of attribute values in those instances.
 139 .PP
 140 Using this \s-1API\s0 directly in your own code violates encapsulation, and
 141 we recommend that you use the appropriate APIs in Class::MOP::Class
 142 and Class::MOP::Attribute instead. Those APIs in turn call the
 143 methods in this class as appropriate.
 144 .PP
 145 This class also participates in generating inlined code by providing
 146 snippets of code to access an object instance.
 147 .SH "METHODS"
 148 .IX Header "METHODS"
 149 .Sh "Object construction"
 150 .IX Subsection "Object construction"
 151 .IP "\fBClass::MOP::Instance\->new(%options)\fR" 4
 152 .IX Item "Class::MOP::Instance->new(%options)"
 153 This method creates a new meta-instance object.
 154 .Sp
 155 It accepts the following keys in \f(CW%options\fR:
 156 .RS 4
 157 .IP "* associated_metaclass" 8
 158 .IX Item "associated_metaclass"
 159 The Class::MOP::Class object for which instances will be created.
 160 .IP "* attributes" 8
 161 .IX Item "attributes"
 162 An array reference of Class::MOP::Attribute objects. These are the
 163 attributes which can be stored in each instance.
 164 .RE
 165 .RS 4
 166 .RE
 167 .Sh "Creating and altering instances"
 168 .IX Subsection "Creating and altering instances"
 169 .IP "\fB$metainstance\->create_instance\fR" 4
 170 .IX Item "$metainstance->create_instance"
 171 This method returns a reference blessed into the associated
 172 metaclass's class.
 173 .Sp
 174 The default is to use a hash reference. Subclasses can override this.
 175 .IP "\fB$metainstance\->clone_instance($instance)\fR" 4
 176 .IX Item "$metainstance->clone_instance($instance)"
 177 Given an instance, this method creates a new object by making
 178 \&\fIshallow\fR clone of the original.
 179 .Sh "Introspection"
 180 .IX Subsection "Introspection"
 181 .IP "\fB$metainstance\->associated_metaclass\fR" 4
 182 .IX Item "$metainstance->associated_metaclass"
 183 This returns the Class::MOP::Class object associated with the
 184 meta-instance object.
 185 .IP "\fB$metainstance\->get_all_slots\fR" 4
 186 .IX Item "$metainstance->get_all_slots"
 187 This returns a list of slot names stored in object instances. In
 188 almost all cases, slot names correspond directly attribute names.
 189 .IP "\fB$metainstance\->is_valid_slot($slot_name)\fR" 4
 190 .IX Item "$metainstance->is_valid_slot($slot_name)"
 191 This will return true if \f(CW$slot_name\fR is a valid slot name.
 192 .IP "\fB$metainstance\->get_all_attributes\fR" 4
 193 .IX Item "$metainstance->get_all_attributes"
 194 This returns a list of attributes corresponding to the attributes
 195 passed to the constructor.
 196 .Sh "Operations on Instance Structures"
 197 .IX Subsection "Operations on Instance Structures"
 198 It's important to understand that the meta-instance object is a
 199 different entity from the actual instances it creates. For this
 200 reason, any operations on the \f(CW$instance_structure\fR always require
 201 that the object instance be passed to the method.
 202 .ie n .IP "\fB$metainstance\->get_slot_value($instance_structure, \fB$slot_name\fB)\fR" 4
 203 .el .IP "\fB$metainstance\->get_slot_value($instance_structure, \f(CB$slot_name\fB)\fR" 4
 204 .IX Item "$metainstance->get_slot_value($instance_structure, $slot_name)"
 205 .PD 0
 206 .ie n .IP "\fB$metainstance\->set_slot_value($instance_structure, \fB$slot_name\fB, \f(BI$value\fB)\fR" 4
 207 .el .IP "\fB$metainstance\->set_slot_value($instance_structure, \f(CB$slot_name\fB, \f(CB$value\fB)\fR" 4
 208 .IX Item "$metainstance->set_slot_value($instance_structure, $slot_name, $value)"
 209 .ie n .IP "\fB$metainstance\->initialize_slot($instance_structure, \fB$slot_name\fB)\fR" 4
 210 .el .IP "\fB$metainstance\->initialize_slot($instance_structure, \f(CB$slot_name\fB)\fR" 4
 211 .IX Item "$metainstance->initialize_slot($instance_structure, $slot_name)"
 212 .ie n .IP "\fB$metainstance\->deinitialize_slot($instance_structure, \fB$slot_name\fB)\fR" 4
 213 .el .IP "\fB$metainstance\->deinitialize_slot($instance_structure, \f(CB$slot_name\fB)\fR" 4
 214 .IX Item "$metainstance->deinitialize_slot($instance_structure, $slot_name)"
 215 .IP "\fB$metainstance\->initialize_all_slots($instance_structure)\fR" 4
 216 .IX Item "$metainstance->initialize_all_slots($instance_structure)"
 217 .IP "\fB$metainstance\->deinitialize_all_slots($instance_structure)\fR" 4
 218 .IX Item "$metainstance->deinitialize_all_slots($instance_structure)"
 219 .ie n .IP "\fB$metainstance\->is_slot_initialized($instance_structure, \fB$slot_name\fB)\fR" 4
 220 .el .IP "\fB$metainstance\->is_slot_initialized($instance_structure, \f(CB$slot_name\fB)\fR" 4
 221 .IX Item "$metainstance->is_slot_initialized($instance_structure, $slot_name)"
 222 .ie n .IP "\fB$metainstance\->weaken_slot_value($instance_structure, \fB$slot_name\fB)\fR" 4
 223 .el .IP "\fB$metainstance\->weaken_slot_value($instance_structure, \f(CB$slot_name\fB)\fR" 4
 224 .IX Item "$metainstance->weaken_slot_value($instance_structure, $slot_name)"
 225 .ie n .IP "\fB$metainstance\->strengthen_slot_value($instance_structure, \fB$slot_name\fB)\fR" 4
 226 .el .IP "\fB$metainstance\->strengthen_slot_value($instance_structure, \f(CB$slot_name\fB)\fR" 4
 227 .IX Item "$metainstance->strengthen_slot_value($instance_structure, $slot_name)"
 228 .ie n .IP "\fB$metainstance\->rebless_instance_structure($instance_structure, \fB$new_metaclass\fB)\fR" 4
 229 .el .IP "\fB$metainstance\->rebless_instance_structure($instance_structure, \f(CB$new_metaclass\fB)\fR" 4
 230 .IX Item "$metainstance->rebless_instance_structure($instance_structure, $new_metaclass)"
 231 .PD
 232 The exact details of what each method does should be fairly obvious
 233 from the method name.
 234 .Sh "Inlinable Instance Operations"
 235 .IX Subsection "Inlinable Instance Operations"
 236 .IP "\fB$metainstance\->is_inlinable\fR" 4
 237 .IX Item "$metainstance->is_inlinable"
 238 This is a boolean that indicates whether or not slot access operations
 239 can be inlined. By default it is true, but subclasses can override
 240 this.
 241 .IP "\fB$metainstance\->inline_create_instance($class_variable)\fR" 4
 242 .IX Item "$metainstance->inline_create_instance($class_variable)"
 243 This method expects a string that, \fIwhen inlined\fR, will become a
 244 class name. This would literally be something like \f(CW'$class'\fR, not an
 245 actual class name.
 246 .Sp
 247 It returns a snippet of code that creates a new object for the
 248 class. This is something like \f(CW\*(C` bless {}, $class_name \*(C'\fR.
 249 .ie n .IP "\fB$metainstance\->inline_slot_access($instance_variable, \fB$slot_name\fB)\fR" 4
 250 .el .IP "\fB$metainstance\->inline_slot_access($instance_variable, \f(CB$slot_name\fB)\fR" 4
 251 .IX Item "$metainstance->inline_slot_access($instance_variable, $slot_name)"
 252 .PD 0
 253 .ie n .IP "\fB$metainstance\->inline_get_slot_value($instance_variable, \fB$slot_name\fB)\fR" 4
 254 .el .IP "\fB$metainstance\->inline_get_slot_value($instance_variable, \f(CB$slot_name\fB)\fR" 4
 255 .IX Item "$metainstance->inline_get_slot_value($instance_variable, $slot_name)"
 256 .ie n .IP "\fB$metainstance\->inline_set_slot_value($instance_variable, \fB$slot_name\fB, \f(BI$value\fB)\fR" 4
 257 .el .IP "\fB$metainstance\->inline_set_slot_value($instance_variable, \f(CB$slot_name\fB, \f(CB$value\fB)\fR" 4
 258 .IX Item "$metainstance->inline_set_slot_value($instance_variable, $slot_name, $value)"
 259 .ie n .IP "\fB$metainstance\->inline_initialize_slot($instance_variable, \fB$slot_name\fB)\fR" 4
 260 .el .IP "\fB$metainstance\->inline_initialize_slot($instance_variable, \f(CB$slot_name\fB)\fR" 4
 261 .IX Item "$metainstance->inline_initialize_slot($instance_variable, $slot_name)"
 262 .ie n .IP "\fB$metainstance\->inline_deinitialize_slot($instance_variable, \fB$slot_name\fB)\fR" 4
 263 .el .IP "\fB$metainstance\->inline_deinitialize_slot($instance_variable, \f(CB$slot_name\fB)\fR" 4
 264 .IX Item "$metainstance->inline_deinitialize_slot($instance_variable, $slot_name)"
 265 .ie n .IP "\fB$metainstance\->inline_is_slot_initialized($instance_variable, \fB$slot_name\fB)\fR" 4
 266 .el .IP "\fB$metainstance\->inline_is_slot_initialized($instance_variable, \f(CB$slot_name\fB)\fR" 4
 267 .IX Item "$metainstance->inline_is_slot_initialized($instance_variable, $slot_name)"
 268 .ie n .IP "\fB$metainstance\->inline_weaken_slot_value($instance_variable, \fB$slot_name\fB)\fR" 4
 269 .el .IP "\fB$metainstance\->inline_weaken_slot_value($instance_variable, \f(CB$slot_name\fB)\fR" 4
 270 .IX Item "$metainstance->inline_weaken_slot_value($instance_variable, $slot_name)"
 271 .ie n .IP "\fB$metainstance\->inline_strengthen_slot_value($instance_variable, \fB$slot_name\fB)\fR" 4
 272 .el .IP "\fB$metainstance\->inline_strengthen_slot_value($instance_variable, \f(CB$slot_name\fB)\fR" 4
 273 .IX Item "$metainstance->inline_strengthen_slot_value($instance_variable, $slot_name)"
 274 .PD
 275 These methods all expect two arguments. The first is the name of a
 276 variable, than when inlined, will represent the object
 277 instance. Typically this will be a literal string like \f(CW'$_[0]'\fR.
 278 .Sp
 279 The second argument is a slot name.
 280 .Sp
 281 The method returns a snippet of code that, when inlined, performs some
 282 operation on the instance.
 283 .ie n .IP "\fB$metainstance\->inline_rebless_instance_structure($instance_variable, \fB$class_variable\fB)\fR" 4
 284 .el .IP "\fB$metainstance\->inline_rebless_instance_structure($instance_variable, \f(CB$class_variable\fB)\fR" 4
 285 .IX Item "$metainstance->inline_rebless_instance_structure($instance_variable, $class_variable)"
 286 This takes the name of a variable that will, when inlined, represent the object
 287 instance, and the name of a variable that will represent the class to rebless
 288 into, and returns code to rebless an instance into a class.
 289 .Sh "Introspection"
 290 .IX Subsection "Introspection"
 291 .IP "\fBClass::MOP::Instance\->meta\fR" 4
 292 .IX Item "Class::MOP::Instance->meta"
 293 This will return a Class::MOP::Class instance for this class.
 294 .Sp
 295 It should also be noted that Class::MOP will actually bootstrap
 296 this module by installing a number of attribute meta-objects into its
 297 metaclass.
 298 .SH "AUTHORS"
 299 .IX Header "AUTHORS"
 300 Yuval Kogman <nothingmuch@woobling.com>
 301 .PP
 302 Stevan Little <stevan@iinteractive.com>
 303 .SH "COPYRIGHT AND LICENSE"
 304 .IX Header "COPYRIGHT AND LICENSE"
 305 Copyright 2006\-2009 by Infinity Interactive, Inc.
 306 .PP
 307 <http://www.iinteractive.com>
 308 .PP
 309 This library is free software; you can redistribute it and/or modify
 310 it under the same terms as Perl itself.