blib/lib/Devel/UseFromCommandLineOnly.pm

filter: Statementstmt 77.2% 17 / 22 Branchbran 50.0% 3 / 6 Conditioncond 0.0% 0 / 6 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 100% 4 / 4 Podpod n/a totaltotal 58.5% 24 / 41 CC 7 SCAR 25.6
CC
7
Cov
59%
import
18.1
BEGIN
1.0
BEGIN
1.0
CRAP 12.9
↑ Summary
1 package Devel::UseFromCommandLineOnly;
2  
3 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 #use warnings;
5  
6 2 ▶use Carp qw(croak confess);
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 2 ▶use vars qw($VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 2 $VERSION = "1.00";
10  
11 =head1 NAME
12  
13 Devel::UseFromCommandLineOnly - use a module from the command line only
14  
15 =head1 SYNOPSIS
16  
17 package Foo;
18 use base qw(Devel::UseFromCommandLineOnly);
19  
20 # it's okay to use from the command line
21 # these examples will work
22 perl -MFoo -E 'say "This will work!"'
23 perl -MFoo -E 'say "This will work!"'
24 echo 'use Foo; use 5.010; say "This will work!' | perl
25  
26 # but not from a file or module
27 # these examples will die
28 echo "use Foo;" > /tmp/foo.pl; perl /tmp/foo.pl
29 echo "package Bar; use Foo;" > /tmp/Bar.pm; perl -I/tmp -MBar
30  
31 =head1 DESCRIPTION
32  
33 This module prevents you from loading any subclass of it from anywhere but
34 the command line.
35  
36 This is most useful for writing development tools that monkeypatch other people's
37 code. These hacks are fine to enable from the command line during development,
38 but you wouldn't want to allow anyone to perminatly install them in any code that
39 they could ship as the hacks could break at any point. See L<Test::EnhancedIs>
40 as a good example of this.
41  
42 To use it you simply subclass the module:
43  
44 package Foo;
45 use base qw(Devel::UseFromCommandLineOnly);
46  
47 This exposes an C<import> routine that checks if you're calling it from a
48 script or module or from the command line and throws an exception if it's
49 the former.
50  
51 =cut
52  
53 2 ▶sub import {
Subroutine import: called CC=7 SCAR=28.9
54 2 my $pkg = shift;
55  
56 # don't fire when the module that's using this uses it
57 2 ▶ if ($pkg eq "Devel::UseFromCommandLineOnly") {
Branch: 1 branch
BranchTrueFalseTotal
if ($pkg eq "Devel::UseFromCommandLineOnly") 1 1 2
58 1 return;
59 }
60  
61 # process all other import arguments
62 1 foreach (@_) {
63  
64 # skip the checks if they're disabled
65 1 ▶ if ($_ eq "disable_command_line_checks") {
Branch: 1 branch
BranchTrueFalseTotal
if ($_ eq "disable_command_line_checks") 1 0 1
66 1 return;
67 }
68  
69 # go bang if we didn't understand the import argument
70 0 croak "Invalid import argument to $pkg: $_"
71  
72 }
73  
74 # panic if this isn't a "-" or "-e" invocation
75 0 my ($package, $filename, $line) = caller;
76 0 ▶ unless ($filename eq "-e" || $filename eq "-" || $line == 0) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($filename eq "-e" or $filename eq "-" or $line == 0) 0 0 0
Condition0%0/6
$filename eq "-e" or $filename eq "-" or $line == 0
l!l&&r!l&&!r
000
$filename eq "-e" or $filename eq "-"
l!l&&r!l&&!r
000
MC/DC0%0/3
$filename eq "-e" or $filename eq "-" or $line == 0
$filename eq "-e" $filename eq "-" $line == 0
Truth table0%0/4
A or B or C
A= $filename eq "-e"B= $filename eq "-"C= $line == 0
ABCresult
1XX1
01X1
0011
0000
77 0 croak "Invalid use of $pkg in '$filename' at line $line; This module can only be loaded from the command line";
78 }
79  
80 0 return;
81 }
82  
83 =head2 Disabling this module's functionality
84  
85 The one place that subclasses of this module will be needed to be loaded
86 from within a script that is testing that subclass. In this case
87 it's possible to override this module's behavior:
88  
89 #!/usr/bin/perl
90  
91 use Test::More tests => 1;
92 use Foo qw(disable_command_line_checks);
93 isa_ok(Foo->new(), "Foo");
94  
95 End users should NEVER EVER DO THIS. Or, if they do, they're playing
96 with fire and deserve to get burnt...
97  
98 =head1 AUTHOR
99  
100 Written by Mark Fowler E<lt>mark@twoshortplanks.comE<gt>
101  
102 Copryright Mark Fowler 2009. All Rights Reserved.
103  
104 This program is free software; you can redistribute it
105 and/or modify it under the same terms as Perl itself.
106  
107 =head1 BUGS
108  
109 None known.
110  
111 Please see http://www.twoshortplanks.com/project/devel-usefromcommandline for
112 details of how to submit bugs, access the source control for
113 this project, and contact the author.
114  
115 =head1 SEE ALSO
116  
117 L<perl>
118  
119 =cut
120  
121 2 1;
↑ Summary