File: //usr/local/ssl/local/share/man/man3/Cpanel::Class.3
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" 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 "Cpanel::Class 3"
.TH Cpanel::Class 3 "2009-12-16" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Cpanel::Class \- Tool to help organize and build perl classes
.Sh "Utility functions"
.IX Subsection "Utility functions"
.IP "load_class ($class_name)" 4
.IX Item "load_class ($class_name)"
.Vb 2
\& This will load a given C<$class_name> and if it does not have an
\& already initialized metaclass, then it will intialize one for it.
.Ve
.IP "is_class_loaded ($class_name)" 4
.IX Item "is_class_loaded ($class_name)"
.Vb 2
\& This will return a boolean depending on if the C<$class_name> has
\& been loaded.
.Ve
.Sp
These functions are not exported
.SH "has \- Create attributes"
.IX Header "has - Create attributes"
.ie n .IP "has $name\fR => \f(CW%options" 4
.el .IP "has \f(CW$name\fR => \f(CW%options\fR" 4
.IX Item "has $name => %options"
.PP
is => ('rw'|'ro')
.PP
.Vb 3
\& The is option accepts either rw (for read/write) or ro (for read only). These will
\& create either a read/write accessor or a read-only accessor respectively, using the
\& same name as the $name of the attribute.
.Ve
.PP
default
.PP
.Vb 1
\& Change the default value of an attribute.
.Ve
.PP
lazy => (1|0)
.PP
.Vb 2
\& This will tell the class to not create this slot until absolutely necessary. If an
\& attribute is marked as lazy it must have a default supplied.
.Ve
.PP
handles => \s-1ARRAY\s0 | \s-1HASH\s0
.PP
.Vb 1
\& The handles option provides Cpanel::Class classes with automated delegation features.
.Ve
.PP
.Vb 1
\& ARRAY
.Ve
.PP
.Vb 2
\& This is the most common usage for handles. You basically pass a list of method names
\& to be delegated, and Cpanel::Class will install a delegation method for each one.
.Ve
.PP
.Vb 1
\& HASH
.Ve
.PP
.Vb 3
\& Instead of a list of method names, you pass a HASH ref where each key is the method
\& name you want installed locally, and its value is the name of the original method in
\& the class being delegated to.
.Ve
.PP
auto_deref => (1|0)
.PP
.Vb 2
\& This tells the accessor whether to automatically dereference the value returned. Only
\& works for arrayref or hashref.
.Ve
.PP
weak_ref => (1|0)
.PP
.Vb 1
\& This will tell the class to store the value of this attribute as a weakened reference.
.Ve
.PP
trigger => \f(CW$code_ref\fR
.PP
.Vb 4
\& The trigger option is a CODE reference which will be called after the value of the
\& attribute is set. The CODE ref will be passed the instance itself, the updated value
\& and the attribute meta-object (this is for more advanced fiddling and can typically
\& be ignored). You cannot have a trigger on a read-only attribute.
.Ve
.PP
clearer => 'method_name'
.PP
.Vb 1
\& Create a method that will delete/undefine an attribute
.Ve
.PP
required => (1|0)
.PP
.Vb 1
\& This marks the attribute as being required. This means a defined value must be supplied during class construction, and the attribute may never be set to undef with an accessor.
.Ve
.PP
builder => 'method_name'
.PP
.Vb 1
\& The value of this key is the name of the method that will be called to obtain the value used to initialize the attribute. This should be a method in the class associated with the attribute, not a method in the attribute class itself.
.Ve
.PP
has is exported by default.
.SH "Method modifiers"
.IX Header "Method modifiers"
\fIbefore\fR
.IX Subsection "before"
.PP
.Vb 2
\& When writing a "before" hook you can catch the call to an inherited method or a method in the same class,
\& and execute some code before the inherited method is called.
.Ve
.PP
.Vb 1
\& Example:
.Ve
.PP
.Vb 2
\& package Foo;
\& use Cpanel::Class;
.Ve
.PP
.Vb 1
\& sub method { return 4; }
.Ve
.PP
.Vb 3
\& package Bar;
\& use Cpanel::Class;
\& extends 'Foo';
.Ve
.PP
.Vb 4
\& before 'method' => sub {
\& my ($self, @args) = @_;
\& # ... here some stuff to do before Foo::method is called
\& };
.Ve
.PP
\fIafter\fR
.IX Subsection "after"
.PP
.Vb 3
\& When writing an "after" hook you can catch the call to an inherited method or a method in the same class and
\& execute some code after the original method is executed. You receive in your
\& hook the result of the mother's method.
.Ve
.PP
.Vb 1
\& Example:
.Ve
.PP
.Vb 2
\& package Foo;
\& use Cpanel::Class;
.Ve
.PP
.Vb 1
\& sub method { return 4; }
.Ve
.PP
.Vb 3
\& package Bar;
\& use Cpanel::Class;
\& extends 'Foo';
.Ve
.PP
.Vb 1
\& my $flag;
.Ve
.PP
.Vb 4
\& after 'method' => sub {
\& my ($self, @args) = @_;
\& $flag = 1;
\& };
.Ve
.PP
\fIaround\fR
.IX Subsection "around"
.PP
.Vb 2
\& When writing an "around" hook you can catch the call to an inherited method or a method in the same class and
\& actually redefine it on-the-fly.
.Ve
.PP
.Vb 2
\& You get the code reference to the parent's method and its arguments, and can
\& do what you want then.
.Ve
.PP
.Vb 1
\& Example:
.Ve
.PP
.Vb 2
\& package Foo;
\& use Cpanel::Class;
.Ve
.PP
.Vb 1
\& sub method { return 4; }
.Ve
.PP
.Vb 3
\& package Bar;
\& use Cpanel::Class;
\& extends 'Foo';
.Ve
.PP
.Vb 3
\& around 'method' => sub {
\& my $orig = shift;
\& my ($self, @args) = @_;
.Ve
.PP
.Vb 3
\& my $res = $self->$orig(@args);
\& return $res + 3;
\& }
.Ve
.SH "meta"
.IX Header "meta"
meta gives access to the Classes' Meta Object Protocal
.Sh "Meta Object Protocal"
.IX Subsection "Meta Object Protocal"
A meta object protocol is an \s-1API\s0 to an object system.
.PP
To be more specific, it is a set of abstractions of the components of
an object system (typically things like; classes, object, methods,
object attributes, etc.). These abstractions can then be used to both
inspect and manipulate the object system which they describe.
.IP "\->meta\->get_attribute($attr_name)" 4
.IX Item "->meta->get_attribute($attr_name)"
.Vb 1
\& Creates attributes just like the has key word
.Ve
.IP "\->meta\->get_method_map" 4
.IX Item "->meta->get_method_map"
.Vb 1
\& Returns a hashref of all method and code from the class
.Ve
.ie n .IP "\->meta\->add_method($name => $coderef)" 4
.el .IP "\->meta\->add_method($name => \f(CW$coderef\fR)" 4
.IX Item "->meta->add_method($name => $coderef)"
.Vb 1
\& Add a method to the class
.Ve
.IP "\->meta\->get_method_list" 4
.IX Item "->meta->get_method_list"
.Vb 1
\& Returns an array method names from the class
.Ve
.IP "\->meta\->get_method($method_name)" 4
.IX Item "->meta->get_method($method_name)"
.Vb 1
\& Returns coderef of a given method
.Ve
.IP "\->meta\->has_method($method_name)" 4
.IX Item "->meta->has_method($method_name)"
.Vb 1
\& Returns true if the method exists in the class otherwise false
.Ve
.IP "\->meta\->remove_method($method_name)" 4
.IX Item "->meta->remove_method($method_name)"
.Vb 1
\& Remove the method from the class
.Ve
.IP "\->meta\->superclasses" 4
.IX Item "->meta->superclasses"
.Vb 1
\& Returns the @ISA list of superclasses
.Ve
.IP "\->meta\->class_precedence_list" 4
.IX Item "->meta->class_precedence_list"
.Vb 1
\& Returns the list of all Classes in the Class hierarchy. Duplicates are possible.
.Ve
.IP "\->meta\->linearized_isa" 4
.IX Item "->meta->linearized_isa"
.Vb 1
\& Returns the list of all Classes in the Classes hierarchy. It removes duplicates
.Ve
.IP "\->meta\->subclasses" 4
.IX Item "->meta->subclasses"
.Vb 1
\& Returns the list of all Classes that inherit from the current class
.Ve
.IP "\->meta\->name" 4
.IX Item "->meta->name"
.Vb 1
\& Returns the name of the current class
.Ve
.IP "\->meta\->version" 4
.IX Item "->meta->version"
.Vb 1
\& Returns the VERSION of the class
.Ve
.IP "\->meta\->authority" 4
.IX Item "->meta->authority"
.Vb 1
\& Returns the Authority of the class
.Ve
.IP "\->meta\->identifier" 4
.IX Item "->meta->identifier"
.Vb 1
\& Returns a concatenation of name, version and authority seperated by dashes
.Ve
.PP
meta is inherited from Cpanel::Class::Object