Re: Module Submission for CPAN

[chipmunk]

Here's what I like to see in a module on CPAN:

• An easy installation procedure, preferably the standard `perl Makefile.pl; make; make test; make install`. make test should test the features of the module.
• Documentation, including a README file and standard POD in the module itself.
• Configurability, as appropriate. Your module, for example, depends on /usr/dict/words. The person using your module may need to or want to specify an alternate file to use. (*)

One comment specifically about your module... I notice that you set @Anagram::EXPORT, but you don't have an import() sub. You might want to change @EXPORT to @EXPORT_OK and inherit Exporter's import() method.

(*) On some systems, /usr/dict/words includes Unix terms and includes only root forms of regular words, which is not good for word puzzles.

[tedv]

To be honest, I don't understand a lot of how module exporting and importing works-- I just know use and require. Is there a brief tutorial on this exporting stuff, or is it explainable in a paragraph or so? I've read through the Camel Book's section on exporting, but I just got a syntatical feel, not a feel for the purpose behind it or how it's best used.

-Ted

[chipmunk]

Here's a quick, off-the-cuff explanation of exporting/importing:

First, exporting and importing are the same thing; like emigrating/immigrating, it just depends which side you're looking from. :)

Exporting/importing is simply the process of making a link from a symbol (or part of a symbol) in one package to a symbol in another package, so that the symbol can be accessed from either package. For example, if you import CPAN's install method, then CPAN exports it (by using Exporter) with this assignment: (*{"${callpkg}::$sym"} = \&{"${pkg}::$sym"}. That actually makes an assignment to the symbol table for the calling package. Assuming $callpkg is main, now main::install and CPAN::install refer to the same subroutine. The \& on the RHS of the assignment means that only the subroutine part of the CPAN::install symbol was duplicated; the scalar, array, hash, and other parts were not. Exporter does separate assignments for each data type, so that only what was asked for is imported.

The reason for exporting/importing is simply to make accessing symbols in other packages easier, by bringing them into your package. Someone using the functional interface to CGI, for example, would have to write out CGI::header(), CGI::start_html(), CGI::param(), etc., for every function, if they couldn't import the methods.

[cwest]

Read the Exporter manpage... here's a simple example:

package Ctweten::Export;

use Exporter;
our @ISA = qw(Exporter); # we now inherit from Exporter, namely the im
+port() method

our @EXPORT_OK = qw(this that); # you must ask for these: use Ctweten:
+:Export 'this';
our @EXPORT    = qw(other); # exporter by default

sub this { print "Hello\n" }
*that = *other = *this;

In a program, if you want to use this() and other(), you do the following: <code> #!/usr/local/bin/perl -w use strict; $|++; use Ctweten::Export qw(this); other; this; that; # this would die under these circumstances.

--
Casey
   I am a superhero.