File Coverage

blib/lib/PDLx/DetachedObject.pm

Criterion	Covered	Total	%
statement	12	12	100.0
branch			n/a
condition			n/a
subroutine	5	5	100.0
pod	2	2	100.0
total	19	19	100.0

# ABSTRACT: parent class for subclassing PDL 2.X from class frameworks
package PDLx::DetachedObject;

use strict;
use warnings;

our $VERSION = '0.02';

our @ISA = qw( PDL );
use PDL::Lite;

#pod =begin pod_coverage
#pod
#pod =head3 initialize
#pod
#pod =head3 new
#pod
#pod =end pod_coverage
#pod
#pod =cut

sub initialize { return PDL->null }

sub new {
    my $class = shift;
    bless { PDL => PDL->null }, $class;
}

1;

#
# This file is part of PDLx-DetachedObject
#
# This software is Copyright (c) 2016 by Smithsonian Astrophysical Observatory.
#
# This is free software, licensed under:
#
#   The GNU General Public License, Version 3, June 2007
#

=pod

=encoding UTF-8

=head1 NAME

PDLx::DetachedObject - parent class for subclassing PDL 2.X from class frameworks

=head1 VERSION

version 0.02

=head1 SYNOPSIS

=head3 Moo

   # DEPRECATED; use MooX::PDL2 instead
   package MyPDL;

   use Moo;
   use PDL::Lite;

   extends 'PDLx::DetachedObject';

   has PDL => ( is => 'rw' );

=head3 Class::Tiny

    package MyPDL;

    use Class::Tiny qw[ PDL ];

    use parent 'PDLx::DetachedObject';

=head3 Object::Tiny

    package MyPDL;

    use Object::Tiny qw[ PDL ];

    use parent 'PDLx::DetachedObject';

=head3 Class::Accessor

    package MyPDL;

    use parent 'Class::Accessor', 'PDLx::DetachedObject';
    __PACKAGE__->follow_best_practice;
    __PACKAGE__->mk_accessors( 'PDL' );

or with Antlers:

    package MyPDL;
    use Class::Accessor "antlers";
    use parent 'PDLx::DetachedObject';

    has PDL => ( is => 'ro' );

=head1 DESCRIPTION

B provides a minimal shim between L and
object-orientation frameworks.  Directly subclassing B is tricky,
as a B object (a piddle) is a blessed scalar, not a blessed hash.
B provides an L means of subclassing; this
class encapsulates that prescription.

For L based classes, see L, which provides a more
integrated approach.

=head2 Background

Because a B object is a blessed scalar, outside of using
inside-out classes as the subclass, there is no easy means of adding
extra attributes to the object.

To work around this, B will treat any hash blessed into a
subclass of PDL which has an entry with key C whose value is a
real B object as a B object.

So far, here's a L<< B >> version of the class

   package MyPDL;

   use Moo;

   extends 'PDL';

   # don't pass any constructor arguments to PDL->new; it confuses it
   sub FOREIGNBUILDARGS {}

   has PDL => ( is => 'rw' );
   has required_attr => ( is => 'ro', required =>1 );

When B needs to instantiate an object from the subclass,
it doesn't call the subclass's constructor, rather it calls the
B class method, which is expected to return a hash,
blessed into the subclass, containing the C key as well as any
other attributes.

  sub initialize {
    my $class = shift;
    bless { PDL => PDL->null }, $class;
  }

The B method is invoked in a variety of places.  For
instance, it's called in B, which due to B's
inheritance scheme will be called by B's constructor:

  $mypdl = MyPDL->new( required_attr => 2 );

It's also called when B needs to create an object to receive
the results of a B operation on a B object:

  $newpdl = $mypdl + 1;

There's one wrinkle, however.  B I create an object without
any extra attributes (it cannot know which values to give them) so
B is called with a I argument, the class name.
This means that C<$newpdl> will be an I B object,
i.e.  C is uninitialized. This can I confuse
polymorphic code which operates differently when handed a B or
B object.

One way out of this dilemma is to have B create a I piddle
instead of a B object.  B has explicitly indicated it wants to be
treated as a normal piddle in B operations (by subclassing from B) so
this doesn't break that contract.

  $newpdl = $mypdl + 1;

would result in C<$newpdl> being a normal B object, not a B
object.

Subclassing from B effects this
behavior. B provides a wrapper constructor and
an B class method.  The constructor ensures returns a
properly subclassed hash with the C key, keeping B happy.
When B calls the B function it gets a normal B.

=head2 Classes without required constructor parameters

If your class does I require parameters be passed to the constructor,
it is safe to overload the C method to return a fully fledged
instance of your class:

 sub initialize { shift->new() }

=head2 Using with Class Frameworks

The L shows how to use B with various
class frameworks.  The key differentiation between frameworks is
whether or not they will call a superclass's constructor.  B
always calls it, B calls it only if it inherits from
B, and B and B
never will call the superclass' constructor.

=begin pod_coverage

=head3 initialize

=head3 new

=end pod_coverage

=head1 BUGS AND LIMITATIONS

Please report any bugs or feature requests to
C, or through the web interface at
L.

=head1 AUTHOR

Diab Jerius

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007

=cut

__END__