Improve sample module header

Subject: Re: addition to perlmod and perlfaq?

Here's the "final" version.  Larry and I have to
head off to a book signing now.  Chip, please have
this replace the old stuff I have in L<perlmod/"Perl Modules">
that begins with ``package Fred;''.

p5p-msgid: 199703011732.KAA14693@jhereg.perl.com
Signed-off-by: Graham Barr <gbarr@ti.com>

diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index 9b649d6..5623631 100644 (file)
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -225,14 +225,63 @@ symbols.  Or it can do a little of both.
 For example, to start a normal module called Fred, create
 a file called Fred.pm and put this at the start of it:
 
-    package      Fred;
-    use          strict;
-    use          Exporter ();
-    use          vars qw(@ISA @EXPORT @EXPORT_OK);
-    @ISA       = qw(Exporter);
-    @EXPORT    = qw(&func1 &func2);
-    @EXPORT_OK = qw($sally @listabob %harry &func3);
-    use                 vars qw($sally @listabob %harry);
+    package Some::Module;  # assumes Some/Module.pm
+
+    use strict;
+
+    BEGIN {
+        use Exporter   ();
+        use vars       qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
+
+        # set the version for version checking
+        $VERSION     = 1.00;
+        # if using RCS/CVS, this may be preferred
+        $VERSION = (qw$Revision: 1.00 $)[1];
+
+        @ISA         = qw(Exporter);
+        @EXPORT      = qw(&func1 &func2 &func4);
+        %EXPORT_TAGS = ( );     # eg: TAG => [ qw!name1 name2! ],
+
+        # your exported package globals go here,
+        # as well as any optionally exported functions
+        @EXPORT_OK   = qw($Var1 %Hashit &func3);
+    }
+    use vars      @EXPORT_OK;
+
+    # non-exported package globals go here
+    use vars      qw( @more $stuff );
+
+    # initalize package globals, first exported ones
+    $Var1   = '';
+    %Hashit = ();
+
+    # then the others (which are still accessible as $Some::Module::stuff)
+    $stuff  = ''  
+    @more   = ();
+
+    # all file-scoped lexicals must be created before
+    # the functions below that use them.
+
+    # file-private lexicals go here
+    my $priv_var    = ''; 
+    my %secret_hash = ();
+
+    # here's a file-private function as a closure,
+    # callable as &$priv_func;  it cannot be prototyped.
+    my $priv_func = sub {
+        # stuff goes here.
+    };
+        
+    # make all your functions, whether exported or not;
+    # remember to put something interesting in the {} stubs
+    sub func1      {}    # no prototype
+    sub func2()    {}    # proto'd void 
+    sub func3($$)  {}    # proto'd to 2 scalars
+
+    # this one isn't exported, but could be called!
+    sub func4(\%)  {}    # proto'd to 1 hash ref
+
+    END { }       # module clean-up code here (global destructor)
 
 Then go on to declare and use your variables in functions
 without any qualifications.