Object::Annotate - mix in logging-to-database to objects (deprecated)
version 0.025
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)" });
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.
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:
use
new
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
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 => { ... } });
These methods are not provided by Object::Annotate, but are installed into classes that use Object::Annotate.
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.
$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 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.
search
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.
$target
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.
"construct_class"
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.
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.
This method returns the class from which the annotator subclass will inherit. It defaults to Class::DBI.
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)
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
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.
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
Ricardo SIGNES <rjbs@cpan.org>
Karen Etheridge <ether@cpan.org>
Ricardo SIGNES <rjbs@codesimply.com>
This software is copyright (c) 2006 by Ricardo SIGNES.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Object::Annotate, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Object::Annotate
CPAN shell
perl -MCPAN -e shell install Object::Annotate
For more information on module installation, please visit the detailed CPAN module installation guide.