File Coverage

blib/lib/Class/Adapter.pm

Criterion	Covered	Total	%
statement	15	16	93.7
branch	4	6	66.6
condition			n/a
subroutine	6	6	100.0
pod	1	1	100.0
total	26	29	89.6

package Class::Adapter; # git description: 1a66420
# ABSTRACT: Perl implementation of the "Adapter" Design Pattern

#pod =pod
#pod
#pod =head1 DESCRIPTION
#pod
#pod The C class is intended as an abstract base class for
#pod creating any sort of class or object that follows the I pattern.
#pod
#pod =head2 What is an Adapter?
#pod
#pod The term I refers to a I<"Design Pattern"> of the same name,
#pod from the famous I<"Gang of Four"> book I<"Design Patterns">. Although
#pod their original implementation was designed for Java and similar
#pod single-inheritance strictly-typed language, the situation for which it
#pod applies is still valid.
#pod
#pod An I in this Perl sense of the term is when a class is created
#pod to achieve by composition (objects containing other object) something that
#pod can't be achieved by inheritance (sub-classing).
#pod
#pod This is similar to the I pattern, but is intended to be
#pod applied on a class-by-class basis, as opposed to being able to be applied
#pod one object at a time, as is the case with the I pattern.
#pod
#pod The C object holds a parent object that it "wraps",
#pod and when a method is called on the C, it manually
#pod calls the same (or different) method with the same (or different)
#pod parameters on the parent object contained within it.
#pod
#pod Instead of these custom methods being hooked in on an object-by-object
#pod basis, they are defined at the class level.
#pod
#pod Basically, a C is one of your fall-back positions
#pod when Perl's inheritance model fails you, or is no longer good enough,
#pod and you need to do something twisty in order to make several APIs play
#pod nicely with each other.
#pod
#pod =head2 What can I do with the actual Class::Adapter class
#pod
#pod Well... nothing really. It exist to provide some extremely low level
#pod fundamental methods, and to provide a common base for inheritance of
#pod Adapter classes.
#pod
#pod The base C class doesn't even implement a way to push
#pod method calls through to the underlying object, since the way in which
#pod B happens is the bit that changes from case to case.
#pod
#pod To actually DO something, you probably want to go take a look at
#pod L, which makes the creation of I
#pod classes relatively quick and easy.
#pod
#pod =head1 METHODS
#pod
#pod The C class itself supplies only the two most common
#pod methods, a default constructor and a private method to access the
#pod underlying object.
#pod
#pod =cut

use 5.005;
use strict;
use Carp              ();
use Scalar::Util 1.10 ();

our $VERSION = '1.09';





#####################################################################
# Constructor

#pod =pod
#pod
#pod =head2 new $object
#pod
#pod The default C constructor takes a single object as argument and
#pod creates a new object which holds the passed object.
#pod
#pod Returns a new C object, or C if you do not pass
#pod in an object.
#pod
#pod =cut

sub new {
	my $class  = ref $_[0] ? ref shift : shift;
	my $object = Scalar::Util::blessed($_[0]) ? shift : return undef;
	return bless { OBJECT => $object }, $class;
}





#####################################################################
# Private Methods

#pod =pod
#pod
#pod =head2 _OBJECT_
#pod
#pod The C<_OBJECT_> method is provided primarily as a convenience, and a tool
#pod for people implementing sub-classes, and allows the C
#pod interface to provide a guaranteed correct way of getting to the underlying
#pod object, should you need to do so.
#pod
#pod =cut

sub _OBJECT_ {
	return $_[0]->{OBJECT} if ref $_[0];
	Carp::croak('Class::Adapter::_OBJECT_ called as a static method');
}

1;

__END__