Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Object::Annotate
mix in logging-to-database to objects

Object::Annotate - mix in logging-to-database to objects


NAME

Object::Annotate - mix in logging-to-database to objects


VERSION


 $Id: /my/icg/annotate/trunk/lib/Object/Annotate.pm 22351 2006-05-19T03:22:24.551612Z rjbs  $

version 0.020


SYNOPSIS


  package Your::Class;

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

  ...

  my $object = Your::Class->new( ... );

  $object->annotate({ event => "created", comment => "(as example)" });


WARNING

The interface described here is still in real flux. Feedback is welcome! If, however, you rely on this interface for production code, and then upgrade this module blindly, you are likely to see things break.

I will remove this warning when the interface is less likely to change.


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 the Sub::Exporter manpage.

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.

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
Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy