KinoSearch::Util::Class(3pm)
NAME
KinoSearch::Util::Class - class building utility
PRIVATE CLASS
This is a private class and the interface may change radically and
without warning. Do not use it on its own.
SYNOPSIS
package KinoSearch::SomePackage::SomeClass;
use base qw( KinoSearch::Util::Class );
BEGIN {
__PACKAGE__->init_instance_vars(
# constructor params / members
foo => undef,
bar => {},
# members
baz => {},
);
}
DESCRIPTION
KinoSearch::Util::Class is a class-building utility a la
Class::Accessor, Class::Meta, etc. It provides four main services:
1. A mechanism for inheriting instance variable declarations.
2. A constructor with basic argument checking.
3. Manufacturing of get_xxxx and set_xxxx methods.
4. Convenience methods which help in defining abstract classes.
VARIABLES
- %instance_vars
- The %instance_vars hash, which is always a package global, serves as a
template for the creation of a hash-based object. It is built up from
all the %instance_vars hashes in the module's parent classes, using
init_instance_vars(). - Key-value pairs in an %instance_vars hash are labeled as "constructor
params" and/or "members". Items which are labeled as constructor
params can be used as arguments to new().
BEGIN {
__PACKAGE__->init_instance_vars(
# constructor params / members
foo => undef,
bar => 10,
# members
baz => '', - );
- }
- # ok: specifies foo, uses default for bar, derives baz
my $object = __PACKAGE__->new( foo => $foo ); - # not ok: baz isn't a constructor param
my $object = __PACKAGE__->new( baz => $baz ); - # ok if a parent class defines boffo as a constructor param
my $object = __PACKAGE__->new(
foo => $foo,
boffo => $boffo, - );
- %instance_vars may only contain scalar values, as the defaults are
merged into the object using a shallow copy. - init_instance_vars() must be called from within a BEGIN block and before any "use" directives load a child class -- if children are born before their parents, inheritance gets screwed up.
METHODS
- new
- A generic constructor with basic argument checking. new() expects
hash-style labeled parameters; the label names must be present in the
%instance_vars hash, or it will croak(). - After verifying the labeled parameters, new() merges %instance_vars and @_ into a new object. It then calls $self->init_instance() before returning the blessed reference.
- init_instance
$self->init_instance(); - Perform customized initialization routine. By default, this is a noop.
- init_instance_vars
BEGIN {
__PACKAGE__->init_instance_vars(
a_safe_variable_name_that_wont_clash => 1,
freep_warble => undef, - );
- }
- Package method only. Creates a package global %instance_vars hash in
the passed in package which consists of the passed in arguments plus
all the key-value pairs in the parent class's %instance_vars hash. - ready_get_set ready_get ready_set # create get_foo(), set_foo(), get_bar(), set_bar() in __PACKAGE__ BEGIN { __PACKAGE__->ready_get_set(qw( foo bar )) };
- Mass manufacture getters and setters. The setters do not return a
meaningful value. - abstract_death unimplemented_death todo_death
sub an_abstract_method { shift->abstract_death }
sub an_unimplemented_method { shift->unimplemented_death }
sub maybe_someday { shift->todo_death } - These are just different ways to die(), and are of little interest until your particular application comes face to face with one of them.
- abstract_death indicates that a method must be defined in a subclass.
- unimplemented_death indicates a feature/function that will probably not
be implemented. Typically, this would appear for a sub that a
developer intimately familiar with Lucene would expect to find. - todo_death indicates a feature that might get implemented someday.
COPYRIGHT
Copyright 2005-2009 Marvin Humphrey
LICENSE, DISCLAIMER, BUGS, etc.
- See KinoSearch version 0.165.