Remove unnecessary cruft from the module example.
authorMichael G. Schwern <schwern@pobox.com>
Sun, 23 Oct 2011 02:32:04 +0000 (19:32 -0700)
committerTony Cook <tony@develop-help.com>
Sat, 29 Oct 2011 03:20:44 +0000 (14:20 +1100)
This makes it more like a real module would be written while retaining it's utility as a teaching boilerplate.

* require Exporter instead of use with no import
* Declare and initialize variables together.
* Eliminate archaic RCS/CVS versioning clutter.
* Explain what @ISA does.
* Remove archaic (and slower) &func syntax from exporting
* Remove %EXPORT_TAGS.  It's not explained and rarely used.
* Remove redundant @EXPORT_OK
* Use cleaner $priv_func->() syntax rather than &$priv_func.
* Eliminate prototypes, they're clutter, rarely used and dangerous.

TonyC: update known_pod_issues.dat

pod/perlmod.pod
t/porting/known_pod_issues.dat

index 336b99c..33f098d 100644 (file)
@@ -404,65 +404,50 @@ create a file called F<Some/Module.pm> and start with this template:
     use warnings;
 
     BEGIN {
-        use Exporter   ();
-        our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
+        require Exporter;
 
         # set the version for version checking
-        $VERSION     = 1.00;
-        # if using RCS/CVS, this may be preferred
-        $VERSION = sprintf "%d.%03d", q$Revision: 1.1 $ =~ /(\d+)/g;
+        our $VERSION     = 1.00;
 
-        @ISA         = qw(Exporter);
-        @EXPORT      = qw(&func1 &func2 &func4);
-        %EXPORT_TAGS = ( );     # eg: TAG => [ qw!name1 name2! ],
+        # Inherit from Exporter to export functions and variables
+        our @ISA         = qw(Exporter);
 
-        # your exported package globals go here,
-        # as well as any optionally exported functions
-        @EXPORT_OK   = qw($Var1 %Hashit &func3);
+        # Functions and variables which are exported by default
+        our @EXPORT      = qw(func1 func2);
+
+        # Functions and variables which can be optionally exported
+        our @EXPORT_OK   = qw($Var1 %Hashit func3);
     }
-    our @EXPORT_OK;
 
     # exported package globals go here
-    our $Var1;
-    our %Hashit;
+    our $Var1    = '';
+    our %Hashit  = ();
 
     # non-exported package globals go here
-    our @more;
-    our $stuff;
-
-    # initialize package globals, first exported ones
-    $Var1   = '';
-    %Hashit = ();
-
-    # then the others (which are still accessible as $Some::Module::stuff)
-    $stuff  = '';
-    @more   = ();
+    # (they are still accessible as $Some::Module::stuff)
+    our @more    = ();
+    our $stuff   = '';
 
-    # all file-scoped lexicals must be created before
-    # the functions below that use them.
-
-    # file-private lexicals go here
+    # file-private lexicals go here, before any functions which use them
     my $priv_var    = '';
     my %secret_hash = ();
 
     # here's a file-private function as a closure,
-    # callable as &$priv_func;  it cannot be prototyped.
+    # callable as $priv_func->();
     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
+    sub func1      { ... }
+    sub func2      { ... }
 
-    END { }       # module clean-up code here (global destructor)
+    # this one isn't exported, but could be called directly
+    # as Some::Module::func3()
+    sub func3      { ... }
 
-    ## YOUR CODE GOES HERE
+    END { ... }       # module clean-up code here (global destructor)
 
     1;  # don't forget to return a true value from the file
 
index 4c42a46..0ee1c43 100644 (file)
@@ -235,7 +235,7 @@ pod/perlirix.pod    Verbatim line length including indents exceeds 79 by    4
 pod/perllocale.pod     Verbatim line length including indents exceeds 79 by    4
 pod/perllol.pod        Verbatim line length including indents exceeds 79 by    4
 pod/perlmacosx.pod     Verbatim line length including indents exceeds 79 by    3
-pod/perlmod.pod        Verbatim line length including indents exceeds 79 by    3
+pod/perlmod.pod        Verbatim line length including indents exceeds 79 by    2
 pod/perlmodlib.pod     Verbatim line length including indents exceeds 79 by    3
 pod/perlmodstyle.pod   Verbatim line length including indents exceeds 79 by    2
 pod/perlmpeix.pod      Verbatim line length including indents exceeds 79 by    2