1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
=head1 NAME
PDL::Objects -- Object-orientation, what it is and how to exploit it
=head1 DESCRIPTION
This describes how to subclass L<PDL> objects for fun and profit.
=head2 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.
=head2 Perl values into underlying C values
C<typemap>s turns Perl values into the C entities needed by the C
code. PDL's one uses C<SvPDLV> to extract a C<pdl*> from a Perl
value. That knows how to deal with:
=over
=item *
"simple" blessed scalars that have a C pointer
=item *
blessed hash-refs that have a C<PDL> member that's a C pointer as above
=item *
blessed hash-refs that have a C<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. As of 2.094, the original hash-ref
will be passed as the first argument. This means you can give a
method as shown below, rather than needing to make a closure each
time.
Example from F<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=>\&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;
}
=item *
"simple" Perl data, either a scalar or an array-reference
=item *
blessed hash-refs that are a L<Math::Complex> (or subclass) object
- special case of the "scalar" above
=back
The rest of this document deals with the second case above.
=head2 Inheritance
To enable subclassing, make a package and bless a hash-ref into it
with a C<PDL> member. Make that package inherit from C<PDL>, and
redefine the method C<initialize>.
package FOO;
our ISA = qw(PDL::Hash);
sub initialize {
my $class = shift;
my $self = $class->SUPER::initialize(@_);
$self->{creation_time} = time(); # necessary extension :-)
$self;
}
All PDL constructors will call initialize() to make sure that your
extensions are added by I<all> PDL constructors automatically.
Do remember that if you subclass a class that is subclassed from an ndarray,
you need to call C<SUPER::initialize>. Make sure it is callable as
an instance method, e.g. by copying data from C<$class> if C<ref
$class> is true.
=head2 Examples
You can find some simple examples of PDL subclassing in the PDL distribution
test-case files. Look in F<t/subclass.t>.
=head2 Output Auto-Creation and Subclassed Objects
For PDL Functions where the output is created and returned, PDL will
call the subclassed object's C<initialize> method on either instance
or class to create the
output object. (See L<PDL::Indexing|PDL::Indexing/"Output auto-creation and PP-function calling conventions">
for a discussion on Output Auto-Creation.) This behavior is summarized as follows:
PDL will call C<initialize> on the first input argument if it is
an object, else on C<PDL> to create the output object.
In the spirit of the Perl philosophy of making I<Easy Things Easy>,
this behavior enables PDL-subclassed objects to be written without having to
overload the many simple PDL functions in this category.
=head1 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.
=cut
|
