local-lib5/man/man3/Mouse::Meta::Attribute.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Mouse::Meta::Attribute 3"
 127 .TH Mouse::Meta::Attribute 3 "2009-12-07" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Mouse::Meta::Attribute \- The Mouse attribute metaclass
 134 .SH "VERSION"
 135 .IX Header "VERSION"
 136 This document describes Mouse version 0.43
 137 .SH "METHODS"
 138 .IX Header "METHODS"
 139 .ie n .SS """new(%options) \-> Mouse::Meta::Attribute"""
 140 .el .SS "\f(CWnew(%options) \-> Mouse::Meta::Attribute\fP"
 141 .IX Subsection "new(%options) -> Mouse::Meta::Attribute"
 142 Instantiates a new Mouse::Meta::Attribute. Does nothing else.
 143 .PP
 144 It adds the following options to the constructor:
 145 .ie n .IP """is => \*(Aqro\*(Aq, \*(Aqrw\*(Aq, \*(Aqbare\*(Aq""" 4
 146 .el .IP "\f(CWis => \*(Aqro\*(Aq, \*(Aqrw\*(Aq, \*(Aqbare\*(Aq\fR" 4
 147 .IX Item "is => ro, rw, bare"
 148 This provides a shorthand for specifying the \f(CW\*(C`reader\*(C'\fR, \f(CW\*(C`writer\*(C'\fR, or
 149 \&\f(CW\*(C`accessor\*(C'\fR names. If the attribute is read-only ('ro') then it will
 150 have a \f(CW\*(C`reader\*(C'\fR method with the same attribute as the name.
 151 .Sp
 152 If it is read-write ('rw') then it will have an \f(CW\*(C`accessor\*(C'\fR method
 153 with the same name. If you provide an explicit \f(CW\*(C`writer\*(C'\fR for a
 154 read-write attribute, then you will have a \f(CW\*(C`reader\*(C'\fR with the same
 155 name as the attribute, and a \f(CW\*(C`writer\*(C'\fR with the name you provided.
 156 .Sp
 157 Use 'bare' when you are deliberately not installing any methods
 158 (accessor, reader, etc.) associated with this attribute; otherwise,
 159 Moose will issue a deprecation warning when this attribute is added to a
 160 metaclass.
 161 .ie n .IP """isa => Type""" 4
 162 .el .IP "\f(CWisa => Type\fR" 4
 163 .IX Item "isa => Type"
 164 This option accepts a type. The type can be a string, which should be
 165 a type name. If the type name is unknown, it is assumed to be a class
 166 name.
 167 .Sp
 168 This option can also accept a Moose::Meta::TypeConstraint object.
 169 .Sp
 170 If you \fIalso\fR provide a \f(CW\*(C`does\*(C'\fR option, then your \f(CW\*(C`isa\*(C'\fR option must
 171 be a class name, and that class must do the role specified with
 172 \&\f(CW\*(C`does\*(C'\fR.
 173 .ie n .IP """does => Role""" 4
 174 .el .IP "\f(CWdoes => Role\fR" 4
 175 .IX Item "does => Role"
 176 This is short-hand for saying that the attribute's type must be an
 177 object which does the named role.
 178 .Sp
 179 \&\fBThis option is not yet supported.\fR
 180 .ie n .IP """coerce => Bool""" 4
 181 .el .IP "\f(CWcoerce => Bool\fR" 4
 182 .IX Item "coerce => Bool"
 183 This option is only valid for objects with a type constraint
 184 (\f(CW\*(C`isa\*(C'\fR). If this is true, then coercions will be applied whenever
 185 this attribute is set.
 186 .Sp
 187 You can make both this and the \f(CW\*(C`weak_ref\*(C'\fR option true.
 188 .ie n .IP """trigger => CodeRef""" 4
 189 .el .IP "\f(CWtrigger => CodeRef\fR" 4
 190 .IX Item "trigger => CodeRef"
 191 This option accepts a subroutine reference, which will be called after
 192 the attribute is set.
 193 .ie n .IP """required => Bool""" 4
 194 .el .IP "\f(CWrequired => Bool\fR" 4
 195 .IX Item "required => Bool"
 196 An attribute which is required must be provided to the constructor. An
 197 attribute which is required can also have a \f(CW\*(C`default\*(C'\fR or \f(CW\*(C`builder\*(C'\fR,
 198 which will satisfy its required-ness.
 199 .Sp
 200 A required attribute must have a \f(CW\*(C`default\*(C'\fR, \f(CW\*(C`builder\*(C'\fR or a
 201 non\-\f(CW\*(C`undef\*(C'\fR \f(CW\*(C`init_arg\*(C'\fR
 202 .ie n .IP """lazy => Bool""" 4
 203 .el .IP "\f(CWlazy => Bool\fR" 4
 204 .IX Item "lazy => Bool"
 205 A lazy attribute must have a \f(CW\*(C`default\*(C'\fR or \f(CW\*(C`builder\*(C'\fR. When an
 206 attribute is lazy, the default value will not be calculated until the
 207 attribute is read.
 208 .ie n .IP """weak_ref => Bool""" 4
 209 .el .IP "\f(CWweak_ref => Bool\fR" 4
 210 .IX Item "weak_ref => Bool"
 211 If this is true, the attribute's value will be stored as a weak
 212 reference.
 213 .ie n .IP """auto_deref => Bool""" 4
 214 .el .IP "\f(CWauto_deref => Bool\fR" 4
 215 .IX Item "auto_deref => Bool"
 216 If this is true, then the reader will dereference the value when it is
 217 called. The attribute must have a type constraint which defines the
 218 attribute as an array or hash reference.
 219 .ie n .IP """lazy_build => Bool""" 4
 220 .el .IP "\f(CWlazy_build => Bool\fR" 4
 221 .IX Item "lazy_build => Bool"
 222 Setting this to true makes the attribute lazy and provides a number of
 223 default methods.
 224 .Sp
 225 .Vb 4
 226 \&  has \*(Aqsize\*(Aq => (
 227 \&      is         => \*(Aqro\*(Aq,
 228 \&      lazy_build => 1,
 229 \&  );
 230 .Ve
 231 .Sp
 232 is equivalent to this:
 233 .Sp
 234 .Vb 7
 235 \&  has \*(Aqsize\*(Aq => (
 236 \&      is        => \*(Aqro\*(Aq,
 237 \&      lazy      => 1,
 238 \&      builder   => \*(Aq_build_size\*(Aq,
 239 \&      clearer   => \*(Aqclear_size\*(Aq,
 240 \&      predicate => \*(Aqhas_size\*(Aq,
 241 \&  );
 242 .Ve
 243 .ie n .SS """associate_method(MethodName)"""
 244 .el .SS "\f(CWassociate_method(MethodName)\fP"
 245 .IX Subsection "associate_method(MethodName)"
 246 Associates a method with the attribute. Typically, this is called internally
 247 when an attribute generates its accessors.
 248 .PP
 249 Currently the argument \fIMethodName\fR is ignored in Mouse.
 250 .ie n .SS """verify_against_type_constraint(Item) \-> TRUE | ERROR"""
 251 .el .SS "\f(CWverify_against_type_constraint(Item) \-> TRUE | ERROR\fP"
 252 .IX Subsection "verify_against_type_constraint(Item) -> TRUE | ERROR"
 253 Checks that the given value passes this attribute's type constraint. Returns \f(CW\*(C`true\*(C'\fR
 254 on success, otherwise \f(CW\*(C`confess\*(C'\fRes.
 255 .ie n .SS """clone_and_inherit_options(options) \-> Mouse::Meta::Attribute"""
 256 .el .SS "\f(CWclone_and_inherit_options(options) \-> Mouse::Meta::Attribute\fP"
 257 .IX Subsection "clone_and_inherit_options(options) -> Mouse::Meta::Attribute"
 258 Creates a new attribute in the owner class, inheriting options from parent classes.
 259 Accessors and helper methods are installed. Some error checking is done.
 260 .ie n .SS """get_read_method_ref"""
 261 .el .SS "\f(CWget_read_method_ref\fP"
 262 .IX Subsection "get_read_method_ref"
 263 .ie n .SS """get_write_method_ref"""
 264 .el .SS "\f(CWget_write_method_ref\fP"
 265 .IX Subsection "get_write_method_ref"
 266 Returns the subroutine reference of a method suitable for reading or
 267 writing the attribute's value in the associated class. These methods
 268 always return a subroutine reference, regardless of whether or not the
 269 attribute is read\- or write-only.
 270 .SH "SEE ALSO"
 271 .IX Header "SEE ALSO"
 272 Moose::Meta::Attribute
 273 .PP
 274 Class::MOP::Attribute