local-lib5/man/man3/Moose::Cookbook::Meta::Recipe7.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::Cookbook::Meta::Recipe7 3"
 132 .TH Moose::Cookbook::Meta::Recipe7 3 "2009-03-27" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Meta::Recipe7 \- Creating a glob reference meta\-instance class
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  package My::Meta::Instance;
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&  use Scalar::Util qw( weaken );
 143 \&  use Symbol qw( gensym );
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&  use Moose;
 148 \&  extends 'Moose::Meta::Instance';
 149 .Ve
 150 .PP
 151 .Vb 5
 152 \&  sub create_instance {
 153 \&      my $self = shift;
 154 \&      my $sym = gensym();
 155 \&      bless $sym, $self\->_class_name;
 156 \&  }
 157 .Ve
 158 .PP
 159 .Vb 2
 160 \&  sub clone_instance {
 161 \&      my ( $self, $instance ) = @_;
 162 .Ve
 163 .PP
 164 .Vb 2
 165 \&      my $new_sym = gensym();
 166 \&      %{*$new_sym} = %{*$instance};
 167 .Ve
 168 .PP
 169 .Vb 2
 170 \&      bless $new_sym, $self\->_class_name;
 171 \&  }
 172 .Ve
 173 .PP
 174 .Vb 4
 175 \&  sub get_slot_value {
 176 \&      my ( $self, $instance, $slot_name ) = @_;
 177 \&      return *$instance\->{$slot_name};
 178 \&  }
 179 .Ve
 180 .PP
 181 .Vb 4
 182 \&  sub set_slot_value {
 183 \&      my ( $self, $instance, $slot_name, $value ) = @_;
 184 \&      *$instance\->{$slot_name} = $value;
 185 \&  }
 186 .Ve
 187 .PP
 188 .Vb 4
 189 \&  sub deinitialize_slot {
 190 \&      my ( $self, $instance, $slot_name ) = @_;
 191 \&      delete *$instance\->{$slot_name};;
 192 \&  }
 193 .Ve
 194 .PP
 195 .Vb 4
 196 \&  sub is_slot_initialized {
 197 \&      my ( $self, $instance, $slot_name, $value ) = @_;
 198 \&      exists *$instance\->{$slot_name};;
 199 \&  }
 200 .Ve
 201 .PP
 202 .Vb 4
 203 \&  sub weaken_slot_value {
 204 \&      my ( $self, $instance, $slot_name ) = @_;
 205 \&      weaken *$instance\->{$slot_name};;
 206 \&  }
 207 .Ve
 208 .PP
 209 .Vb 4
 210 \&  sub inline_create_instance {
 211 \&      my ( $self, $class_variable ) = @_;
 212 \&      return 'do { my $sym = Symbol::gensym(); bless $sym, ' . $class_variable . ' }';
 213 \&  }
 214 .Ve
 215 .PP
 216 .Vb 4
 217 \&  sub inline_slot_access {
 218 \&      my ( $self, $instance, $slot_name ) = @_;
 219 \&      return '*{' . $instance . '}\->{' . $slot_name . '}';
 220 \&  }
 221 .Ve
 222 .PP
 223 .Vb 1
 224 \&  package MyApp::User;
 225 .Ve
 226 .PP
 227 .Vb 2
 228 \&  use metaclass 'Moose::Meta::Class' =>
 229 \&      ( instance_metaclass => 'My::Meta::Instance' );
 230 .Ve
 231 .PP
 232 .Vb 1
 233 \&  use Moose;
 234 .Ve
 235 .PP
 236 .Vb 4
 237 \&  has 'name' => (
 238 \&      is  => 'rw',
 239 \&      isa => 'Str',
 240 \&  );
 241 .Ve
 242 .PP
 243 .Vb 4
 244 \&  has 'email' => (
 245 \&      is  => 'rw',
 246 \&      isa => 'Str',
 247 \&  );
 248 .Ve
 249 .SH "DESCRIPTION"
 250 .IX Header "DESCRIPTION"
 251 This recipe shows how to build your own meta\-instance. The meta
 252 instance is the metaclass that creates object instances and helps
 253 manages access to attribute slots.
 254 .PP
 255 In this example, we're creating a meta-instance that is based on a
 256 glob reference rather than a hash reference. This example is largely
 257 based on the Piotr Roszatycki's MooseX::GlobRef module.
 258 .PP
 259 Our class is a subclass of Moose::Meta::Instance, which creates
 260 hash reference based objects. We need to override all the methods
 261 which make assumptions about the object's data structure.
 262 .PP
 263 The first method we override is \f(CW\*(C`create_instance\*(C'\fR:
 264 .PP
 265 .Vb 5
 266 \&  sub create_instance {
 267 \&      my $self = shift;
 268 \&      my $sym = gensym();
 269 \&      bless $sym, $self\->_class_name;
 270 \&  }
 271 .Ve
 272 .PP
 273 This returns an glob reference which has been blessed into our
 274 meta\-instance's associated class.
 275 .PP
 276 We also override \f(CW\*(C`clone_instance\*(C'\fR to create a new array reference:
 277 .PP
 278 .Vb 2
 279 \&  sub clone_instance {
 280 \&      my ( $self, $instance ) = @_;
 281 .Ve
 282 .PP
 283 .Vb 2
 284 \&      my $new_sym = gensym();
 285 \&      %{*$new_sym} = %{*$instance};
 286 .Ve
 287 .PP
 288 .Vb 2
 289 \&      bless $new_sym, $self\->_class_name;
 290 \&  }
 291 .Ve
 292 .PP
 293 After that, we have a series of methods which mediate access to the
 294 object's slots (attributes are stored in \*(L"slots\*(R"). In the default
 295 instance class, these expect the object to be a hash reference, but we
 296 need to change this to expect a glob reference instead.
 297 .PP
 298 .Vb 4
 299 \&  sub get_slot_value {
 300 \&      my ( $self, $instance, $slot_name ) = @_;
 301 \&      *$instance\->{$slot_name};;
 302 \&  }
 303 .Ve
 304 .PP
 305 This level of indirection probably makes our instance class \fIslower\fR
 306 than the default. However, when attribute access is inlined, this
 307 lookup will be cached:
 308 .PP
 309 .Vb 4
 310 \&  sub inline_create_instance {
 311 \&      my ( $self, $class_variable ) = @_;
 312 \&      return 'do { my $sym = Symbol::gensym(); bless $sym, ' . $class_variable . ' }';
 313 \&  }
 314 .Ve
 315 .PP
 316 The code snippet that the \f(CW\*(C`inline_slot_access\*(C'\fR method returns will
 317 get \f(CW\*(C`eval\*(C'\fR'd once per attribute.
 318 .PP
 319 Finally, we use this meta-instance in our \f(CW\*(C`MyApp::User\*(C'\fR class:
 320 .PP
 321 .Vb 2
 322 \&  use metaclass 'Moose::Meta::Class' =>
 323 \&      ( instance_metaclass => 'My::Meta::Instance' );
 324 .Ve
 325 .PP
 326 We actually don't recommend the use of metaclass in most
 327 cases. However, the other ways of using alternate metaclasses are more
 328 complex, and would complicate our example code unnecessarily.
 329 .SH "CONCLUSION"
 330 .IX Header "CONCLUSION"
 331 This recipe shows how to create your own meta-instance class. It's
 332 unlikely that you'll need to do this yourself, but it's interesting to
 333 take a peek at how Moose works under the hood.
 334 .SH "SEE ALSO"
 335 .IX Header "SEE ALSO"
 336 There are a few meta-instance class extensions on \s-1CPAN:\s0
 337 .IP "* MooseX::Singleton" 4
 338 .IX Item "MooseX::Singleton"
 339 This module extends the instance class in order to ensure that the
 340 object is a singleton. The instance it uses is still a blessed hash
 341 reference.
 342 .IP "* MooseX::GlobRef" 4
 343 .IX Item "MooseX::GlobRef"
 344 This module makes the instance a blessed glob reference. This lets you
 345 use a handle as an object instance.
 346 .SH "AUTHOR"
 347 .IX Header "AUTHOR"
 348 Dave Rolsky <autarch@urth.org>
 349 .SH "COPYRIGHT AND LICENSE"
 350 .IX Header "COPYRIGHT AND LICENSE"
 351 Copyright 2006\-2009 by Infinity Interactive, Inc.
 352 .PP
 353 <http://www.iinteractive.com>
 354 .PP
 355 This library is free software; you can redistribute it and/or modify
 356 it under the same terms as Perl itself.