1Devel::EnforceEncapsulaUtsieorn(C3o)ntributed Perl DocumDeenvtealt:i:oEnnforceEncapsulation(3)
2
3
4

NAME

6       Devel::EnforceEncapsulation - Find access violations to blessed objects
7

SYNOPSIS

9         package BankAccount;
10         sub new {
11            my $pkg = shift;
12            return bless {}, $pkg;
13         }
14         sub balance {
15            my $self = shift;
16            return $self->{balance};
17         }
18         # ... etc. ...
19
20         package main;
21         Devel::EnforceEncapsulation->apply_to('BankAccount');
22         my $acct = BankAccount->new();
23         print $acct->balance(),"\n";  # ok
24         print $acct->{balance},"\n";  # dies
25

LICENSE

27       Copyright 2014 Chris Dolan, <cpan@chrisdolan.net> Copyright 2006 Clotho
28       Advanced Media, Inc., <cpan@clotho.com>
29
30       This library is free software; you can redistribute it and/or modify it
31       under the same terms as Perl itself.
32

DESCRIPTION

34       Encapsulation is the practice of creating subroutines to access the
35       properties of a class instead of accessing those properties directly.
36       The advantage of good encapsulation is that the author is permitted to
37       change the internal implementation of a class without breaking its
38       usage.
39
40       Object-oriented programming in Perl is most commonly implemented via
41       blessed hashes.  This practice makes it easy for users of a class to
42       violate encapsulation by simply accessing the hash values directly.
43       Although less common, the same applies to classes implemented via
44       blessed arrays, scalars, filehandles, etc.
45
46       This module is a hack to block those direct accesses.  If you try to
47       access a hash value of an object from it's own class, or a superclass
48       or subclass, all goes well.  If you try to access a hash value from any
49       other package, an exception is thrown.  The same applies to the scalar
50       value of a blessed scalar, entry in a blessed array, etc.
51
52       To be clear: this class is NOT intended for strict enforcement of
53       encapsulation.  If you want bullet-proof encapsulation, use inside-out
54       objects or the like.  Instead, this module is intended to be a
55       development or debugging aid in catching places where direct access is
56       used against classes implemented as blessed hashes.
57
58       To repeat: the encapsulation enforced here is a hack and is easily
59       circumvented.  Please use this module for good (finding bugs), not evil
60       (making life harder for downstream developers).
61

METHODS

63       $pkg->apply_to($other_pkg);
64       $pkg->apply_to($other_pkg, {policy => 'carp'});
65           Add strict encapsulation to an existing $other_pkg.  The
66           encapsulation changes only apply to instances created after the
67           call.
68
69           The optional "policy" argument allows you to change the response to
70           an illegal access.  By default the policy is "croak", which invokes
71           "Carp::croak()".  The alternative is "carp" which invokes
72           "Carp::carp()" instead.
73
74       $pkg->remove_from($other_pkg);
75           Remove any encapsulation previously set by "apply_to()".  This does
76           not affect instances created before this call.
77

SEE ALSO

79   Class::Privacy
80       Class::Privacy is a very similar implementation that is, in general,
81       stricter than this module.  The key differences:
82
83       •   D::E applies externally post-facto; C::P from inside the code.
84
85       •   D::E allows access from sub/superclasses; C::P does not
86           (deliberately!).
87
88       •   D::E supports all dereferencers from overload.pm; C::P supports
89           "%", "@", "$", and "&".
90
91       •   D::E allows access from anything in the same package; C::P allows
92           access only from matching package AND file.
93
94   Inside-out classes
95       Class::InsideOut, Object::InsideOut and Class::Std are all
96       implementations of "inside-out" objects, which offer a stricter
97       encapsulation style at the expense of a less familiar coding style.
98

DIAGNOSTICS

100       "Illegal attempt to access %s internals from %s"
101           (Fatal) You tried to access a hash property directly instead of via
102           an accessor method.  The %s values are the object and caller
103           packages respectively.
104

QUALITY

106       We care about code quality.  This distribution complies with the
107       following quality metrics:
108
109       •   Perl::Critic v0.20 passes
110
111       •   Devel::Cover test coverage at 100%
112
113       •   Pod::Coverage at 100%
114
115       •   Test::Spelling passes
116
117       •   Test::Portability::Files passes
118
119       •   Test::Kwalitee passes
120

CAVEATS

122       The regression tests do not cover blessed code or glob references.
123
124       Any other issues:
125       <http://rt.cpan.org/Dist/Display.html?Queue=Devel-EnforceEncapsulation>
126

AUTHOR

128       Clotho Advanced Media Inc., cpan@clotho.com
129
130       Maintainer: Chris Dolan
131

CREDITS

133       This idea, and the original source code, came from Adrian Howard via
134       Curtis "Ovid" Poe on
135       <http://www.perlmonks.org/?node_id=576707|perlmonks.org>.  Adrian has
136       authorized me to release a variant of his code under the Perl license.
137
138       Joshua ben Jore provided crucial improvements that simplified yet
139       generalized the implementation.  This module would not be half as
140       useful without his contributions.
141       <http://use.perl.org/comments.pl?sid=33253&cid=50863>
142
143       Ricardo Signes contributed the "{policy =" 'carp'}> feature (with
144       tests!).  <http://rt.cpan.org/Ticket/Display.html?id=22024>
145
146
147
148perl v5.36.0                      2022-07-22    Devel::EnforceEncapsulation(3)
Impressum