/ 
KinoSearch-0.09_01
River stage two • 9 direct dependents • 10 total dependents
/ KinoSearch::Util::Class

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 );

our %instance_vars = __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 three main services:

  1. A mechanism for inheriting instance variable declarations.

  2. A constructor with basic argument checking.

  3. 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().

our %instance_vars = __PACKAGE__->init_instance_vars(
    # constructor params / members
    foo => undef,
    bar => {},
    # 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 can contain hashrefs, array-refs, and full-fledged Perl objects. However, it cannot contain C-struct based objects, since Clone's clone() method doesn't know how to duplicate those safely.

# ok, Lock is a Perl object
our %instance_vars = __PACKAGE__->init_instance_vars(
    # members
    term => KinoSearch::Store::Lock->new,
);

# BAD! causes memory errors, since TermInfo is a C-struct object
our %instance_vars = __PACKAGE__->init_instance_vars(
    # members
    tinfo => KinoSearch::Index::TermInfo->new,
);

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() creates a deep clone of %instance_vars, and merges in the labeled arguments. 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

our %instance_vars = __PACKAGE__->init_instance_vars(
    a_safe_variable_name_that_wont_clash => 1,
    freep_warble                         => undef,
);

Package method only. Return a flat list containing the arguments, plus all the key-value pairs in the parent class's %instance_vars hash.

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

LICENSE, DISCLAIMER, BUGS, etc.

See KinoSearch version 0.09.