Sub::Usage - Issue subroutine/method usage
use Sub::Usage; sub turn_on { @_ >= 2 or usage 'NAME, COLOR [, INTENSITY]'; # sub continues }
Only the usage function is exported by default. You may optionally import the warn_hard and warn_soft functions or use the tag :all to import all available symbols. parse_fqpn will only be imported if it is explicitly requested; it is not included in the :all tag.
usage
warn_hard
warn_soft
parse_fqpn
Sub::Usage provides functions to issue the usage of subroutines or methods from inside the stub. The issued usage is part of the error message or warning when the subroutine in question is called with inappropriate parameters.
Sub::Usage provides functions to display usage of subroutines or methods from inside the stub. Some people like to check the parameters of the routine. For example,
# turn_on(NAME, COLOR [, INTENSITY]) sub turn_on { @_ >= 2 or die "usage: turn_on(NAME, COLOR [, INTENSITY])\n"; # the process goes on }
With the usage function (exported by default), you can achieve the same results (and more) without having to remember the subroutine name.
use Sub::Usage; sub turn_on { @_ >= 2 or usage 'NAME, COLOR [, INTENSITY]'; # process goes on }
The usage function makes use of the built-in caller function to determine the subroutine name. When, for example, turn_on is called with inappropriate parameters, usage will terminate the program with backtrace information and print an error message like the following:
caller
turn_on
usage: turn_on(NAME, COLOR [, INTENSITY])
If turn_on is a method, a prefix can be added to indicate whether it is being called as an object method or a class method.
package Light::My::Fire; use Sub::Usage; sub turn_on { @_ >= 3 or usage 'NAME, COLOR [, INTENSITY]', '$light'; # process goes on }
or,
sub turn_on { @_ >= 3 or usage 'NAME, COLOR [, INTENSITY]', __PACKAGE__; # process goes on }
The error message will then be either:
usage: $light->turn_on(NAME, COLOR [, INTENSITY])
usage: Light::My::Fire->turn_on(NAME, COLOR [, INTENSITY])
The warn_hard and warn_soft functions are similar to usage, but they don't die. Instead, as the their names suggest, they only warn about the problem and return undef. This can be handy for having the subroutine print the error message and return immediately in one step.
sub turn_off { @_ >= 2 or return warn_hard('NAME', '$light'); # process goes on }
The difference between the two is that warn_soft only works when $^W holds true, while warn_hard always works regardless of the value of $^W.
The parse_fqpn function is called internally. It takes a string that contains a fully qualified package name and returns pieces of the name. It can also accept numeric parameters that determine what it returns.
By default, it will just return the last part of the name, which is the subroutine name in this case. Of course it doesn't know whether it's really a subroutine name or another name from the symbol table, or even just garbage.
# get subroutine name: usage() my $sub = parse_fqpn('Sub::Usage::usage'); # get the package name: Sub::Usage my $sub = parse_fqpn('Sub::Usage::usage', 1); # get both the package and sub name my($pack, $sub) = parse_fqpn('Sub::Usage::usage', 2); # get all pieces my(@parts) = parse_fqpn('Sub::Usage::usage', 3);
The usage function and friends should not be called from anywhere outside subroutines or methods, such as the main space. It will die when it detects such situation. For example:
#!perl usage();
This will result in an error message such as:
Sub::Usage::usage() must be called from a method or subroutine
Unfortunately, the underlying function relies too much on caller(1) to return the fourth element as subroutine name. But this is not the situation in eval context, as documented in perldoc -f caller. This causes the usage and friends behave unexpectedly.
caller(1)
perldoc -f caller
The workaround is simply don't call them outside of subroutines or methods. This is utility for the subs, after all :-)
Hasanuddin Tamir <hasant@trabas.com>
Copyright (C) 2002 Trabas. All rights reserved.
This program is free software. You may freely use it, modify and/or distribute it under the same term as Perl itself.
I'd like to thank Matthew Sachs <matthewg@zevils.com> for his patch on the POD and suggestion on renaming to Sub::Usage.
perl.
To install Sub::Usage, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sub::Usage
CPAN shell
perl -MCPAN -e shell install Sub::Usage
For more information on module installation, please visit the detailed CPAN module installation guide.