NAME

PDL::Objects -- Object-orientation, what it is and how to exploit it

DESCRIPTION

This describes how to subclass PDL objects for fun and profit.

Why subclass?

There are basically two reasons for subclassing ndarrays. The first is simply that you want to be able to use your own routines like

  $ndarray->something

but don't want to mess up the PDL namespace (a worthy goal, indeed!). The other is that you wish to provide special handling of some functions or more information about the data the ndarray contains. The first case you can do with

  package BAR;
  our @ISA=qw/PDL/;
  sub foo {my($this) = @_; fiddle;}

  package main;
  $x = BAR->pdl(5);
  $x->foo;

However, because a PDL object is an opaque reference to a C struct, it is not instantly possible to extend the PDL class by e.g. extra data via subclassing.

Perl values into underlying C values

typemaps turns Perl values into the C entities needed by the C code. PDL's one uses SvPDLV to extract a pdl* from a Perl value. That knows how to deal with:

• "simple" blessed scalars that have a C pointer

• blessed hash-refs that have a PDL member that's a C pointer as above

• blessed hash-refs that have a PDL member that's a Perl code-ref. It will be called, and is expected to return an ndarray that conforms to one of cases 1-2 or 4-5 above. Example from t/subclass.t:

    package PDL::Derived2;
    # This is a array of ones of dim 'Coeff'
    # All that is stored initially is "Coeff", the
    # PDL array is only realised when a boring PDL
    # function is called on it. One can imagine methods
    # in PDL::Derived2 doing manipulation on the Coeffs
    # rather than actualizing the data.
    our @ISA = qw/PDL/;
    sub new {
      my $class = shift;
      bless {
        Coeff=>shift,
        PDL=>sub { return $_[0]->cache },
        SomethingElse=>42,
      }, $class;
    }
    # Actualize the value (demonstrating cacheing)
    # One can imagine expiring the cache if say, Coeffs change
    sub cache {
      my $self = shift;
      return $self->{Cache} if exists $self->{Cache};
      $self->{Cache} = PDL->ones(@$self{qw(Coeff Coeff)})+2;
    }

• "simple" Perl data, either a scalar or an array-reference

• blessed hash-refs that are a Math::Complex (or subclass) object - special case of the "scalar" above

The rest of this document deals with the second case above.

Inheritance

To enable subclassing, make a package and bless a hash-ref into it with a PDL member. Make that package inherit from PDL, and redefine the method initialize.

  package FOO;
  our ISA = qw(PDL);
  sub initialize {
    my $class = shift;
    my $self = {
      creation_time => time(),  # necessary extension :-)
      PDL => $class->SUPER::initialize, # used to store PDL object
    };
    bless $self, ref $class || $class;
  }

All PDL constructors will call initialize() to make sure that your extensions are added by all PDL constructors automatically.

Do remember that if you subclass a class that is subclassed from an ndarray, you need to call SUPER::initialize.

Examples

You can find some simple examples of PDL subclassing in the PDL distribution test-case files. Look in t/subclass.t.

Output Auto-Creation and Subclassed Objects

For PDL Functions where the output is created and returned, PDL will either call the subclassed object's initialize or copy method to create the output object. (See PDL::Indexing for a discussion on Output Auto-Creation.) This behavior is summarized as follows:

• For simple functions, defined as having a signature of

   func( a(), [o]b() )

  PDL will call $a->copy to create the output object.

  In the spirit of the Perl philosophy of making Easy Things Easy, this behavior enables PDL-subclassed objects to be written without having to overload the many simple PDL functions in this category.

  The file t/subclass.t in the PDL Distribution tests for this behavior. See that file for an example.

• For other functions, PDL will call $class->initialize to create the output object. Where $class is the class name of the first argument supplied to the function.

  For these more complex cases, it is difficult to second-guess the subclassed object's designer to know if a copy or a initialize is appropriate. So for these cases, $class->initialize is called by default. If this is not appropriate for you, overload the function in your subclass and do whatever is appropriate is the overloaded function's code.

AUTHOR

Copyright (C) Karl Glazebrook (kgb@aaoepp.aao.gov.au), Tuomas J. Lukka, (lukka@husc.harvard.edu) and Christian Soeller (c.soeller@auckland.ac.nz) 2000. All rights reserved. There is no warranty. You are allowed to copy this on the same terms as Perl itself.