local-lib5/man/man3/Class::MOP::Package.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::Package 3"
 132 .TH Class::MOP::Package 3 "2009-11-18" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Class::MOP::Package \- Package Meta Object
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 The Package Protocol provides an abstraction of a Perl 5 package. A
 138 package is basically namespace, and this module provides methods for
 139 looking at and changing that namespace's symbol table.
 140 .SH "METHODS"
 141 .IX Header "METHODS"
 142 .IP "\fBClass::MOP::Package\->initialize($package_name)\fR" 4
 143 .IX Item "Class::MOP::Package->initialize($package_name)"
 144 This method creates a new \f(CW\*(C`Class::MOP::Package\*(C'\fR instance which
 145 represents specified package. If an existing metaclass object exists
 146 for the package, that will be returned instead.
 147 .IP "\fBClass::MOP::Package\->reinitialize($package)\fR" 4
 148 .IX Item "Class::MOP::Package->reinitialize($package)"
 149 This method forcibly removes any existing metaclass for the package
 150 before calling \f(CW\*(C`initialize\*(C'\fR. In contrast to \f(CW\*(C`initialize\*(C'\fR, you may
 151 also pass an existing \f(CW\*(C`Class::MOP::Package\*(C'\fR instance instead of just
 152 a package name as \f(CW$package\fR.
 153 .Sp
 154 Do not call this unless you know what you are doing.
 155 .IP "\fB$metapackage\->name\fR" 4
 156 .IX Item "$metapackage->name"
 157 This is returns the package's name, as passed to the constructor.
 158 .IP "\fB$metapackage\->namespace\fR" 4
 159 .IX Item "$metapackage->namespace"
 160 This returns a hash reference to the package's symbol table. The keys
 161 are symbol names and the values are typeglob references.
 162 .ie n .IP "\fB$metapackage\->add_package_symbol($variable_name, \fB$initial_value\fB)\fR" 4
 163 .el .IP "\fB$metapackage\->add_package_symbol($variable_name, \f(CB$initial_value\fB)\fR" 4
 164 .IX Item "$metapackage->add_package_symbol($variable_name, $initial_value)"
 165 This method accepts a variable name and an optional initial value. The
 166 \&\f(CW$variable_name\fR must contain a leading sigil.
 167 .Sp
 168 This method creates the variable in the package's symbol table, and
 169 sets it to the initial value if one was provided.
 170 .IP "\fB$metapackage\->get_package_symbol($variable_name)\fR" 4
 171 .IX Item "$metapackage->get_package_symbol($variable_name)"
 172 Given a variable name, this method returns the variable as a reference
 173 or undef if it does not exist. The \f(CW$variable_name\fR must contain a
 174 leading sigil.
 175 .IP "\fB$metapackage\->has_package_symbol($variable_name)\fR" 4
 176 .IX Item "$metapackage->has_package_symbol($variable_name)"
 177 Returns true if there is a package variable defined for
 178 \&\f(CW$variable_name\fR. The \f(CW$variable_name\fR must contain a leading sigil.
 179 .IP "\fB$metapackage\->remove_package_symbol($variable_name)\fR" 4
 180 .IX Item "$metapackage->remove_package_symbol($variable_name)"
 181 This will remove the package variable specified \f(CW$variable_name\fR. The
 182 \&\f(CW$variable_name\fR must contain a leading sigil.
 183 .IP "\fB$metapackage\->remove_package_glob($glob_name)\fR" 4
 184 .IX Item "$metapackage->remove_package_glob($glob_name)"
 185 Given the name of a glob, this will remove that glob from the
 186 package's symbol table. Glob names do not include a sigil. Removing
 187 the glob removes all variables and subroutines with the specified
 188 name.
 189 .IP "\fB$metapackage\->list_all_package_symbols($type_filter)\fR" 4
 190 .IX Item "$metapackage->list_all_package_symbols($type_filter)"
 191 This will list all the glob names associated with the current
 192 package. These names do not have leading sigils.
 193 .Sp
 194 You can provide an optional type filter, which should be one of
 195 \&'\s-1SCALAR\s0', '\s-1ARRAY\s0', '\s-1HASH\s0', or '\s-1CODE\s0'.
 196 .IP "\fB$metapackage\->get_all_package_symbols($type_filter)\fR" 4
 197 .IX Item "$metapackage->get_all_package_symbols($type_filter)"
 198 This works much like \f(CW\*(C`list_all_package_symbols\*(C'\fR, but it returns a
 199 hash reference. The keys are glob names and the values are references
 200 to the value for that name.
 201 .Sh "Method introspection and creation"
 202 .IX Subsection "Method introspection and creation"
 203 These methods allow you to introspect a class's methods, as well as
 204 add, remove, or change methods.
 205 .PP
 206 Determining what is truly a method in a Perl 5 class requires some
 207 heuristics (aka guessing).
 208 .PP
 209 Methods defined outside the package with a fully qualified name (\f(CW\*(C`sub
 210 Package::name { ... }\*(C'\fR) will be included. Similarly, methods named
 211 with a fully qualified name using Sub::Name are also included.
 212 .PP
 213 However, we attempt to ignore imported functions.
 214 .PP
 215 Ultimately, we are using heuristics to determine what truly is a
 216 method in a class, and these heuristics may get the wrong answer in
 217 some edge cases. However, for most \*(L"normal\*(R" cases the heuristics work
 218 correctly.
 219 .IP "\fB$metapackage\->get_method($method_name)\fR" 4
 220 .IX Item "$metapackage->get_method($method_name)"
 221 This will return a Class::MOP::Method for the specified
 222 \&\f(CW$method_name\fR. If the class does not have the specified method, it
 223 returns \f(CW\*(C`undef\*(C'\fR
 224 .IP "\fB$metapackage\->has_method($method_name)\fR" 4
 225 .IX Item "$metapackage->has_method($method_name)"
 226 Returns a boolean indicating whether or not the class defines the
 227 named method. It does not include methods inherited from parent
 228 classes.
 229 .IP "\fB$metapackage\->get_method_list\fR" 4
 230 .IX Item "$metapackage->get_method_list"
 231 This will return a list of method \fInames\fR for all methods defined in
 232 this class.
 233 .ie n .IP "\fB$metapackage\->add_method($method_name, \fB$method\fB)\fR" 4
 234 .el .IP "\fB$metapackage\->add_method($method_name, \f(CB$method\fB)\fR" 4
 235 .IX Item "$metapackage->add_method($method_name, $method)"
 236 This method takes a method name and a subroutine reference, and adds
 237 the method to the class.
 238 .Sp
 239 The subroutine reference can be a Class::MOP::Method, and you are
 240 strongly encouraged to pass a meta method object instead of a code
 241 reference. If you do so, that object gets stored as part of the
 242 class's method map directly. If not, the meta information will have to
 243 be recreated later, and may be incorrect.
 244 .Sp
 245 If you provide a method object, this method will clone that object if
 246 the object's package name does not match the class name. This lets us
 247 track the original source of any methods added from other classes
 248 (notably Moose roles).
 249 .IP "\fB$metapackage\->remove_method($method_name)\fR" 4
 250 .IX Item "$metapackage->remove_method($method_name)"
 251 Remove the named method from the class. This method returns the
 252 Class::MOP::Method object for the method.
 253 .IP "\fB$metapackage\->method_metaclass\fR" 4
 254 .IX Item "$metapackage->method_metaclass"
 255 Returns the class name of the method metaclass, see
 256 Class::MOP::Method for more information on the method metaclass.
 257 .IP "\fB$metapackage\->wrapped_method_metaclass\fR" 4
 258 .IX Item "$metapackage->wrapped_method_metaclass"
 259 Returns the class name of the wrapped method metaclass, see
 260 Class::MOP::Method::Wrapped for more information on the wrapped
 261 method metaclass.
 262 .IP "\fBClass::MOP::Package\->meta\fR" 4
 263 .IX Item "Class::MOP::Package->meta"
 264 This will return a Class::MOP::Class instance for this class.
 265 .SH "AUTHORS"
 266 .IX Header "AUTHORS"
 267 Stevan Little <stevan@iinteractive.com>
 268 .SH "COPYRIGHT AND LICENSE"
 269 .IX Header "COPYRIGHT AND LICENSE"
 270 Copyright 2006\-2009 by Infinity Interactive, Inc.
 271 .PP
 272 <http://www.iinteractive.com>
 273 .PP
 274 This library is free software; you can redistribute it and/or modify
 275 it under the same terms as Perl itself.