# $Id: Module_Template.pm,v 1.2 1999/08/15 15:39:11 jbw Exp $

=head1 NAME

XYZZY - supplies capabilities a, b, and c

=head1 SYNOPSIS

    use XYZZY qw(&func1 $Scalar2 %Hash3);

    $stuff = func1(...);

    %Hash3{'key'} = ... ;

=head1 DESCRIPTION

C<XYZZY> supplies capabilities a, b, and c.  Blah, blah, blah.

Blah, blah, blah.

The functions and methods available work as follows:

=over 4

=cut

# Declare the start of package XYZZY.  The following code is compiled
# and evaluated with XYZZY as the current package.  The file should
# be named "XYZZY.pm".  If, instead of XYZZY, a name like
# ABC::DEF::GHI is used, the file should be named "GHI.pm" and placed
# in directory "DEF" inside "ABC".
package XYZZY;

# Set bits in $ to turn on extra compile-time and run-time checks.
use strict;

# Perform "require Exporter" at compile-time.
# "()" means Exporter's import method is _not_ invoked, which is
# important because that would cause an error.
use Exporter ();

# Allow using these global package variables without including the
# package name.
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);

# Set the version for version checking (RCS/CVS method).
$VERSION = do { my @r = (q$Revision: 1.2 $ =~ /\d+/g); sprintf "%d."."%02d" x $#r, @r }; # must be all one line, for MakeMaker

# We put these in a BEGIN block so they are available within the block
# and for the "use vars" statement which follows.
BEGIN {
    # Cause method invocation to inherit from Exporter if method
    # undefined here.  Make these class methods available:
    #
    #   XYZZY->export
    #   XYZZY->import        (invoked automatically by "use XYZZY")
    #   XYZZY->export_tags
    #   XYZZY->export_ok_tags
    #
    @ISA         = qw(Exporter);

    # The following settings of the EXPORT* variables affect the
    # behavior of the "import" method inherited from Exporter which is
    # automatically invoked by "use".

    # Names (including type prefix character) of entities (i.e.,
    # global variables or functions) which are exported by default.
    @EXPORT = qw(&func1 &func2 $Scalar1 %Hash1);

    # Names of additional entities which are allowed to be exported on
    # request.
    @EXPORT_OK = qw(&func3 &func4 $Scalar2 %Hash2);

    # Groups of entities which can be added or subtracted from an
    # import request list.
    %EXPORT_TAGS = (tag1 => [ qw(&func5 $Array1) ],
                    tag2 => [ qw(&func3 $Scalar2) ]);
    
    # We must make sure that every entity mentioned in %EXPORT_TAGS
    # appears in either @EXPORT or @EXPORT_OK.
    XYZZY->export_tags('tag1');     # add &func5 and $Array1 to @EXPORT
    #XYZZY->export_ok_tags('tag1'); # add &func5 and $Array1 to @EXPORT_OK
}

# Allow using global package variables named in @EXPORT and
# @EXPORT_OK without including the package name. 
# Also allow using functions named in @EXPORT and @EXPORT_OK as list
# operators without parentheses around the arguments. 
# WARNING: this doesn't work for functions which will have prototypes.
# (Note that "use subs 'foo'" does the same as "use vars '&foo'".) 
use vars @EXPORT, @EXPORT_OK;

# give Perl's magic variables readable names.
use English;

# DEFINITIONS GO HERE
# For example:
#
# =item func1 PARAMETER1, PARAMETER12
# 
# Does x, y, and z.
# 
# =cut
# 
# sub func1 {
#     ...
# }

END {
    # Module clean-up code goes here (global destructor on thread exit).
    # Avoid changing $? ($CHILD_ERROR) by accident.
}

# Successful return value to keep "require" happy.
1;

=back

=head1 VERSION

  $Id: Module_Template.pm,v 1.2 1999/08/15 15:39:11 jbw Exp $

=head1 AUTHOR

Joe Wells (F<http://www.cee.hw.ac.uk/~jbw>)

=head1 LICENSE

Copyright Joe Wells, 1999.

You can redistribute and/or modify this software under the terms of
the GNU General Public License as published by the Free Software
Foundation; either version 2, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You may obtain the GNU General Public License by writing to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.

=cut