blib/lib/Sub/Usage.pm

filter: Statementstmt 90.2% 37 / 41 Branchbran 75.0% 12 / 16 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 9 / 9 Podpod 100% 4 / 4 totaltotal 88.5% 62 / 70 CC 9 SCAR 11.8
CC
9
Cov
86%
parse_fqpn
5.8
_usage
4.1
warn_soft
2.0
CRAP 3.3
↑ Summary
1 package Sub::Usage;
2  
3 # Copyright (C) 2002 Trabas. All rights reserved.
4 #
5 # This program is free software. You may freely use it, modify
6 # and/or distribute it under the same term as Perl itself.
7 #
8 # $Revision: 1.1.1.1 $
9 # $Date: 2002/02/26 00:11:27 $
10  
11 =head1 NAME
12  
13 Sub::Usage - Issue subroutine/method usage
14  
15 =head1 SYNOPSIS
16  
17 use Sub::Usage;
18  
19 sub turn_on {
20 @_ >= 2 or usage 'NAME, COLOR [, INTENSITY]';
21 # sub continues
22 }
23  
24 =cut
25  
26 1 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
28 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 1 ▶use Carp qw(confess cluck);
Subroutine BEGIN: called CC=1 SCAR=0.0
30 1 require Exporter;
31  
32 =head1 EXPORT
33  
34 Only the C<usage> function is exported by default. You may optionally
35 import the C<warn_hard> and C<warn_soft> functions or use the tag B<:all>
36 to import all available symbols. C<parse_fqpn> will only be imported if it
37 is explicitly requested; it is not included in the B<:all> tag.
38  
39 =cut
40  
41 1 our @ISA = qw(Exporter);
42 1 our %EXPORT_TAGS = ('all' => [qw(usage warn_hard warn_soft)]);
43 1 our @EXPORT_OK = (@{$EXPORT_TAGS{'all'}}, 'parse_fqpn');
44 1 our @EXPORT = qw(usage);
45 1 our $VERSION = '0.03';
46  
47 4 ▶sub _usage {
Subroutine _usage: called CC=4 SCAR=14.2
48 4 my($caller, $arg, $prefix) = @_;
49 4 ▶ unless ($caller) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($caller) 0 4 4
50 0 $caller = parse_fqpn((caller 1)[3]);
51 0 confess __PACKAGE__,
52 "::$caller() must be called from a method or subroutine";
53 }
54  
55 4 my $usage = parse_fqpn($caller);
56 4 ▶ $usage = "$prefix\->$usage" if defined $prefix;
Branch: 1 branch
BranchTrueFalseTotal
if defined $prefix 1 3 4
57 4 ▶ $arg = '' unless defined $arg;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $arg 1 3 4
58 4 $usage .= "($arg)";
59 4 return "usage: $usage";
60 }
61  
62 =head1 ABSTRACT
63  
64 B<Sub::Usage> provides functions to issue the usage of subroutines
65 or methods from inside the stub. The issued usage is part of the
66 error message or warning when the subroutine in question is called
67 with inappropriate parameters.
68  
69 =head1 DESCRIPTION
70  
71 B<Sub::Usage> provides functions to display usage of subroutines
72 or methods from inside the stub. Some people like to check the
73 parameters of the routine. For example,
74  
75 # turn_on(NAME, COLOR [, INTENSITY])
76 sub turn_on {
77 @_ >= 2 or die "usage: turn_on(NAME, COLOR [, INTENSITY])\n";
78 # the process goes on
79 }
80  
81 With the C<usage> function (exported by default), you can achieve the same
82 results (and more) without having to remember the subroutine name.
83  
84 use Sub::Usage;
85  
86 sub turn_on {
87 @_ >= 2 or usage 'NAME, COLOR [, INTENSITY]';
88 # process goes on
89 }
90  
91 =over 8
92  
93 =item B<usage()>
94  
95 The C<usage> function makes use of the built-in C<caller> function to
96 determine the subroutine name. When, for example, C<turn_on> is called
97 with inappropriate parameters, C<usage> will terminate the program with
98 backtrace information and print an error message like the following:
99  
100 usage: turn_on(NAME, COLOR [, INTENSITY])
101  
102 If C<turn_on> is a method, a prefix can be added to indicate whether
103 it is being called as an object method or a class method.
104  
105 package Light::My::Fire;
106 use Sub::Usage;
107  
108  
109 sub turn_on {
110 @_ >= 3 or usage 'NAME, COLOR [, INTENSITY]', '$light';
111 # process goes on
112 }
113  
114 or,
115  
116 sub turn_on {
117 @_ >= 3 or usage 'NAME, COLOR [, INTENSITY]', __PACKAGE__;
118 # process goes on
119 }
120  
121 The error message will then be either:
122  
123 usage: $light->turn_on(NAME, COLOR [, INTENSITY])
124  
125 or,
126  
127 usage: Light::My::Fire->turn_on(NAME, COLOR [, INTENSITY])
128  
129 =cut
130  
131 2 ▶sub usage { confess _usage((caller 1)[3], @_) }
Subroutine usage: called CC=1 SCAR=0.0
Pod documented
132  
133 =pod
134  
135 =item B<warn_hard>
136  
137 =item B<warn_soft>
138  
139 The C<warn_hard> and C<warn_soft> functions are similar to C<usage>, but
140 they don't die. Instead, as the their names suggest, they only warn
141 about the problem and return undef. This can be handy for having the
142 subroutine print the error message and return immediately in one
143 step.
144  
145 sub turn_off {
146 @_ >= 2 or return warn_hard('NAME', '$light');
147 # process goes on
148 }
149  
150 The difference between the two is that C<warn_soft> only works when
151 B<$^W> holds true, while C<warn_hard> always works regardless of the
152 value of B<$^W>.
153  
154 =cut
155  
156 1 ▶sub warn_hard {
Subroutine warn_hard: called CC=1 SCAR=0.0
Pod documented
157 1 cluck _usage((caller 1)[3], @_);
158 1 return;
159 }
160  
161 2 ▶sub warn_soft {
Subroutine warn_soft: called CC=2 SCAR=6.9
Pod documented
162 2 ▶ cluck _usage((caller 1)[3], @_) if $^W;
Branch: 1 branch
BranchTrueFalseTotal
if $^W 1 1 2
163 2 return;
164 }
165  
166 =pod
167  
168 =item B<parse_fqpn>
169  
170 The C<parse_fqpn> function is called internally. It takes a string that
171 contains a fully qualified package name and returns pieces of the name.
172 It can also accept numeric parameters that determine what it returns.
173  
174 By default, it will just return the last part of the name, which is the
175 subroutine name in this case. Of course it doesn't know whether it's
176 really a subroutine name or another name from the symbol table, or even
177 just garbage.
178  
179 # get subroutine name: usage()
180 my $sub = parse_fqpn('Sub::Usage::usage');
181  
182 # get the package name: Sub::Usage
183 my $sub = parse_fqpn('Sub::Usage::usage', 1);
184  
185 # get both the package and sub name
186 my($pack, $sub) = parse_fqpn('Sub::Usage::usage', 2);
187  
188 # get all pieces
189 my(@parts) = parse_fqpn('Sub::Usage::usage', 3);
190  
191 =cut
192  
193 6 ▶sub parse_fqpn {
Subroutine parse_fqpn: called CC=5 SCAR=17.5
Pod documented
194 6 my($sub, $how) = @_;
195 6 ▶ confess 'usage: parse_fqpn( FQPN [, HOW] )' unless $sub;
Branch: 1 branch
BranchTrueFalseTotal
unless $sub 0 6 6
196 6 $sub =~ /(.*)::(.*)/;
197 6 ▶ return $2 unless $how;
Branch: 1 branch
BranchTrueFalseTotal
unless $how 5 1 6
198 1 ▶ return $1 if $how == 1;
Branch: 1 branch
BranchTrueFalseTotal
if $how == 1 0 1 1
199 1 ▶ return($1, $2) if $how == 2;
Branch: 1 branch
BranchTrueFalseTotal
if $how == 2 1 0 1
200 0 my @packs = split /::/, $1;
201 0 return(@packs, $2);
202 }
203  
204 =pod
205  
206 =back
207  
208 =head1 BUGS
209  
210 The C<usage> function and friends should not be called from anywhere
211 outside subroutines or methods, such as the main space. It will die when
212 it detects such situation. For example:
213  
214 #!perl
215 usage();
216  
217 This will result in an error message such as:
218  
219 Sub::Usage::usage() must be called from a method or subroutine
220  
221 Unfortunately, the underlying function relies too much on C<caller(1)>
222 to return the fourth element as subroutine name. But this is not the
223 situation in eval context, as documented in C<perldoc -f caller>. This
224 causes the C<usage> and friends behave unexpectedly.
225  
226 The workaround is simply don't call them outside of subroutines or methods.
227 This is utility for the subs, after all :-)
228  
229 =head1 AUTHOR
230  
231 Hasanuddin Tamir E<lt>hasant@trabas.comE<gt>
232  
233 =head1 COPYRIGHT
234  
235 Copyright (C) 2002 Trabas. All rights reserved.
236  
237 This program is free software. You may freely use it, modify
238 and/or distribute it under the same term as Perl itself.
239  
240 =head1 THANKS
241  
242 I'd like to thank Matthew Sachs E<lt>matthewg@zevils.comE<gt> for his
243 patch on the POD and suggestion on renaming to Sub::Usage.
244  
245 =head1 SEE ALSO
246  
247 L<perl>.
248  
249 =cut
250  
251  
252 1 1;
↑ Summary