1MooseX::Deprecated(3) User Contributed Perl DocumentationMooseX::Deprecated(3)
2
3
4

NAME

6       MooseX::Deprecated - mark attributes and methods as deprecated
7

SYNOPSIS

9          package Goose
10          {
11             use Moose;
12
13             has feathers => (is => 'ro');
14
15             sub honk { say "Honk!" }
16
17             with "MooseX::Deprecated" => {
18                attributes => [ "feathers" ],
19                methods    => [ "honk" ],
20             };
21          }
22

DESCRIPTION

24       MooseX::Deprecated is a parameterizable role that makes it easy to
25       deprecate particular attributes and methods in a class.
26
27       In the SYNOPSIS above, "before" method modifiers will be installed on
28       the "feathers" accessor and the "honk" method, issuing a deprecation
29       warning. Additionally, an "after" modifier will be installed on the
30       class' "BUILD" method which will issue deprecation warnings for any
31       deprecated attributes passed to the constructor.
32
33       The warning text will be something along the lines of: "%s is a
34       deprecated %s"
35
36       Warnings are issued in the "deprecated" warnings category, so can be
37       disabled using:
38
39          no warnings qw( deprecated );
40
41       Warnings can be upgraded to fatal errors with:
42
43          use warnings FATAL => qw( deprecated );
44
45       Warnings will only be issued once per call site.
46
47       When consuming the role you must pass either a list of attributes, or a
48       list of methods, or both, as parameters to the role. If you forget to
49       do so, you'll get an error message like: "%s with no list of attributes
50       or methods".
51

CAVEATS

53       To deprecate an attribute, the attribute must actually exist at the
54       time you consume this role. In particular, this will not work:
55
56          package Goose
57          {
58             use Moose;
59
60             with "MooseX::Deprecated" => {
61                attributes => [ "feathers" ],
62             };
63
64             has feathers => (is => 'ro');
65          }
66
67       Because the "feathers" attribute isn't defined until after the role is
68       consumed. Attempting the above will die with a nasty error message:
69       "Attribute %s does not exist in %s so cannot be deprecated".
70
71       If a deprecated attribute handles any methods via delegation, then
72       calling these methods will result in not one, but two warnings. One
73       warning for calling the delegated method; the other warning for calling
74       the accessor (reader) to obtain the object to delegate to. This could
75       theoretically be changed, but I'm comfortable with the existing
76       situation.
77
78       Warnings issued by the accessor (reader) during method delegation come
79       from inside your class, and thus the caller cannot disable them or
80       fatalize them.
81

BUGS

83       Please report any bugs to
84       <http://rt.cpan.org/Dist/Display.html?Queue=MooseX-Deprecated>.
85
86   Perl 5.8
87       The behaviour of "warnings::warnif" changed significantly between Perl
88       5.8 and 5.10; the location considered to be the effective caller
89       changed from being "like "warn"" to being "like "carp"" (the latter
90       being considerably more useful). Therefore under Perl 5.8, doing things
91       like "no warnings "deprecated"" in your code to control warnings from
92       this role is rather useless, because your code is unlikely to be
93       considered to be the caller.
94
95       In the test suite I just skip the complex test that checks for this on
96       Perl prior to 5.10, allowing you to install this module without a hitch
97       on Perl 5.8. However, you are strongly discouraged from using this
98       module with Perl 5.8.
99

SEE ALSO

101       Package::DeprecationManager provides a more powerful and complicated
102       set of features. I'm a simple kind of guy, and don't see the need to
103       allow my caller to pick and choose which deprecations they'd like to
104       ignore based on some API version.
105
106       Attribute::Deprecated is cute, but only deals with methods, and
107       ironically not (what Moose calls) attributes.
108
109       Devel::Deprecation has some pretty nice features, but is more manual
110       than I'd like, and again only deals with methods.
111
112       Not to be confused with Moose::Deprecated which can be used to manage
113       warnings issued by Moose itself.
114
115       <http://en.wikipedia.org/wiki/Self-deprecation>.
116

AUTHOR

118       Toby Inkster <tobyink@cpan.org>.
119

121       This software is copyright (c) 2013-2014 by Toby Inkster.
122
123       This is free software; you can redistribute it and/or modify it under
124       the same terms as the Perl 5 programming language system itself.
125

DISCLAIMER OF WARRANTIES

127       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
128       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
129       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
130
131
132
133perl v5.32.1                      2021-01-27             MooseX::Deprecated(3)
Impressum