Diab Jerius
and 1 contributors

NAME

PDLx::DetachedObject - parent class for subclassing PDL from class frameworks

SYNTAX

Moo

   package MyPDL;

   use Moo;
   use PDL::Lite;

   extends 'PDLx::DetachedObject';

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

Class::Tiny

    package MyPDL;

    use Class::Tiny qw[ PDL ];

    use parent 'PDLx::DetachedObject';

Object::Tiny

    package MyPDL;

    use Object::Tiny qw[ PDL ];

    use parent 'PDLx::DetachedObject';

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' );

DESCRIPTION

PDL has a non-standard way of handling subclasses. Because a PDL 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, PDL will treat any hash blessed into a subclass of PDL which has an entry with key PDL whose value is a real PDL object as a PDL object.

So far, here's a Moo 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 PDL needs to instantiate an object from the subclass, it doesn't call the subclass's constructor, rather it calls the initialize class method, which is expected to return a hash, blessed into the subclass, containing the PDL key as well as any other attributes.

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

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

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

It's also called when PDL needs to create an object to recieve the results of a PDL operation on a MyPDL object:

  $newpdl = $mypdl + 1;

There's one wrinkle, however. PDL must create an object without any extra attributes (it cannot know which values to give them) so initialize() is called with a single argument, the class name. This means that $newpdl will be an incomplete MyPDL object, i.e. required_attr is uninitiailzed. This can really confuse polymorphic code which operates differently when handed a PDL or MyPDL object.

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

  $newpdl = $mypdl + 1;

would result in $newpdl being a normal PDL object, not a MyPDL object.

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

Using with Class Frameworks

The "SYNOPSIS" shows how to use PDLx::DetachedObject with various class frameworks. The key differentiation between frameworks is whether or not they will call a superclass's constructor. Moo always calls it, Class::Tiny calls it only if it inherits from Class::Tiny::Object, and Object::Tiny and Class::Accessor never will call the superclass' constructor.

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-pdlx-mask@rt.cpan.org, or through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=PDLx-DetachedObject.

VERSION

Version 0.01

LICENSE AND COPYRIGHT

Copyright (c) 2016 The Smithsonian Astrophysical Observatory

PDLx::DetachedObject is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

Diab Jerius <djerius@cpan.org>