---
name: "KinoSearch::Util::Class"
section: "3pm"
platform: "linux"
package: "libkinosearch-perl"
version: "0.165-2"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/KinoSearch::Util::Class"
---

# KinoSearch::Util::Class(3pm)

class building utility

## 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-2009 Marvin Humphrey

## LICENSE, DISCLAIMER, BUGS, etc.

See KinoSearch version 0.165.