| 1 | # You may distribute under the terms of either the GNU General Public License | ||||||||||
| 2 | # or the Artistic License (the same terms as Perl itself) | ||||||||||
| 3 | # | ||||||||||
| 4 | # (C) Paul Evans, 2024 -- leonerd@leonerd.org.uk | ||||||||||
| 5 | |||||||||||
| 6 | package Object::Pad::Operator::Of 0.01; | ||||||||||
| 7 | |||||||||||
| 8 | 2 | ▶ | use v5.14; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 9 | 2 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 10 | |||||||||||
| 11 | 2 | ▶ | use Carp; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 12 | |||||||||||
| 13 | 2 | ▶ | use Object::Pad; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 14 | |||||||||||
| 15 | 2 | require XSLoader; | |||||||||
| 16 | 2 | XSLoader::load( __PACKAGE__, our $VERSION ); | |||||||||
| 17 | |||||||||||
| 18 | =head1 NAME | ||||||||||
| 19 | |||||||||||
| 20 | C<Object::Pad::Operator::Of> - access fields of other instances | ||||||||||
| 21 | |||||||||||
| 22 | =head1 SYNOPSIS | ||||||||||
| 23 | |||||||||||
| 24 | On Perl v5.38 or later: | ||||||||||
| 25 | |||||||||||
| 26 | use v5.38; | ||||||||||
| 27 | use Object::Pad; | ||||||||||
| 28 | use Object::Pad::Operator::Of; | ||||||||||
| 29 | |||||||||||
| 30 | class Bucket { | ||||||||||
| 31 | field $size :param; | ||||||||||
| 32 | |||||||||||
| 33 | use overload '<=>' => method ($other, $) { | ||||||||||
| 34 | return $size <=> $size of $other; | ||||||||||
| 35 | }; | ||||||||||
| 36 | } | ||||||||||
| 37 | |||||||||||
| 38 | =head1 DESCRIPTION | ||||||||||
| 39 | |||||||||||
| 40 | This module provides an infix operator for accessing fields of other instances | ||||||||||
| 41 | of an L<Object::Pad> class, even if those fields do not have accessor methods. | ||||||||||
| 42 | This allows code to be written that can look into the inner workings of other | ||||||||||
| 43 | instances of the same class (or subclasses thereof), in order to implement | ||||||||||
| 44 | particular behaviours, such as sorting comparisons. | ||||||||||
| 45 | |||||||||||
| 46 | Support for custom infix operators was added in the Perl 5.37.x development | ||||||||||
| 47 | cycle and is available from development release v5.37.7 onwards, and therefore | ||||||||||
| 48 | in Perl v5.38 onwards. The documentation of L<XS::Parse::Infix> | ||||||||||
| 49 | describes the situation in more detail. | ||||||||||
| 50 | |||||||||||
| 51 | =cut | ||||||||||
| 52 | |||||||||||
| 53 | sub import | ||||||||||
| 54 | 1 | ▶ | { | ||||||||
|
Subroutine
import: called CC=1 SCAR=0.0
| |||||||||||
| 55 | 1 | my $pkg = shift; | |||||||||
| 56 | 1 | my $caller = caller; | |||||||||
| 57 | |||||||||||
| 58 | 1 | $pkg->import_into( $caller, @_ ); | |||||||||
| 59 | } | ||||||||||
| 60 | |||||||||||
| 61 | sub unimport | ||||||||||
| 62 | 0 | ▶ | { | ||||||||
|
Subroutine
unimport: not called CC=1 SCAR=6.9
| |||||||||||
| 63 | 0 | my $pkg = shift; | |||||||||
| 64 | 0 | my $caller = caller; | |||||||||
| 65 | |||||||||||
| 66 | 0 | $pkg->unimport_into( $caller, @_ ); | |||||||||
| 67 | } | ||||||||||
| 68 | |||||||||||
| 69 | 1 | ▶ | sub import_into { shift->apply( 1, @_ ) } | ||||||||
|
Subroutine
import_into: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||
| 70 | 0 | ▶ | sub unimport_into { shift->apply( 0, @_ ) } | ||||||||
|
Subroutine
unimport_into: not called CC=1 SCAR=6.9
Pod
undocumented
| |||||||||||
| 71 | |||||||||||
| 72 | sub apply | ||||||||||
| 73 | 1 | ▶ | { | ||||||||
|
Subroutine
apply: called CC=3 SCAR=11.3
Pod
undocumented
| |||||||||||
| 74 | 1 | my $pkg = shift; | |||||||||
| 75 | 1 | my ( $on, $caller, @syms ) = @_; | |||||||||
| 76 | |||||||||||
| 77 | 1 | ▶ | @syms or @syms = qw( of ); | ||||||||
|
Branch: 1 branch
| |||||||||||
| 78 | |||||||||||
| 79 | 1 | $pkg->XS::Parse::Infix::apply_infix( $on, \@syms, qw( of ) ); | |||||||||
| 80 | |||||||||||
| 81 | 1 | ▶ | croak "Unrecognised import symbols @syms" if @syms; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 82 | } | ||||||||||
| 83 | |||||||||||
| 84 | =head1 OPERATORS | ||||||||||
| 85 | |||||||||||
| 86 | =head2 of | ||||||||||
| 87 | |||||||||||
| 88 | my $value = $field of $other; | ||||||||||
| 89 | |||||||||||
| 90 | Yields the current value of the given field of a different instance than | ||||||||||
| 91 | C<$self>. The field variable, on the left of the operator, must be lexically | ||||||||||
| 92 | visible in the current scope. The expression on the right must yield an | ||||||||||
| 93 | instance of the class that defines the field (or some subclass of it); if not | ||||||||||
| 94 | an exception is thrown. | ||||||||||
| 95 | |||||||||||
| 96 | =cut | ||||||||||
| 97 | |||||||||||
| 98 | =head1 TODO | ||||||||||
| 99 | |||||||||||
| 100 | =over 4 | ||||||||||
| 101 | |||||||||||
| 102 | =item * | ||||||||||
| 103 | |||||||||||
| 104 | Try to find a better operator name, which puts the object instance on the left | ||||||||||
| 105 | and the field on the right. | ||||||||||
| 106 | |||||||||||
| 107 | =item * | ||||||||||
| 108 | |||||||||||
| 109 | Look into whether regular C<sub>s can also use C<of> expressions. Currently | ||||||||||
| 110 | no fields are visible due to the way that C<Object::Pad> implements methods. | ||||||||||
| 111 | |||||||||||
| 112 | =item * | ||||||||||
| 113 | |||||||||||
| 114 | Look into whether it might be possible to use C<of> expressions as lvalues, | ||||||||||
| 115 | for mutation or assignment. | ||||||||||
| 116 | |||||||||||
| 117 | =back | ||||||||||
| 118 | |||||||||||
| 119 | =cut | ||||||||||
| 120 | |||||||||||
| 121 | =head1 AUTHOR | ||||||||||
| 122 | |||||||||||
| 123 | Paul Evans <leonerd@leonerd.org.uk> | ||||||||||
| 124 | |||||||||||
| 125 | =cut | ||||||||||
| 126 | |||||||||||
| 127 | 2 | 0x55AA; | |||||||||