##########################################################################
# An erupd perl style: 
#
#  1) File names should be the same as the corresponding module name.
#  2) The module/file name should be lower case words starting with 
#     updxyz (where xyz is an module indentifier), like: 'updlcl'
#  3) All files should have a header with entries: FILE, DESCRIPTION,
#     AUTHORS and MODIFICATIONS (see below).
#  4) Exported functions and variables from a module updxyz, should be 
#     all lowercase word starting with updxyz_, like: 'updlcl_find'
#  5) All functions should have a header with entries: name,
#     description, input, output, return (see below).
#  6) All files should have a 'pod' section (see bottom), where the
#     documentations are structures as a man page.
#  7) Constants (or variables used as constants) should be all uppercase,
#     where words are separated by underscore, like '$THIS_IS_A_CONSTANT'.
#  8) Variables at file scope (global variables (and variables declared
#     'local') should start with a 'g_'.
#  9) Private functions and variables at functions scope should just
#     be all lower case.
# 10) 'use strict', will catch a lot of typos.
# 11) use 'my' (or 'local') for not exported variables (most of the time
#     you mean 'my')

##########################################################################
#
# FILE:
#       updxyz.pm
# 
# DESCRIPTION: 
#       Will shave the world.
#       (for more info, see pod at the end).
#
# AUTHORS:
#       Mark Mengel
#       Lars Rasmussen
#       Margaret Votava
#       Don Walsh
#
#       Fermilab Computing Division
#       Batavia, Il 60510, U.S.A.                                              
#
# MODIFICATIONS:
#       23-Jun-1997, dw, first
#       24-Jun-1997, mv, second
#       25-Jun-1997, lr, third
#       26-Jun-1997, mm, fourth
#
##########################################################################
package updxyz;

use strict;
use Exporter();
use vars qw( @ISA @EXPORT
	     %updxyz_shaved_whales
	   );
@ISA = qw(Exporter);

# export this !
@EXPORT = qw (
	      updxyz_shave_world
	      updxyz_shave_whale

	      %updxyz_shaved_whales
	      );

##########################################################################
# Exported variables
#
%updxyz_shaved_whales = ();

##########################################################################
# Global and local variables
#
use vars qw(
	    $g_world_name
	    $g_first_whale
	    $g_next_whale
	   );

my $g_world_name = '';

##########################################################################
# Exported functions
#

#-------------------------------------------------------------------------
# $bool = updxyz_shave_world( $name_of_world )
#
# Will shave the world.
#
# Input : name of world
# Output: 
# Return: 1 if anything was shaved, else 0
#
sub updxyz_shave_world
{
    $g_world_name = shift;
    
    local $g_first_whale = 'Hans';
    local $g_next_whale = '';

    my $count = 0;
    while ( ($g_next_whale = next_whale()) ) {
	if ( shave_whale( $g_next_whale ) ) {
	    $count++;
	    $updxyz_shaved_whales{$g_next_whale} = 1;
	}
    }

    return $count;
}

#-------------------------------------------------------------------------
# $bool = updxyz_shave_whale( $name_of_whale )
#
# Will shave a single whale.
#
# Input : name of whale
# Output: 
# Return: 1 if whale was shaved, else 0
#
sub updxyz_shave_whale
{
    my $name = shift;

    # will be implemented later.

    return 1;
}

##########################################################################
# Private functions
#

#-------------------------------------------------------------------------
# $next_whale = next_whale( $current_whale )
#
# Will find next whale.
#
# Input : name of current whale
# Output: 
# Return: next whale found or ''
#
sub next_whale
{
    my $current = shift;

    $g_next_whale = go_fishing( $current );
    return $g_next_whale;
}

1;

__END__

=head1 NAME

updxyz.pm - will shave the world.

=head1 SYNOPSIS

use updxyz - use it as a module.

=head1 DESCRIPTION

updxyz will shave all whales in the world.

=head2 Interface

=item updxyz_shave_world( $name_of_world )

=item updxyz_shave_whale( $name_of_whale )

=item %updxyz_shaved_whales will contain hash table of shaved whales,
    hash key is the name of the whale.

=head1 BUGS

It does not work as expected.

=cut
