File::Package(3) User Contributed Perl Documentation File::Package(3)NAMEFile::Package - test load a pm and import symbols without eval and $@
misbehavoirs
SYNOPSIS
##########
# Subroutine interface
#
use File::Package qw(is_package_loaded load_package);
$yes = is_package_loaded($package, $program_module);
$error = load_package($program_module);
$error = load_package($program_module, @import);
$error = load_package($program_module, [@package_list]);
$error = load_package($program_module, @import, [@package_list]);
##########
# Class Interface
#
use File::Package;
$yes = is_package_loaded($package, $program_module);
$error = File::Package->load_package($program_module);
$error = File::Package->load_package($program_module, @import);
$error = File::Package->load_package($program_module, [@package_list]);
$error = File::Package->load_package($program_module, @import, [@package_list]);
DESCRIPTION
In a perfect Perl, everything would behave exactly the same running
under "eval". Many times the reason to use an "eval" is the anticipa-
tion that the expression may die. When that happens, a perfect Perl
would have deposited all the output fromm the "warn" and "die" in $@.
Maybe you have a perfect Perl. However, it is shocking that there are
some Perls on some platforms out in the wild that are mutants and are
not perfect.
A "require" under eval works just fine just to see if a program will
load or not. If working locally, you can simply devise a quick debug
setup and track down the problem. However, when running tests
remotely, on different remote platforms, running continuously unat-
tended where uptime is important, or any number of situations it is
very helpful to have meaningful error messages when a problem arise.
Thus, the reason to run under "eval" is not only to avoid the "die" but
also to pick up the error message returned by "eval" in $@. In certain
situations it is extremely critical to obtain reliable error messages
when a failure occurs.
Well, a "eval "require $program_module"" failure returns a reasonble
looking $@ except for one small thing. Not all the warnings make it to
$@ at least on one Perl, probably more. And there can be quite a few
warnings when loading a broken program module. It would be nice if
everyone could update to a Perl where the "eval" deposits all the warn-
ings in $@. But as the acient proverb says, "If wishes were horses,
beggers would ride.".
One workaround is to catch the warnings with $SIG{__WARN__} when run-
ning the "require" under a "eval". This collects all the warnings
which is good. Now when a load fails, the program does not die, it
gracefully collects all the warnings and logs them or ships back.
Now try the "import" under "eval" and pick up the error messages. The
"import" and "eval" is big time "failure to communicate" aka the movie
"Cool Hand Luke". The "import" uses the caller stack to determine
where to stuff the symbols and there is a lot of "Carp" "croak" gyra-
tions such as making "import" look like "use", trapping "warnings" and
"dies". The "eval" takes off on its own caller stack which to quote
President Bush: "is not helpful".
The "import" uses the "croak" instead of "die" directly or else any
efforts to get meaningfull error messages would be dead on arrival.
Perl is designed so that it is nearly impossible to avoid a die unless
running under a "eval". A workaround is hooking in a "croak" that does
not die and collecting the error messages.
Subroutines
is_package_loaded
$package = is_package_loaded($program_module, $package)
The "is_package_loaded" subroutine determines if the $package is
present and the $progarm_module loaded. If $package is absent, 0 or
'', $package is set to the "program_module".
load_package
$error = load_package($program_module, @import, [@package_list]);
The "load_package" subroutine attempts to capture any load problems by
loading the package with a "require " under an eval and capturing all
the "warn" and $@ messages.
If the $program_module load is successful, the checks that the packages
in the @package list are present. If @package list is absent, the
$program_module uses the "program_module" name as a list of one pack-
age. Although a program module and package have the same name syntax,
they are entirely different. A program module is a file. A package is
a hash of symbols, a symbol table. The Perl convention is that the
names for each are the same which enhances the appearance that they are
the same when in fact they are different. Thus, a program module may
have a single package with a different name or many different packages.
Finally the $program_module subroutine will import the symbols in the
@import list. If @import is absent $program_module subroutine does not
import any symbols; if @import is '', all symbols are imported. A
@import of 0 usually results in an $error.
The $program_module traps all load errors and all import "Carp::Crock"
errors and returns them in the $error string.
One very useful application of the "load_package" subroutine is in test
scripts. If a package does load, it is very helpful that the program
does not die and reports the reason the package did not load. This
information is readily available when loaded at a local site. However,
it the load occurs at a remote site and the load crashes Perl, the
remote tester usually will not have this information readily available.
Other applications include using backup alternative software if a pack-
age does not load. For example if the package 'Compress::Zlib' did not
load, an attempt may be made to use the gzip system command.
BUGS
The "load_package" cannot load program modules whose name contain the
'-' characters. The 'eval' function used to trap the die errors
believes it means subtraction.
REQUIREMENTS
Coming.
DEMONSTRATION
#########
# perl Package.d
###
~~~~~~ Demonstration overview ~~~~~
Perl code begins with the prompt
=>
The selected results from executing the Perl Code follow on the next
lines. For example,
=> 2 + 2
4
~~~~~~ The demonstration follows ~~~~~
=> use File::Package;
=> my $uut = 'File::Package';
=> ##################
=> # Good Load
=> #
=> ###
=> my $error = $uut->load_package( 'File::Basename' )
''
=> $error = $uut->load_package( '_File_::BadLoad' )
'Cannot load _File_::BadLoad
syntax error at E:/User/SoftwareDiamonds/installation/t/File/_File_/BadLoad.pm line 13, near "$FILE "
Global symbol "$FILE" requires explicit package name at E:/User/SoftwareDiamonds/installation/t/File/_File_/BadLoad.pm line 13.
Compilation failed in require at (eval 12) line 1.
Scalar found where operator expected at E:/User/SoftwareDiamonds/installation/t/File/_File_/BadLoad.pm line 13, near "$FILE"
(Missing semicolon on previous line?)
'
=> $uut->load_package( '_File_::BadPackage' )
'# _File_::BadPackage file but package(s) _File_::BadPackage absent.
'
=> $uut->load_package( '_File_::Multi' )
'# _File_::Multi file but package(s) _File_::Multi absent.
'
=> $error = $uut->load_package( '_File_::Hyphen-Test' )
'Cannot load _File_::Hyphen-Test
syntax error at (eval 15) line 1, near "require _File_::Hyphen-"
Warning: Use of "require" without parens is ambiguous at (eval 15) line 1.
'
=> ##################
=> # No &File::Find::find import baseline
=> #
=> ###
=> !defined($main::{'find'})
'1'
=> ##################
=> # Load File::Find, Import &File::Find::find
=> #
=> ###
=> $error = $uut->load_package( 'File::Find', 'find', ['File::Find'] )
''
=> ##################
=> # &File::Find::find imported
=> #
=> ###
=> defined($main::{'find'})
'1'
=> ##################
=> # &File::Find::finddepth not imported
=> #
=> ###
=> !defined($main::{'finddepth'})
'1'
=> ##################
=> # Import error
=> #
=> ###
=> $uut->load_package( 'File::Find', 'Jolly_Green_Giant')
'"Jolly_Green_Giant" is not exported by the File::Find module
Can't continue after import errors at D:/Perl/lib/Exporter/Heavy.pm line 127
Exporter::heavy_export('File::Find', 'main', 'Jolly_Green_Giant') called at D:/Perl/lib/Exporter.pm line 45
Exporter::import('File::Find', 'Jolly_Green_Giant') called at (eval 9) line 81
File::Package::load_package('File::Package', 'File::Find', 'Jolly_Green_Giant') called at E:\User\SoftwareDiamonds\installation\t\File\Package.d line 195
'
=> ##################
=> # &File::Find::finddepth still no imported
=> #
=> ###
=> !defined($main::{'finddepth'})
'1'
=> ##################
=> # Import all File::Find functions
=> #
=> ###
=> $error = $uut->load_package( 'File::Find', '')
''
=> ##################
=> # &File::Find::finddepth imported
=> #
=> ###
=> defined($main::{'finddepth'})
'1'
QUALITY ASSURANCE
Running the test script "package.t" verifies the requirements for this
module.
The <tmake.pl> cover script for Test::STDmaker automatically generated
the "package.t" test script, "package.d" demo script, and
"t::File::Package" STD program module POD, from the "t::File::Package"
program module contents. The "t::File::Package" program module is in
the distribution file File-Package-$VERSION.tar.gz.
NOTES
AUTHOR
The holder of the copyright and maintainer is
<support@SoftwareDiamonds.com>
COPYRIGHT NOTICE
Copyrighted (c) 2002 Software Diamonds
All Rights Reserved
BINDING REQUIREMENTS NOTICE
Binding requirements are indexed with the pharse 'shall[dd]' where dd
is an unique number for each header section. This conforms to standard
federal government practices, 490A ("3.2.3.6" in STD490A). In accor-
dance with the License, Software Diamonds is not liable for any
requirement, binding or otherwise.
LICENSE
Software Diamonds permits the redistribution and use in source and
binary forms, with or without modification, provided that the following
conditions are met:
1 Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2 Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribu-
tion.
SOFTWARE DIAMONDS, http::www.softwarediamonds.com, PROVIDES THIS SOFT-
WARE 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SOFTWARE DIAMONDS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING USE OF THIS SOFTWARE,
EVEN IF ADVISED OF NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
THE POSSIBILITY OF SUCH DAMAGE.
SEE ALSO
Docs::Site_SVD::File_Package
Test::STDmaker
perl v5.8.8 2004-04-26 File::Package(3)
