Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Moose::Cookbook::Meta::Recipe7.3pm

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Moose::Cookbook::Meta::Recipe7 3"
.TH Moose::Cookbook::Meta::Recipe7 3 "2009-03-27" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Moose::Cookbook::Meta::Recipe7 \- Creating a glob reference meta\-instance class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package My::Meta::Instance;
.Ve
.PP
.Vb 2
\&  use Scalar::Util qw( weaken );
\&  use Symbol qw( gensym );
.Ve
.PP
.Vb 2
\&  use Moose;
\&  extends 'Moose::Meta::Instance';
.Ve
.PP
.Vb 5
\&  sub create_instance {
\&      my $self = shift;
\&      my $sym = gensym();
\&      bless $sym, $self\->_class_name;
\&  }
.Ve
.PP
.Vb 2
\&  sub clone_instance {
\&      my ( $self, $instance ) = @_;
.Ve
.PP
.Vb 2
\&      my $new_sym = gensym();
\&      %{*$new_sym} = %{*$instance};
.Ve
.PP
.Vb 2
\&      bless $new_sym, $self\->_class_name;
\&  }
.Ve
.PP
.Vb 4
\&  sub get_slot_value {
\&      my ( $self, $instance, $slot_name ) = @_;
\&      return *$instance\->{$slot_name};
\&  }
.Ve
.PP
.Vb 4
\&  sub set_slot_value {
\&      my ( $self, $instance, $slot_name, $value ) = @_;
\&      *$instance\->{$slot_name} = $value;
\&  }
.Ve
.PP
.Vb 4
\&  sub deinitialize_slot {
\&      my ( $self, $instance, $slot_name ) = @_;
\&      delete *$instance\->{$slot_name};;
\&  }
.Ve
.PP
.Vb 4
\&  sub is_slot_initialized {
\&      my ( $self, $instance, $slot_name, $value ) = @_;
\&      exists *$instance\->{$slot_name};;
\&  }
.Ve
.PP
.Vb 4
\&  sub weaken_slot_value {
\&      my ( $self, $instance, $slot_name ) = @_;
\&      weaken *$instance\->{$slot_name};;
\&  }
.Ve
.PP
.Vb 4
\&  sub inline_create_instance {
\&      my ( $self, $class_variable ) = @_;
\&      return 'do { my $sym = Symbol::gensym(); bless $sym, ' . $class_variable . ' }';
\&  }
.Ve
.PP
.Vb 4
\&  sub inline_slot_access {
\&      my ( $self, $instance, $slot_name ) = @_;
\&      return '*{' . $instance . '}\->{' . $slot_name . '}';
\&  }
.Ve
.PP
.Vb 1
\&  package MyApp::User;
.Ve
.PP
.Vb 2
\&  use metaclass 'Moose::Meta::Class' =>
\&      ( instance_metaclass => 'My::Meta::Instance' );
.Ve
.PP
.Vb 1
\&  use Moose;
.Ve
.PP
.Vb 4
\&  has 'name' => (
\&      is  => 'rw',
\&      isa => 'Str',
\&  );
.Ve
.PP
.Vb 4
\&  has 'email' => (
\&      is  => 'rw',
\&      isa => 'Str',
\&  );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This recipe shows how to build your own meta\-instance. The meta
instance is the metaclass that creates object instances and helps
manages access to attribute slots.
.PP
In this example, we're creating a meta-instance that is based on a
glob reference rather than a hash reference. This example is largely
based on the Piotr Roszatycki's MooseX::GlobRef module.
.PP
Our class is a subclass of Moose::Meta::Instance, which creates
hash reference based objects. We need to override all the methods
which make assumptions about the object's data structure.
.PP
The first method we override is \f(CW\*(C`create_instance\*(C'\fR:
.PP
.Vb 5
\&  sub create_instance {
\&      my $self = shift;
\&      my $sym = gensym();
\&      bless $sym, $self\->_class_name;
\&  }
.Ve
.PP
This returns an glob reference which has been blessed into our
meta\-instance's associated class.
.PP
We also override \f(CW\*(C`clone_instance\*(C'\fR to create a new array reference:
.PP
.Vb 2
\&  sub clone_instance {
\&      my ( $self, $instance ) = @_;
.Ve
.PP
.Vb 2
\&      my $new_sym = gensym();
\&      %{*$new_sym} = %{*$instance};
.Ve
.PP
.Vb 2
\&      bless $new_sym, $self\->_class_name;
\&  }
.Ve
.PP
After that, we have a series of methods which mediate access to the
object's slots (attributes are stored in \*(L"slots\*(R"). In the default
instance class, these expect the object to be a hash reference, but we
need to change this to expect a glob reference instead.
.PP
.Vb 4
\&  sub get_slot_value {
\&      my ( $self, $instance, $slot_name ) = @_;
\&      *$instance\->{$slot_name};;
\&  }
.Ve
.PP
This level of indirection probably makes our instance class \fIslower\fR
than the default. However, when attribute access is inlined, this
lookup will be cached:
.PP
.Vb 4
\&  sub inline_create_instance {
\&      my ( $self, $class_variable ) = @_;
\&      return 'do { my $sym = Symbol::gensym(); bless $sym, ' . $class_variable . ' }';
\&  }
.Ve
.PP
The code snippet that the \f(CW\*(C`inline_slot_access\*(C'\fR method returns will
get \f(CW\*(C`eval\*(C'\fR'd once per attribute.
.PP
Finally, we use this meta-instance in our \f(CW\*(C`MyApp::User\*(C'\fR class:
.PP
.Vb 2
\&  use metaclass 'Moose::Meta::Class' =>
\&      ( instance_metaclass => 'My::Meta::Instance' );
.Ve
.PP
We actually don't recommend the use of metaclass in most
cases. However, the other ways of using alternate metaclasses are more
complex, and would complicate our example code unnecessarily.
.SH "CONCLUSION"
.IX Header "CONCLUSION"
This recipe shows how to create your own meta-instance class. It's
unlikely that you'll need to do this yourself, but it's interesting to
take a peek at how Moose works under the hood.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
There are a few meta-instance class extensions on \s-1CPAN:\s0
.IP "* MooseX::Singleton" 4
.IX Item "MooseX::Singleton"
This module extends the instance class in order to ensure that the
object is a singleton. The instance it uses is still a blessed hash
reference.
.IP "* MooseX::GlobRef" 4
.IX Item "MooseX::GlobRef"
This module makes the instance a blessed glob reference. This lets you
use a handle as an object instance.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2006\-2009 by Infinity Interactive, Inc.
.PP
<http://www.iinteractive.com>
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.