Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Moose::Meta::Attribute.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::Meta::Attribute 3"
.TH Moose::Meta::Attribute 3 "2009-11-19" "perl v5.8.7" "User Contributed Perl Documentation"
.SH "NAME"
Moose::Meta::Attribute \- The Moose attribute metaclass
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is a subclass of Class::MOP::Attribute that provides
additional Moose-specific functionality.
.PP
To really understand this class, you will need to start with the
Class::MOP::Attribute documentation. This class can be understood
as a set of additional features on top of the basic feature provided
by that parent class.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
\&\f(CW\*(C`Moose::Meta::Attribute\*(C'\fR is a subclass of Class::MOP::Attribute.
.SH "METHODS"
.IX Header "METHODS"
Many of the documented below override methods in
Class::MOP::Attribute and add Moose specific features.
.Sh "Creation"
.IX Subsection "Creation"
.IP "\fBMoose::Meta::Attribute\->new(%options)\fR" 4
.IX Item "Moose::Meta::Attribute->new(%options)"
This method overrides the Class::MOP::Attribute constructor.
.Sp
Many of the options below are described in more detail in the
Moose::Manual::Attributes document.
.Sp
It adds the following options to the constructor:
.RS 4
.IP "* is => 'ro', 'rw', 'bare'" 8
.IX Item "is => 'ro', 'rw', 'bare'"
This provides a shorthand for specifying the \f(CW\*(C`reader\*(C'\fR, \f(CW\*(C`writer\*(C'\fR, or
\&\f(CW\*(C`accessor\*(C'\fR names. If the attribute is read-only ('ro') then it will
have a \f(CW\*(C`reader\*(C'\fR method with the same attribute as the name.
.Sp
If it is read-write ('rw') then it will have an \f(CW\*(C`accessor\*(C'\fR method
with the same name. If you provide an explicit \f(CW\*(C`writer\*(C'\fR for a
read-write attribute, then you will have a \f(CW\*(C`reader\*(C'\fR with the same
name as the attribute, and a \f(CW\*(C`writer\*(C'\fR with the name you provided.
.Sp
Use 'bare' when you are deliberately not installing any methods
(accessor, reader, etc.) associated with this attribute; otherwise,
Moose will issue a deprecation warning when this attribute is added to a
metaclass.
.ie n .IP "* isa => $type" 8
.el .IP "* isa => \f(CW$type\fR" 8
.IX Item "isa => $type"
This option accepts a type. The type can be a string, which should be
a type name. If the type name is unknown, it is assumed to be a class
name.
.Sp
This option can also accept a Moose::Meta::TypeConstraint object.
.Sp
If you \fIalso\fR provide a \f(CW\*(C`does\*(C'\fR option, then your \f(CW\*(C`isa\*(C'\fR option must
be a class name, and that class must do the role specified with
\&\f(CW\*(C`does\*(C'\fR.
.ie n .IP "* does => $role" 8
.el .IP "* does => \f(CW$role\fR" 8
.IX Item "does => $role"
This is short-hand for saying that the attribute's type must be an
object which does the named role.
.ie n .IP "* coerce => $bool" 8
.el .IP "* coerce => \f(CW$bool\fR" 8
.IX Item "coerce => $bool"
This option is only valid for objects with a type constraint
(\f(CW\*(C`isa\*(C'\fR). If this is true, then coercions will be applied whenever
this attribute is set.
.Sp
You can make both this and the \f(CW\*(C`weak_ref\*(C'\fR option true.
.ie n .IP "* trigger => $sub" 8
.el .IP "* trigger => \f(CW$sub\fR" 8
.IX Item "trigger => $sub"
This option accepts a subroutine reference, which will be called after
the attribute is set.
.ie n .IP "* required => $bool" 8
.el .IP "* required => \f(CW$bool\fR" 8
.IX Item "required => $bool"
An attribute which is required must be provided to the constructor. An
attribute which is required can also have a \f(CW\*(C`default\*(C'\fR or \f(CW\*(C`builder\*(C'\fR,
which will satisfy its required\-ness.
.Sp
A required attribute must have a \f(CW\*(C`default\*(C'\fR, \f(CW\*(C`builder\*(C'\fR or a
non\-\f(CW\*(C`undef\*(C'\fR \f(CW\*(C`init_arg\*(C'\fR
.ie n .IP "* lazy => $bool" 8
.el .IP "* lazy => \f(CW$bool\fR" 8
.IX Item "lazy => $bool"
A lazy attribute must have a \f(CW\*(C`default\*(C'\fR or \f(CW\*(C`builder\*(C'\fR. When an
attribute is lazy, the default value will not be calculated until the
attribute is read.
.ie n .IP "* weak_ref => $bool" 8
.el .IP "* weak_ref => \f(CW$bool\fR" 8
.IX Item "weak_ref => $bool"
If this is true, the attribute's value will be stored as a weak
reference.
.ie n .IP "* auto_deref => $bool" 8
.el .IP "* auto_deref => \f(CW$bool\fR" 8
.IX Item "auto_deref => $bool"
If this is true, then the reader will dereference the value when it is
called. The attribute must have a type constraint which defines the
attribute as an array or hash reference.
.ie n .IP "* lazy_build => $bool" 8
.el .IP "* lazy_build => \f(CW$bool\fR" 8
.IX Item "lazy_build => $bool"
Setting this to true makes the attribute lazy and provides a number of
default methods.
.Sp
.Vb 4
\&  has 'size' => (
\&      is         => 'ro',
\&      lazy_build => 1,
\&  );
.Ve
.Sp
is equivalent to this:
.Sp
.Vb 7
\&  has 'size' => (
\&      is        => 'ro',
\&      lazy      => 1,
\&      builder   => '_build_size',
\&      clearer   => 'clear_size',
\&      predicate => 'has_size',
\&  );
.Ve
.IP "* documentation" 8
.IX Item "documentation"
An arbitrary string that can be retrieved later by calling \f(CW\*(C`$attr\->documentation\*(C'\fR.
.RE
.RS 4
.RE
.IP "\fB$attr\->clone(%options)\fR" 4
.IX Item "$attr->clone(%options)"
This creates a new attribute based on attribute being cloned. You must
supply a \f(CW\*(C`name\*(C'\fR option to provide a new name for the attribute.
.Sp
The \f(CW%options\fR can only specify options handled by
Class::MOP::Attribute.
.Sh "Value management"
.IX Subsection "Value management"
.ie n .IP "\fB$attr\->initialize_instance_slot($meta_instance, \fB$instance\fB, \f(BI$params\fB)\fR" 4
.el .IP "\fB$attr\->initialize_instance_slot($meta_instance, \f(CB$instance\fB, \f(CB$params\fB)\fR" 4
.IX Item "$attr->initialize_instance_slot($meta_instance, $instance, $params)"
This method is used internally to initialize the attribute's slot in
the object \f(CW$instance\fR.
.Sp
This overrides the Class::MOP::Attribute method to handle lazy
attributes, weak references, and type constraints.
.IP "\fBget_value\fR" 4
.IX Item "get_value"
.PD 0
.IP "\fBset_value\fR" 4
.IX Item "set_value"
.PD
.Vb 4
\&  eval { $point\->meta\->get_attribute('x')\->set_value($point, 'forty\-two') };
\&  if($@) {
\&    print "Oops: $@\en";
\&  }
.Ve
.Sp
\&\fIAttribute (x) does not pass the type constraint (Int) with 'forty\-two'\fR
.Sp
Before setting the value, a check is made on the type constraint of
the attribute, if it has one, to see if the value passes it. If the
value fails to pass, the set operation dies with a throw_error.
.Sp
Any coercion to convert values is done before checking the type constraint.
.Sp
To check a value against a type constraint before setting it, fetch the
attribute instance using \*(L"find_attribute_by_name\*(R" in Class::MOP::Class,
fetch the type_constraint from the attribute using \*(L"type_constraint\*(R" in Moose::Meta::Attribute
and call \*(L"check\*(R" in Moose::Meta::TypeConstraint. See Moose::Cookbook::Basics::Recipe4
for an example.
.Sh "Attribute Accessor generation"
.IX Subsection "Attribute Accessor generation"
.IP "\fB$attr\->install_accessors\fR" 4
.IX Item "$attr->install_accessors"
This method overrides the parent to also install delegation methods.
.Sp
If, after installing all methods, the attribute object has no associated
methods, it throws an error unless \f(CW\*(C`is => 'bare'\*(C'\fR was passed to the
attribute constructor.  (Trying to add an attribute that has no associated
methods is almost always an error.)
.IP "\fB$attr\->remove_accessors\fR" 4
.IX Item "$attr->remove_accessors"
This method overrides the parent to also remove delegation methods.
.IP "\fB$attr\->install_delegation\fR" 4
.IX Item "$attr->install_delegation"
This method adds its delegation methods to the attribute's associated
class, if it has any to add.
.IP "\fB$attr\->remove_delegation\fR" 4
.IX Item "$attr->remove_delegation"
This method remove its delegation methods from the attribute's
associated class.
.IP "\fB$attr\->accessor_metaclass\fR" 4
.IX Item "$attr->accessor_metaclass"
Returns the accessor metaclass name, which defaults to
Moose::Meta::Method::Accessor.
.IP "\fB$attr\->delegation_metaclass\fR" 4
.IX Item "$attr->delegation_metaclass"
Returns the delegation metaclass name, which defaults to
Moose::Meta::Method::Delegation.
.Sh "Additional Moose features"
.IX Subsection "Additional Moose features"
These methods are not found in the superclass. They support features
provided by Moose.
.IP "\fB$attr\->does($role)\fR" 4
.IX Item "$attr->does($role)"
This indicates whether the \fIattribute itself\fR does the given
role. The role can be given as a full class name, or as a resolvable
trait name.
.Sp
Note that this checks the attribute itself, not its type constraint,
so it is checking the attribute's metaclass and any traits applied to
the attribute.
.ie n .IP "\fBMoose::Meta::Class\->interpolate_class_and_new($name, \fB%options\fB)\fR" 4
.el .IP "\fBMoose::Meta::Class\->interpolate_class_and_new($name, \f(CB%options\fB)\fR" 4
.IX Item "Moose::Meta::Class->interpolate_class_and_new($name, %options)"
This is an alternate constructor that handles the \f(CW\*(C`metaclass\*(C'\fR and
\&\f(CW\*(C`traits\*(C'\fR options.
.Sp
Effectively, this method is a factory that finds or creates the
appropriate class for the given \f(CW\*(C`metaclass\*(C'\fR and/or \f(CW\*(C`traits\*(C'\fR.
.Sp
Once it has the appropriate class, it will call \f(CW\*(C`$class\->new($name,
%options)\*(C'\fR on that class.
.IP "\fB$attr\->clone_and_inherit_options(%options)\fR" 4
.IX Item "$attr->clone_and_inherit_options(%options)"
This method supports the \f(CW\*(C`has '+foo'\*(C'\fR feature. It does various bits
of processing on the supplied \f(CW%options\fR before ultimately calling
the \f(CW\*(C`clone\*(C'\fR method.
.Sp
One of its main tasks is to make sure that the \f(CW%options\fR provided
only includes the options returned by the
\&\f(CW\*(C`legal_options_for_inheritance\*(C'\fR method.
.IP "\fB$attr\->legal_options_for_inheritance\fR" 4
.IX Item "$attr->legal_options_for_inheritance"
This returns a whitelist of options that can be overridden in a
subclass's attribute definition.
.Sp
This exists to allow a custom metaclass to change or add to the list
of options which can be changed.
.IP "\fB$attr\->type_constraint\fR" 4
.IX Item "$attr->type_constraint"
Returns the Moose::Meta::TypeConstraint object for this attribute,
if it has one.
.IP "\fB$attr\->has_type_constraint\fR" 4
.IX Item "$attr->has_type_constraint"
Returns true if this attribute has a type constraint.
.IP "\fB$attr\->verify_against_type_constraint($value)\fR" 4
.IX Item "$attr->verify_against_type_constraint($value)"
Given a value, this method returns true if the value is valid for the
attribute's type constraint. If the value is not valid, it throws an
error.
.IP "\fB$attr\->handles\fR" 4
.IX Item "$attr->handles"
This returns the value of the \f(CW\*(C`handles\*(C'\fR option passed to the
constructor.
.IP "\fB$attr\->has_handles\fR" 4
.IX Item "$attr->has_handles"
Returns true if this attribute performs delegation.
.IP "\fB$attr\->is_weak_ref\fR" 4
.IX Item "$attr->is_weak_ref"
Returns true if this attribute stores its value as a weak reference.
.IP "\fB$attr\->is_required\fR" 4
.IX Item "$attr->is_required"
Returns true if this attribute is required to have a value.
.IP "\fB$attr\->is_lazy\fR" 4
.IX Item "$attr->is_lazy"
Returns true if this attribute is lazy.
.IP "\fB$attr\->is_lazy_build\fR" 4
.IX Item "$attr->is_lazy_build"
Returns true if the \f(CW\*(C`lazy_build\*(C'\fR option was true when passed to the
constructor.
.IP "\fB$attr\->should_coerce\fR" 4
.IX Item "$attr->should_coerce"
Returns true if the \f(CW\*(C`coerce\*(C'\fR option passed to the constructor was
true.
.IP "\fB$attr\->should_auto_deref\fR" 4
.IX Item "$attr->should_auto_deref"
Returns true if the \f(CW\*(C`auto_deref\*(C'\fR option passed to the constructor was
true.
.IP "\fB$attr\->trigger\fR" 4
.IX Item "$attr->trigger"
This is the subroutine reference that was in the \f(CW\*(C`trigger\*(C'\fR option
passed to the constructor, if any.
.IP "\fB$attr\->has_trigger\fR" 4
.IX Item "$attr->has_trigger"
Returns true if this attribute has a trigger set.
.IP "\fB$attr\->documentation\fR" 4
.IX Item "$attr->documentation"
Returns the value that was in the \f(CW\*(C`documentation\*(C'\fR option passed to
the constructor, if any.
.IP "\fB$attr\->has_documentation\fR" 4
.IX Item "$attr->has_documentation"
Returns true if this attribute has any documentation.
.IP "\fB$attr\->applied_traits\fR" 4
.IX Item "$attr->applied_traits"
This returns an array reference of all the traits which were applied
to this attribute. If none were applied, this returns \f(CW\*(C`undef\*(C'\fR.
.IP "\fB$attr\->has_applied_traits\fR" 4
.IX Item "$attr->has_applied_traits"
Returns true if this attribute has any traits applied.
.SH "BUGS"
.IX Header "BUGS"
All complex software has bugs lurking in it, and this module is no
exception. If you find a bug please either email me, or add the bug
to cpan\-RT.
.SH "AUTHOR"
.IX Header "AUTHOR"
Stevan Little <stevan@iinteractive.com>
.PP
Yuval Kogman <nothingmuch@woobling.com>
.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.