Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

Object::Annotate - mix in logging-to-database to objects (deprecated)

VERSION

version 0.025

SYNOPSIS

Achtung! This library was an experiment. It failed. Consider using Mixin::ExtraFields instead.

package Your::Class;
use Object::Annotate annotate => { dsn => '...', table => 'notes' };

...

my $object = Your::Class->new( ... );
$object->annotate({ event => "created", comment => "(as example)" });

DESCRIPTION

Object::Annotate is a mixin that provides any class with method for storing and retrieving notes about its objects. It can also produce objects which exist only to store annotations about abstract (uninstantiated) objects, procedures, or concepts.

USAGE

To mix Object::Annotate into a class, just use it. To create a classless annotator object, use Object::Annotate's new method. Both of these usages accept the same arguments:

db        - options for the database in which notes are stored; a hashref:

  dsn       - the DSN to pass to Class::DBI to create a connection
  user      - the username to use in connecting to the database
  pass      - the password to use in connecting to the database
  table     - the table in which annotations are stored
  sequence  - if given, the Class::DBI table's primary key values comes from
              this sequence; see L<Class::DBI> for more information

columns   - columns for the annotation table
obj_class - the class name to use for annotations for this class
            (defaults to Class->moniker, see UNIVERSAL::moniker)
id_attr   - the object attribute to use for "id"; called as a method
            if it's a scalar ref, it's de-ref'd and used as a constant string

new

You can use the new method to create a singularity -- an object that can annotate as if it was of a class that used Object::Annotate, but is of its own unique class.

my $notepad = Object::Annotate->new({ db => { ... } });

METHODS

These methods are not provided by Object::Annotate, but are installed into classes that use Object::Annotate.

annotations_class

my $annotations_class = Your::Class->annotations_class;

This method returns the name of the automatically constructed class that handles annotations for the class or object on which it is installed.

annotate

$object->annotate({
  event => 'update',
  attr  => 'priority',
  old_val => 1,
  new_val => 3,
});

This method creates an annotation for the object on which it is called.

search_annotations

# search all annotations for this class
my @notes = Class->search_annotations({ event => 'explosion' });

# searches only annotations for this object
my @notes = $object->search_annotations({ event => 'explosion' });

This method searches through the annotations for a class or an object, using the Class::DBI search method.

INTERNALS

setup_class

Object::Annotate->setup_class('annotator', \%arg, \%col);

This method does the heavy lifting needed to turn the class named by $target into one that does annotation. It is a group generator as described in Sub::Exporter.

class_for

my $class = Object::Annotate->class_for(\%arg);

This method returns the class to use for the described database and table, constructing it (see "construct_class") if needed.

Valid arguments are (for all, see the "USAGE" section): dsn, table, db_user, db_pass, sequence

See the "USAGE" section, above, for information on these arguments, which typically are passed along by the import routine.

default_dsn

default_table

default_user

default_pass

These methods return the default database settings to use if none is specified when importing Object::Annotate. The built-in behavior is to return the OBJ_ANNOTATE_DSN, OBJ_ANNOTATE_TABLE, etc. environment variables.

default_base_class

This method returns the class from which the annotator subclass will inherit. It defaults to Class::DBI.

construct_cdbi_class

my $new_class = Object::Annotate->construct_cdbi_class(\%arg);

This method sets up a new Class::DBI subclass that will store in the database described by the arguments.

Valid arguments are:

dsn     - the dsn for the database in which to store
user    - the database user as whom to connect
pass    - the database password
table   - the table in which to store annotations
columns - the extra columns for the table
base_class - class from which the new class inherits (default: Class::DBI)

build_annotator

my $code = Object::Annotate->build_annotator(\%arg);

This builds the routine that will be installed as "annotate" in the importing class. It returns a coderef.

It takes the following arguments:

obj_class - the class name to use for this class's log entries
id_attr   - the method to use to get object ids; if a scalar ref,
            the dereferenced string is used as a constant
set_time  - if true, the created value will be created as the current time

build_searcher

my $code = Object::Annotate->build_searcher(\%arg);

This builds the routine that will be installed as "search_annotations" in the importing class. It returns a coderef.