#!/usr/bin/perl

=pod

=head1	NAME

B<File_Exists>

Repeated tests if a file exists.

=head1	SYNOPSIS

File_Exists E<lt>B<pathname>E<gt>
[-Repeat E<lt>B<tries>E<gt>] [-Delay E<lt>B<seconds>E<gt>] [-Help]

=head1	DESCRIPTION

The pathname is tested to see if a file exits at that location. If it
does the procedure exits with a success status. Otherwise the procedure
sleeps for the number of delay seconds and repeats the test. This
continues for up to the number of repeat tries or until the test
succeeds. If the test never succeeds the procedure exits with a failure
status.

=head1	OPTIONS AND ARGUMENTS

One pathname must be provided to test.

=over

=item	-Repeat E<lt>B<tries>E<gt>

The number of times to repeat the test for the existence of the file
before giving up. The minimum number of repeat tries is 0; i.e. only
test once and do not repeat the test. The default is 12 tries.

=item	-Delay E<lt>B<seconds>E<gt>

The number of seconds to delay between repeat tries. The default is 10
seconds. The minimum delay is 1 second and the maximum is 60 seconds.

=item	-Help

The man page for this procedure is listed.

=back

=head1	Exit Status

=over

=item	E<48> - Success

A file was found to exist at the pathname.

=item	E<49> - Bad command line syntax

A command line syntax usage message will be provided.

=item	E<50> - No such file

No file was found to exist at the pathname.

=back

=head1	Author

Bradford Castalia, UA/PIRL

=head1	Copyright

Copyright (C) 2009-2012 Arizona Board of Regents on behalf of the
Planetary Image Research Laboratory, Lunar and Planetary Laboratory at
the University of Arizona.

This file is part of the PIRL Java Packages.

The PIRL Java Packages are free software; you can redistribute them
and/or modify them under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.

The PIRL Java Packages are distributed in the hope that they will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

=head1	Version

2.4 2012/04/16 06:04:10

=cut

#	CVS ID: File_Exists,v 2.4 2012/04/16 06:04:10 castalia Exp
#===============================================================================
$CVS_ID = 'Pipeline_Source (2.4 2012/04/16 06:04:10)';

($Command_Name = $0) =~ s|.*/(\S+)$|$1|;
print "$Command_Name - $CVS_ID\n";

#	Defaults:

$Tries		= 12;
$Delay		= 10;
$MAX_DELAY	= 60;

#	Exit status values:
$SUCCESS			= 0;
$BAD_SYNTAX			= 1;
$NO_SUCH_FILE		= 2;

use File::Spec;

#-------------------------------------------------------------------------------
#	Command line arguments:

use Pod::Usage;

pod2usage
	(
	-verbose => 0,
	-exitval => $BAD_SYNTAX
	)
	unless @ARGV;

while ($option = shift @ARGV)
	{
	if ($option =~ /^-[Rr]/)
		{
		pod2usage
			(
			-message => "$Command_Name: Missing repeat tries.\n",
			-verbose => 0,
			-exitval => $BAD_SYNTAX
			)
			unless (@ARGV && $ARGV[0] !~ /^-/);
		$Tries = shift @ARGV;
		pod2usage
			(
			-message => "$Command_Name: The repeat tries \"$Tries\" is not a number.\n",
			-verbose => 0,
			-exitval => $BAD_SYNTAX
			)
			if ($Tries =~ /\D/);
		$Tries = 0
			if ($Tries < 0);
		next;
		}
	if ($option =~ /^-[Dd]/)
		{
		pod2usage
			(
			-message => "$Command_Name: Missing delay seconds.\n",
			-verbose => 0,
			-exitval => $BAD_SYNTAX
			)
			unless (@ARGV && $ARGV[0] !~ /^-/);
		$Delay = shift @ARGV;
		pod2usage
			(
			-message => "$Command_Name: The delay seconds \"$Delay\" is not a number.\n",
			-verbose => 0,
			-exitval => $BAD_SYNTAX
			)
			if ($Delay =~ /\D/);
		$Delay = 1
			if ($Delay <= 0);
		$Delay = $MAX_DELAY
			if ($Delay > $MAX_DELAY);
		next;
		}

	#	Help.
	pod2usage
		(
		-verbose => 2,
		-exitval => $SUCCESS
		)
		if ($option =~ /^-[Hh]/);

	pod2usage
		(
		-message => "$Command_Name: Unknown option \"$option\"\n",
		-verbose => 0,
		-exitval => $BAD_SYNTAX
		)
		if ($option =~ /^-/);

	pod2usage
		(
		-message => "$Command_Name: Multiple pathnames specified - \n"
						."$Pathname\n"
						."and\n"
						."$option",
		-verbose => 0,
		-exitval => $BAD_SYNTAX
		)
		if ($Pathname && $Pathname ne $option);
	$Pathname = $option;
	}

pod2usage
	(
	-message => "$Command_Name: No pathname specified.\n",
	-verbose => 0,
	-exitval => $BAD_SYNTAX
	)
	unless $Pathname;

#	Ensure absolute pathname.
$Pathname = File::Spec->rel2abs ($Pathname);

do
	{
	if (-e "$Pathname")
		{
		print "A file exists at the $Pathname pathname.\n";
		exit ($SUCCESS);
		}
	sleep ($Delay);
	}
	while ($Tries--);

print "No file found at the $Pathname pathname.\n";
exit ($NO_SUCH_FILE);
