NAME

NAME
File::Where - find the absolute file for a program module; absolute dir
for a repository

SYNOPSIS
#######
# Subroutine interface
#
use File::Where qw(pm2require where where_dir where_file where_pm where_repository);

$program_module = is_module(@program_modules);
@program_modules = dir_pms( $dir );
@program_modules = program_modules( $dir, 'file_flag', @dirs);
$file = pm2require($pm);
@program_modules = repository_pms($repository);

$abs_file = where($relative_file);
$abs_file = where($relative_file, \@path);

($abs_file, $inc_path, $rel_fle) = where($relative_file)
($abs_file, $inc_path, $rel_fle) = where($relative_file, \@path);

$abs_dir = where($relative_dir, '', 'nofile');
$abs_dir = where($relative_dir, \@path, 'nofile');

($abs_dir, $inc_path, $rel_dir) = where($relative_dir, '', 'nofile');
($abs_dir, $inc_path, $rel_dir) = where($relative_dir, \@path, 'nofile');

$abs_dir = where_dir($relative_dir);
$abs_dir = where_dir($relative_dir, \@path;
$abs_dir = where_dir($relative_dir, @path;

($abs_dir, $inc_path, $rel_dir) = where_dir($relative_dir);
($abs_dir, $inc_path, $rel_dir) = where_dir($relative_dir, \@path);
($abs_dir, $inc_path, $rel_dir) = where_dir($relative_dir, @path);

$abs_file = where_file($relative_file);
$abs_file = where_file($relative_file, \@path);
$abs_file = where_file($relative_file, @path);

($abs_file, $inc_path, $rel_fle) = where_file($relative_file)
($abs_file, $inc_path, $rel_fle) = where_file($relative_file, \@path)
($abs_file, $inc_path, $rel_fle) = where_file($relative_file, @path)

$abs_file = where_pm($pm);
$abs_file = where_pm($pm, \@path);
$abs_file = where_pm($pm, @path);

($abs_file, $inc_path, $require) = where_pm($pm);
($abs_file, $inc_path, $require) = where_pm($pm, \@path);
($abs_file, $inc_path, $require) = where_pm($pm, @path);

$abs_dir = where_repository($repository);
$abs_dir = where_repository($repository, \@path);
$abs_dir = where_repository($repository, @path);

($abs_dir, $inc_path, $rel_dir) = where_repository($repository);
($abs_dir, $inc_path, $rel_dir) = where_repository($repository, \@path);
($abs_dir, $inc_path, $rel_dir) = where_repository($repository, @path);

#######
# Class interface
#
$program_module = File::Where->is_module(@program_modules);
@program_modules = File::Where->dir_pms( $dir );
@program_modules = File::Where->program_modules( $dir, 'file_flag', @dirs);
$file = File::Where->pm2require($pm);
@program_modules = File::Where->repository_pms($repository);

$abs_file = File::Where->where($relative_file);
$abs_file = File::Where->where($relative_file, \@path);
$abs_dir = File::Where->where($relative_dir, '', 'nofile');
$abs_dir = File::Where->where($relative_dir, \@path, 'nofile');

($abs_file, $inc_path, $require) = File::Where->where($relative_file)
($abs_file, $inc_path, $require) = File::Where->where($relative_file, \@path)
($abs_dir, $inc_path, $rel_dir) = File::Where->where($relative_dir, '', 'nofile');
($abs_dir, $inc_path, $rel_dir) = File::Where->where($relative_dir, \@path, 'nofile');

$abs_dir = File::Where->where_dir($relative_dir);
$abs_dir = File::Where->where_dir($relative_dir, \@path;
$abs_dir = File::Where->where_dir($relative_dir, @path;

($abs_dir, $inc_path, $rel_dir) = File::Where->where_dir($relative_dir);
($abs_dir, $inc_path, $rel_dir) = File::Where->where_dir($relative_dir, \@path);
($abs_dir, $inc_path, $rel_dir) = File::Where->where_dir($relative_dir, @path);

$abs_file = File::Where->where_file($relative_file);
$abs_file = File::Where->where_file($relative_file, \@path);
$abs_file = File::Where->where_file($relative_file, @path);

($abs_file, $inc_path, $require) = File::Where->where_file($relative_file)
($abs_file, $inc_path, $require) = File::Where->where_file($relative_file, \@path)
($abs_file, $inc_path, $require) = File::Where->where_file($relative_file, @path)

$abs_file = File::Where->where_pm($pm);
$abs_file = File::Where->where_pm($pm, \@path);
$abs_file = File::Where->where_pm($pm, @path);

($abs_file, $inc_path, $require) = File::Where->where_pm($pm);
($abs_file, $inc_path, $require) = File::Where->where_pm($pm, \@path);
($abs_file, $inc_path, $require) = File::Where->where_pm($pm, @path);

$abs_dir = File::Where->where_repository($repository);
$abs_dir = File::Where->where_repository($repository, \@path);
$abs_dir = File::Where->where_repository($repository, @path);

($abs_dir, $inc_path, $rel_dir) = File::Where->where_repository($repository);
($abs_dir, $inc_path, $rel_dir) = File::Where->where_repository($repository, \@path);
($abs_dir, $inc_path, $rel_dir) = File::Where->where_repository($repository, @path);

DESCRIPTION
From time to time, an program needs to know the abolute file for a
program module that has not been loaded. The File::Where module provides
methods to find this information. For loaded files, using the hash %INC
may perform better than using the methods in this module.

SUBROUTINES
is_module

$program_module = is_module(@program_modules);

The "is_module" subroutine determines if a *$module* is present in a
list of modules "@modules". The detemination is case insensitive and
only the leading characters are needed.

dir_pms

@program_modules = dir_pms( $dir );

The "dir_pms" subroutine returns the "@program_modules" in directory
"$dir".

program_modules

@program_modules = program_modules( $dir, '$file_flag', @dirs);

The "program_modules" subroutine returns the program_modules in the dir
"File::Spec-"catdir($dir,@dirs) with an empty 'file_flag'; otherwise
with a 'file_flag', "$dir" is a file specification and "program_modules"
subroutine only uses the directory portion of "$dir".

repository_pms

@program_modules = repository_pms($repository);

The "repository_pms" returns the "@program_modules" in "repository". A
repository is the a program module name that corresponds to a directory.
For example, a repository for "File::Where" is "File".

pm2require subroutine

$file = pm2require($pm_file)

The *pm2require* method/subroutine returns the file suitable for use in
a Perl "require" for the "$pm" program module.

where subroutine

The where subroutine is the core subroutine call by where_file,
where_dir, where_pm and where_repository.

When $no_file is absent, 0 or '', the where subroutine performs as
established for the "where_file" subroutine; otherwise the where
subroutine performs as established for the "where_dir" subroutine.

The differences is that the "where" syntax only accepts a reference to
an array path while the "where_dir" and "where_file" accept both a
reference to an array path and an array path.

where_dir subroutine

When $nofile exists and is non-zero, the "find_in_include"
method/subroutine looks for the "$relative_dir" under one of the
directories in the "@path" ("@INC" path if "@path" is '' or 0) in the
order listed in "@path" or "@INC". When *find_in_include* finds the
directory, it returns the absolute file "$absolute_dir" and the
directory "$path" where it found "$relative_dir" when the usage calls
for an array return; otherwise, the absolute directory "$absolute_dir".

When the "@path" list of directores exists and is not '' or 0, the
"where_dir" subroutine/method searches the "@path" list of directories
instead of the "@INC" list of directories.

where_file subroutine

When $nofile is '', 0 or absent, the "find_in_include" method/subroutine
looks for the "$relative_file" in one of the directories in the "@path"
("@INC" path if "@path" is absent, '' or 0) in the order listed in
"@path" or "@INC". When *find_in_include* finds the file, it returns the
absolute file "$file_absolute" and the directory "$path" where it found
"$file_relative" when the usage calls for an array return; otherwise,
the absolute file "$file_absolute".

When the "@path" list of directores exists and is not '' or 0, the
"where_file" subroutine/method searches the "@path" list of directories
instead of the "@INC" list of directories.

where_pm subroutine

In an array context, the *where_pm* subroutine/method returns the
"$absolute_file", the directory "$inc_path" in "@INC", and the relative
"$require_file" for the first directory in "@INC" list of directories
where it found the program module "$pm"; otherwise, it returns just the
"$absolute_file".

When the "@path" list of directores exists and is not '' or 0, the
"where_pm" subroutine/method searches the "@path" list of directories
instead of the "@INC" list of directories.

where_repository subroutine

An repository specifies the location of a number of program modules. For
example, the repository for this program module, "File::Where", is
"File::".

In an array context, the *where_repository* subroutine/method returns
the "$absolute_directory", the directory "$inc_path" in "@INC" for the
first directory in "@INC" list of directories, and the relative
directory of the repository where it found the "$repository"; otherwise,
it returns just the "$absolute_file".\ When *where_repository* cannot
find a directory containing the "$repository" relative directory,
*where_repository* pops the last directory off the "$repository"
relative directory and trys again. If *where_repository* finds that
"$repository" is empty, it returns emptys.

for the "$repository"; otherwise, it returns just the
"$absolute_directory".

When the "@path" list of directores exists and is not '' or 0, the
"where_repository" subroutine/method searches the "@path" list of
directories instead of the "@INC" list of directories.

REQUIREMENTS
DEMONSTRATION
#########
# perl Where.d
###

~~~~~~ Demonstration overview ~~~~~

The results from executing the Perl Code follow on the next lines as
comments. For example,

2 + 2
# 4

~~~~~~ The demonstration follows ~~~~~

use File::Spec;
use File::Copy;
use File::Path;
use File::Package;
my $fp = 'File::Package';

my $uut = 'File::Where';
my $loaded = '';
# Use the test file as an example since know its absolute path
#
my $test_script_dir = cwd();
chdir File::Spec->updir();
chdir File::Spec->updir();
my $include_dir = cwd();
chdir $test_script_dir;
my $OS = $^O; # need to escape ^
unless ($OS) { # on some perls $^O is not defined
require Config;
$OS = $Config::Config{'osname'};
}
$include_dir =~ s=/=\\=g if( $OS eq 'MSWin32');
$test_script_dir =~ s=/=\\=g if( $OS eq 'MSWin32');

# Put base directory as the first in the @INC path
#
my @restore_inc = @INC;

my $relative_file = File::Spec->catfile('t', 'File', 'Where.pm');
my $relative_dir1 = File::Spec->catdir('t', 'File');
my $relative_dir2 = File::Spec->catdir('t', 'Jolly_Green_Giant');

my $absolute_file1 = File::Spec->catfile($include_dir, 't', 'File', 'Where.pm');
my $absolute_dir1A = File::Spec->catdir($include_dir, 't', 'File');
my $absolute_dir1B = File::Spec->catdir($include_dir, 't');

mkpath (File::Spec->catdir($test_script_dir, 't','File'));
my $absolute_file2 = File::Spec->catfile($test_script_dir, 't', 'File', 'Where.pm');
my $absolute_dir2A = File::Spec->catdir($include_dir, 't', 'File', 't', 'File');
my $absolute_dir2B = File::Spec->catdir($include_dir, 't', 'File', 't');

#####
# If doing a target site install, blib going to be up front in @INC
# Locate the include directory with high probability of having the
# first File::Where in the include path.
#
# Really not important that that cheapen test somewhat by doing a quasi
# where search in that using this to test for a boundary condition where
# the class, 'File::Where', is the same as the program module 'File::Where
# that the 'where' subroutine/method is locating.
#
my $absolute_dir_where = File::Spec->catdir($include_dir, 'lib');
foreach (@INC) {
if ($_ =~ /blib/) {
$absolute_dir_where = $_ ;
last;
}
elsif ($_ =~ /lib/) {
$absolute_dir_where = $_ ;
last;
}
}
my $absolute_file_where = File::Spec->catfile($absolute_dir_where, 'File', 'Where.pm');

my @inc2 = ($test_script_dir, @INC); # another way to do unshift

copy $absolute_file1,$absolute_file2;
unshift @INC, $include_dir;

my (@actual,$actual); # use for array and scalar context

##################
# Load UUT
#

my $errors = $fp->load_package('File::Where', 'where_pm')
$errors

# ''
#

##################
# pm2require
#

$actual = $uut->pm2require( 'File::Where')

# 'File\Where.pm'
#

##################
# program modules('_Drivers_')
#

[my @drivers = sort $uut->program_modules( '_Drivers_' )]

# [
# 'Driver',
# 'Generate',
# 'IO'
# ]
#

##################
# is_module('dri', Driver Generate IO)
#

$uut->is_module('dri', @drivers )

# 'Driver'
#

##################
# repository_pms('t::File::_Drivers_')
#

[@drivers = sort $uut->repository_pms( 't::File::_Drivers_' )]

# [
# 'Driver',
# 'Generate',
# 'IO'
# ]
#

##################
# dir_pms( '_Drivers_' )
#

[@drivers = sort $uut->dir_pms( '_Drivers_' )]

# [
# 'Driver',
# 'Generate',
# 'IO'
# ]
#

##################
# where finding a file, array context, path absent
#

[@actual = $uut->where($relative_file)]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\Where.pm',
# 'E:\User\SoftwareDiamonds\installation',
# 't\File\Where.pm'
# ]
#

##################
# where finding a file, scalar context, path absent
#

$actual = $uut->where($relative_file)

# 'E:\User\SoftwareDiamonds\installation\t\File\Where.pm'
#

##################
# where finding a file, array context, array reference path
#

[@actual = $uut->where($relative_file, [$test_script_dir, $include_dir])]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\t\File\Where.pm',
# 'E:\User\SoftwareDiamonds\installation\t\File',
# 't\File\Where.pm'
# ]
#

##################
# where finding a dir, array context, path absent
#

[@actual = $uut->where($relative_dir1, '', 'nofile')]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File',
# 'E:\User\SoftwareDiamonds\installation',
# 't\File'
# ]
#

##################
# where finding a dir, scalar context, path absent
#

$actual = $uut->where($relative_file, '', 'nofile')

# 'E:\User\SoftwareDiamonds\installation\t\File'
#

##################
# where finding a dir, array context, array reference path
#

[@actual = $uut->where($relative_dir2, \@inc2, 'nofile')]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\t',
# 'E:\User\SoftwareDiamonds\installation\t\File',
# 't'
# ]
#

##################
# where finding a dir, scalar context, array reference path
#

$actual = $uut->where('t', [$test_script_dir,@INC], 'nofile')

# 'E:\User\SoftwareDiamonds\installation\t\File\t'
#

##################
# where_file, array context, path absent
#

[@actual = $uut->where_file($relative_file)]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\Where.pm',
# 'E:\User\SoftwareDiamonds\installation',
# 't\File\Where.pm'
# ]
#

##################
# where_file, scalar context, array path
#

$actual = $uut->where_file($relative_file, $test_script_dir, $include_dir)

# 'E:\User\SoftwareDiamonds\installation\t\File\t\File\Where.pm'
#

##################
# where_dir, array context, array reference
#

[@actual = $uut->where_dir($relative_dir1, \@inc2)]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\t\File',
# 'E:\User\SoftwareDiamonds\installation\t\File',
# 't\File'
# ]
#

##################
# where_dir, array context, array reference
#

[@actual = $uut->where_dir($relative_dir2, $test_script_dir)]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\t',
# 'E:\User\SoftwareDiamonds\installation\t\File',
# 't'
# ]
#

##################
# where_dir, scalar context, path absent
#

$actual = $uut->where_dir($relative_file)

# 'E:\User\SoftwareDiamonds\installation\t\File'
#

##################
# where_pm, array context, path absent
#

[@actual= $uut->where_pm( 't::File::Where' )]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\Where.pm',
# 'E:\User\SoftwareDiamonds\installation',
# 't\File\Where.pm'
# ]
#

##################
# where_pm, scalar context, array path
#

$actual = $uut->where_pm( 't::File::Where', @inc2)

# 'E:\User\SoftwareDiamonds\installation\t\File\t\File\Where.pm'
#

##################
# where_pm, File::Where boundary case
#

$actual = $uut->where_pm( 'File::Where')

# 'E:\User\SoftwareDiamonds\installation\lib\File\Where.pm'
#

##################
# where_pm subroutine, array context, array reference path
#

[@actual= $uut->where_pm( 't::File::Where', [$test_script_dir])]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\t\File\Where.pm',
# 'E:\User\SoftwareDiamonds\installation\t\File',
# 't\File\Where.pm'
# ]
#

##################
# where_repository, array context, path absent
#

[@actual= $uut->where_repository( 't::File' )]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File',
# 'E:\User\SoftwareDiamonds\installation',
# 't\File'
# ]
#

##################
# where_repository, scalar context, array path
#

$actual = $uut->where_repository( 't::File', @inc2)

# 'E:\User\SoftwareDiamonds\installation\t\File\t\File'
#

##################
# where_repository, array context, array reference path
#

[@actual= $uut->where_repository( 't::Jolly_Green_Giant', [$test_script_dir])]

# [
# 'E:\User\SoftwareDiamonds\installation\t\File\t',
# 'E:\User\SoftwareDiamonds\installation\t\File',
# 't'
# ]
#
@INC = @restore_inc; #restore @INC;
rmtree 't';

QUALITY ASSURANCE
Running the test script "Where.t" verifies the requirements for this
module.

The "tmake.pl" cover script for Test::STDmaker automatically generated
the "Where.t" test script, "Where.d" demo script, and "t::Data::Where"
program module POD, from the "t::Data::Where" program module contents.
The "t::Data::Where" program module is in the distribution file
Data-Where-$VERSION.tar.gz.

NOTES
Author

The holder of the copyright and maintainer is

<[email protected]>

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, STD490A 3.2.3.6. In accordance 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 distribution.

SOFTWARE DIAMONDS, http://www.softwarediamonds.com, PROVIDES THIS
SOFTWARE '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::Data_Where
Test::STDmaker
Title Page
Software Version Description

for

File::Where - find the absolute file for a program module; dir for a repository

Revision: D

Version: 0.05

Date: 2004/05/04

Prepared for: General Public

Prepared by: SoftwareDiamonds.com E<lt> [email protected] E<gt>

Copyright: copyright � 2003 Software Diamonds

Classification: NONE

1.0 SCOPE
This paragraph identifies and provides an overview of the released
files.

1.1 Identification

This release, identified in 3.2, is a collection of Perl modules that
extend the capabilities of the Perl language.

1.2 System overview

The system is the Perl programming language software. As established by
the Perl referenced documents, program modules, such the "File::Where"
module, extend the Perl language.

The subroutines in File::Where program module finds the absolute file or
dir for a program module, program module repository, relative file,
relative directory by searching the directories in the @INC array of
directories or an override array of directories. The File::Where program
module supercedes the File::PM2File program module.

1.3 Document overview.

This document releases File::Where version 0.05 providing a description
of the inventory, installation instructions and other information
necessary to utilize and track this release.

3.0 VERSION DESCRIPTION
All file specifications in this SVD use the Unix operating system file
specification.

3.1 Inventory of materials released.

This document releases the file

File-Where-0.05.tar.gz

found at the following repository(s):

http://www.softwarediamonds/packages/
http://www.perl.com/CPAN/authors/id/S/SO/SOFTDIA/

Restrictions regarding duplication and license provisions are as
follows:

Copyright.
copyright � 2003 Software Diamonds

Copyright holder contact.
603 882-0846 E<lt>[email protected]<gt>

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, modified or unmodified 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 distribution.

SOFTWARE DIAMONDS, http://www.SoftwareDiamonds.com, PROVIDES THIS
SOFTWARE '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.

3.2 Inventory of software contents

The content of the released, compressed, archieve file, consists of the
following files:

file version date comment
------------------------------------------------------------ ------- ---------- ------------------------
lib/Docs/Site_SVD/File_Where.pm 0.05 2004/05/04 revised 0.04
MANIFEST 0.05 2004/05/04 generated, replaces 0.04
Makefile.PL 0.05 2004/05/04 generated, replaces 0.04
README 0.05 2004/05/04 generated, replaces 0.04
lib/File/Where.pm 1.16 2004/05/04 revised 1.15
t/File/Where.d 0.04 2004/05/04 revised 0.03
t/File/Where.pm 0.04 2004/05/04 revised 0.03
t/File/Where.t 0.04 2004/05/04 revised 0.03
t/File/_Drivers_/Driver.pm 0.02 2004/05/04 new
t/File/_Drivers_/Generate.pm 0.02 2004/05/04 new
t/File/_Drivers_/IO.pm 0.02 2004/05/04 new
t/File/File/Package.pm 1.16 2004/05/04 revised 1.15
t/File/Test/Tech.pm 1.22 2004/05/04 revised 1.17
t/File/Data/Secs2.pm 1.19 2004/05/04 revised 1.15
t/File/Data/SecsPack.pm 0.04 2004/05/04 new
t/File/Data/Startup.pm 0.04 2004/05/04 new

3.3 Changes

The changes to the previous version are as follows:

File-Where-0.01
Originated.

File-Where-0.02
Added code to where_pm for the boundary case where

where_pm('File::Where') # subroutine interface
'File::Where'->where_pm('File::Where') # class interface

This bug was discovered because the obsoleted File::PM2File module
now uses File::Where for backwards compatibility.

File-Where-0.03
Subject: FAIL Test-Tech-0.18 i586-linux 2.4.22-4tr
From: [email protected]
Date: Thu, 8 Apr 2004 15:09:35 -0300 (ADT)

PERL_DL_NONLAZY=1 /usr/bin/perl5.8.0 "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/Test/Tech/Tech.t
t/Test/Tech/Tech....Can't locate FindBIN.pm

Summary of my perl5 (revision 5.0 version 8 subversion 0) configuration:
Platform:
osname=linux, osvers=2.4.22-4tr, archname=i586-linux

This is capitalization problem. The program module name is 'FindBin'
not 'FindBIN' which is part of Perl. Microsoft does not care about
capitalization differences while linux does. This error is in the
test script automatically generated by "Test::STDmaker" and was just
introduced when moved test script libraries from "tlib" to the
directory of the test script. Repaired "Test::STDmaker" and
regenerated the distribution.

File-Where-0.04
Subject: FAIL File-Where-0.03 ppc-darwin-thread-multi 7.2.0 From:
[email protected] Date: Fri, 9 Apr 2004 21:59:10 +0300 (IDT)

# Test 19 got:
'/private/var/cpanplus/5.8.3/build/File-Where-0.03/blib/lib/File/Whe
re.pm' (t/File/where.t at line 277)

# Expected:
'/private/var/cpanplus/5.8.3/build/File-Where-0.03/lib/File/Where.pm
'

If doing a target site install, the install software going to place
the "blib" directory up front in @INC Changed the file test to
locate the include directory with high probability of having the
first "File::Where" in the include path in determining the expected
value.

Really does not cheapen test by doing a quasi where search where
actual does the same. The object of the test to validate boundary
condition where the class, 'File::Where', is the same as the program
module 'File::Where that the 'where' subroutine/method is locating.
There are plenty of successful test where "where" finds directories
and files as expected.

File-Where-0.05
Rework the POD NOTES and QUALITY ASSURANCE sections.

File-Where-0.06
Added the "is_module", "program_modules", "repository_pms" and
"dir_pms" subroutines.

3.4 Adaptation data.

This installation requires that the installation site has the Perl
programming language installed. There are no other additional
requirements or tailoring needed of configurations files, adaptation
data or other software needed for this installation particular to any
installation site.

3.5 Related documents.

There are no related documents needed for the installation and test of
this release.

3.6 Installation instructions.

Instructions for installation, installation tests and installation
support are as follows:

Installation Instructions.
To installed the release file, use the CPAN module pr PPM module in
the Perl release or the INSTALL.PL script at the following web site:

http://packages.SoftwareDiamonds.com

Follow the instructions for the the chosen installation software.

If all else fails, the file may be manually installed. Enter one of
the following repositories in a web browser:

http://www.softwarediamonds/packages/
http://www.perl.com/CPAN/authors/id/S/SO/SOFTDIA/

Right click on 'File-Where-0.05.tar.gz' and download to a temporary
installation directory. Enter the following where $make is 'nmake'
for microsoft windows; otherwise 'make'.

gunzip File-Where-0.05.tar.gz
tar -xf File-Where-0.05.tar
perl Makefile.PL
$make test
$make install

On Microsoft operating system, nmake, tar, and gunzip must be in the
exeuction path. If tar and gunzip are not install, download and
install unxutils from

http://packages.softwarediamonds.com

Prerequistes.
None.

Security, privacy, or safety precautions.
None.

Installation Tests.
Most Perl installation software will run the following test
script(s) as part of the installation:

t/File/Where.t

Installation support.
If there are installation problems or questions with the
installation contact

603 882-0846 E<lt>[email protected]<gt>

3.7 Possible problems and known errors

There is still much work needed to ensure the quality of this module as
follows:

* State the functional requirements for each method including not only
the GO paths but also what to expect for the NOGO paths

* All the tests are GO path tests. Should add NOGO tests.

4.0 NOTES
The following are useful acronyms:

.d extension for a Perl demo script file

.pm extension for a Perl Library Module

.t extension for a Perl test script file

POD Plain Old Documentation

2.0 SEE ALSO
File::Where
Docs::US_DOD::SVD