Only enable the pragma during compile time
[perl/modules/indirect.git] / README
1 NAME
2     indirect - Lexically warn about using the indirect object syntax.
3
4 VERSION
5     Version 0.15
6
7 SYNOPSIS
8         # In a script
9         no indirect;
10         my $x = new Apple 1, 2, 3; # warns
11         {
12          use indirect;
13          my $y = new Pear; # ok
14          {
15           no indirect hook => sub { die "You really wanted $_[0]\->$_[1] at $_[2]:$_[3]" };
16           my $z = new Pineapple 'fresh'; # croaks 'You really wanted Pineapple->new at blurp.pm:13'
17          }
18         }
19         no indirect ':fatal';
20         if (defied $foo) { ... } # croaks, note the typo
21
22         # From the command-line
23         perl -M-indirect -e 'my $x = new Banana;' # warns
24
25         # Or each time perl is ran
26         export PERL5OPT="-M-indirect"
27         perl -e 'my $y = new Coconut;' # warns
28
29 DESCRIPTION
30     When enabled (or disabled as some may prefer to say, since you actually
31     turn it on by calling "no indirect"), this pragma warns about indirect
32     object syntax constructs that may have slipped into your code. This
33     syntax is now considered harmful, since its parsing has many quirks and
34     its use is error prone (when "swoosh" isn't defined, "swoosh $x"
35     actually compiles to "$x->swoosh").
36
37     It currently does not warn when the object is enclosed between braces
38     (like "meth { $obj } @args") or for core functions ("print" or "say").
39     This may change in the future, or may be added as optional features that
40     would be enabled by passing options to "unimport".
41
42     This module is not a source filter.
43
44 METHODS
45   "unimport [ hook => $hook | ':fatal' ]"
46     Magically called when "no indirect @opts" is encountered. Turns the
47     module on. The policy to apply depends on what is first found in @opts :
48
49     *   If it's the string ':fatal', the compilation will croak on the first
50         indirect syntax met.
51
52     *   If the key/value pair "hook => $hook" comes first, $hook will be
53         called for each error with the object name as $_[0], the method name
54         as $_[1], the current file as $_[2] and the line number as $_[3].
55
56     *   Otherwise, a warning will be emitted for each indirect construct.
57
58   "import"
59     Magically called at each "use indirect". Turns the module off.
60
61 CONSTANTS
62   "I_THREADSAFE"
63     True iff the module could have been built with thread-safety features
64     enabled.
65
66 CAVEATS
67     The implementation was tweaked to work around several limitations of
68     vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
69     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
70     "require"d scopes.
71
72     "meth $obj" (no semicolon) at the end of a file won't be seen as an
73     indirect object syntax, although it will as soon as there is another
74     token before the end (as in "meth $obj;" or "meth $obj 1").
75
76     With 5.8 perls, the pragma does not propagate into "eval STRING". This
77     is due to a shortcoming in the way perl handles the hints hash, which is
78     addressed in perl 5.10.
79
80 DEPENDENCIES
81     perl 5.8.
82
83     XSLoader (standard since perl 5.006).
84
85 AUTHOR
86     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
87
88     You can contact me by mail or on "irc.perl.org" (vincent).
89
90 BUGS
91     Please report any bugs or feature requests to "bug-indirect at
92     rt.cpan.org", or through the web interface at
93     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
94     notified, and then you'll automatically be notified of progress on your
95     bug as I make changes.
96
97 SUPPORT
98     You can find documentation for this module with the perldoc command.
99
100         perldoc indirect
101
102     Tests code coverage report is available at
103     <http://www.profvince.com/perl/cover/indirect>.
104
105 ACKNOWLEDGEMENTS
106     Bram, for motivation and advices.
107
108 COPYRIGHT & LICENSE
109     Copyright 2008-2009 Vincent Pit, all rights reserved.
110
111     This program is free software; you can redistribute it and/or modify it
112     under the same terms as Perl itself.
113