Linux Certif

Toute la documentation sur la certification Linux LPI

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 no-op.

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-2007 Marvin Humphrey

LICENSE, DISCLAIMER, BUGS, etc.

See KinoSearch version 0.163.