NAME

Class::Decorator - Attach additional responsibilites to an object. A generic wrapper.

SYNOPSIS

  use Class::Decorator;
  my $object = Foo::Bar->new(); # the object to be decorated
  my $logger = Class::Decorator->new(
    obj  => $object,
    pre  => sub{print "before method\n"},
    post => sub{print "after method\n"}
  );
  $logger->some_method_call(@args);

DESCRIPTION

Decorator objects allow additional functionality to be dynamically added to objects. In this implementation, the user can supply two subroutine references (pre and post) to be performed before (pre) and after (post) any method call to an object (obj).

Both 'pre' and 'post' arguments to the contructor are optional. The 'obj' argument is mandated.

The pre and post methods receive the arguments that are supplied to the decorated method, and therefore Class::Decorator can be used effectively in debugging or logging applications. Return values from pre and post are ignored.

Decorator objects can themselves be decorated. Therefore, it is possible to have an object that performs work, which is decorated by a logging decorator, which in turn is decorated by a debugging decorator. Decorated objects can use wantarray(), but should not use caller() [yet].

To decorate a single method, or several methods with differing decorations, use the alternative 'methods' constructor:

  use Class::Decorator;
  my $object = Foo::Bar->new(); # the object to be decorated
  my $decorator = Class::Decorator->new(
    obj  => $object,
    methods => {
        foobar => {
            pre  => sub{print "before foobar()\n"},
            post => sub{print "after foobar()\n"}
        }
    }
  );
  $decorator->foobar(@args); # decorated
  $decorator->barbaz(@args); # not decorated

$Class::Decorator::METHOD

$Class::Decorator::METHOD is set to the name of the current method being called. So, a simple debugging script might decorate an object like this:

  my $debugger = Class::Decorator->new(
    obj  => $object,
    pre  => sub{print "entering $Class::Decorator::METHOD\n"},
    post => sub{print "leaving $Class::Decorator::METHOD\n"}
  );

Arguments are supplied to the pre- and post- methods, but return values are ignored. Note that the first argument in the list of arguments supplied to pre- and post- is the decorated object (i.e. the second argument $_[1] is the start of the true list of arguments).

NOTES AND WARNINGS

The DESTROY method is currently disabled. This is only important to those users who have implemented DESTROY for cleaning up circular references or for some other reason. Unfortunately, it is not possible to say guess the wrapped object needs to be destroyed when DESTROY is called on the decorator - the decorator may be eligible for garbage collection when the decorated object is not.

The caller() function should not be relied upon in the decorated object - it will return information about the decorator.

Member variables of wrapped objects cannot be accessed directly through the decorator. For example, if it is usually possible to access a member variable 'foo' through the undecorated object like so:

  $object->{foo};

it will not be possible to acces this variable through the decorated object by using $decorator->{foo}. This follows standard object-oriented conventions that all member variables should only be accessible through accessors [i.e. by using $object->get_foo() ]. In object-oriented parlance, this is known as encapsulation.

SEE ALSO

Class::Null - an alternative to wrapping an object is providing an object that performs nothing (i.e. removing functionality when it isn't needed, rather than adding it when required).

Class::Hook - decorates the method for an entire class, rather than for a single object.

Hook::PrePostCall - preprocesses the arguments to a subroutine, and filters the subroutine's results.

Hook::WrapSub - similar to Class::Hook.

Hook::LexWrap - again, decorates a method for an entire class, rather than for a single object, but magically allows wrapped method to see correct return values from caller() funtion.

The Decorator Pattern is fully explained in Design Patterns, Elements of Reusable Object-Oriented Software (Gamma et al., 1994).

AUTHOR

Nigel Wetters, <nwetters@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2002 by Nigel Wetters, <nwetters@cpan.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Class::Decorator

perl -MCPAN -e shell
install Class::Decorator