1Devel::EnforceEncapsulaUtsieorn(C3o)ntributed Perl DocumDeenvtealt:i:oEnnforceEncapsulation(3)
2
6 Devel::EnforceEncapsulation - Find access violations to blessed objects
7
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 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
27 Copyright 2014 Chris Dolan, <cpan@chrisdolan.net> Copyright 2006 Clotho
28 Advanced Media, Inc., <cpan@clotho.com>
29 This library is free software; you can redistribute it and/or modify it
31 under the same terms as Perl itself.
32
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 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 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 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 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
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 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 $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
79 Class::Privacy
80 Class::Privacy is a very similar implementation that is, in general,
81 stricter than this module. The key differences:
82 • D::E applies externally post-facto; C::P from inside the code.
84 • D::E allows access from sub/superclasses; C::P does not
86 (deliberately!).
87 • D::E supports all dereferencers from overload.pm; C::P supports
89 "%", "@", "$", and "&".
90 • D::E allows access from anything in the same package; C::P allows
92 access only from matching package AND file.
93 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
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
106 We care about code quality. This distribution complies with the
107 following quality metrics:
108 • Perl::Critic v0.20 passes
110 • Devel::Cover test coverage at 100%
112 • Pod::Coverage at 100%
114 • Test::Spelling passes
116 • Test::Portability::Files passes
118 • Test::Kwalitee passes
120
122 The regression tests do not cover blessed code or glob references.
123 Any other issues:
125 <http://rt.cpan.org/Dist/Display.html?Queue=Devel-EnforceEncapsulation>
126
128 Clotho Advanced Media Inc., cpan@clotho.com
129 Maintainer: Chris Dolan
131
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 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 Ricardo Signes contributed the "{policy =" 'carp'}> feature (with
144 tests!). <http://rt.cpan.org/Ticket/Display.html?id=22024>
145perl v5.36.0 2022-07-22 Devel::EnforceEncapsulation(3)