How to make a module which exports a function, takes a list and returns a list?

[luma]

as a network administrator i decided this week that it's about time that i quit playing with dos batch files, step up to the plate, and learn a Real Language. also, i find perl a fabulous way to piss away time programmatically organizing my mp3 collection at work while making it look like i'm doing something deep and profound. so here's the rank newbie ?:

how the heck do i make a module that exports one function, which accepts a list and returns a new list? i've purchased the o'reilly collection and have digging through it for answers to this simple question. i'm feeling kinda silly that every time i try to make a module i get a screen full of run time compile errors.

what would be really great would be a nice generic template of a .pm (i know where to put them) that can export a single function (prototype sub myfunc (@)) that returns a @list. any help?

i might add newbie ? #2 - is there a better place for such basic questions than the front of perlmonks.org, so the true shaolin perl monks out there won't have to waste their time on such shallow magic?

luma::s-video

Edit kudra, 2001-08-06 Changed title

[snowcrash]

A few places to find more information:
• How do I create a module
• The perlmod manpage
• the Exporter manpage for exporting subroutings or variables
Further, using the search on top left of the page, or the far more powerful Super Search hidden in the navigation to the right will bring up plenty of nodes that might help you.


snowcrash //////

[tachyon]

Ok here is the world's simplest Perl module domonstrating all the salient features of exporter.

# I am a very simple module
package MyModule;
use warnings;
use Exporter;

our $VERSION     = 1.00;
our @ISA         = qw(Exporter);
our @EXPORT      = qw(&func1);
our @EXPORT_OK   = qw(&func2);
our %EXPORT_TAGS = (DEFAULT => [qw(&func1)], ALL => [qw(&func1 &func2)
+]);

sub func1  {return reverse @_}

sub func2  {return @_}

1;

# here is a very simple script to use this module

#!/use/bin/perl -w
use strict;

my @list = qw (J u s t ~ A n o t h e r ~ P e r l ~ H a c k e r !);

# case 1
# use MyModule;
# print func1(@list),"\n";
# print func2(@list),"\n";

# case 2
# use MyModule;
# print func1(@list),"\n";
# print MyModule::func2(@list),"\n";

# case 3
# use MyModule qw(:DEFAULT);
# print func1(@list),"\n";
# print func2(@list),"\n";

# case 4
# use MyModule qw(:ALL);
# print func1(@list),"\n";
# print func2(@list),"\n";

We build our module as shown. It exports &func1 by default. It exports &funct2 only is specifically requiested to. It defines two sets of tags. The ':DEFAULT' tag exports only &func1; the ':ALL' tag exports all the functions - all two of them!. We use it as shown. Uncomment the examples to see what happens. In case 1 we get an error as &funct2 has not been exported thus does not exist. In case 2 we are OK as although &func2 was not exported we reference it with its full package name. Case 3 is the same as case 1 as the :DEFAULT tag only exports &func1. Case 4 uses the :ALL tag to export all the functions we defined in the EXPORT_TAGS => ALL so &func1 and &func2 are exported and thus this works.

Note the use statement refers to a *file* that ends with .pm. When we say &MyModule::func2 we are refering to the *package name* not the file name that we used in the use. This allows you to have many package names in one used file. In practice the names are usually the same.

Hope this explains how it works.

cheers

tachyon

s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print

[luma]

argh!!! this thing is driving me nuts. ok, i copy and paste the module and test code as listed. my results are exactly the same as what i was getting before - "Undefined subroutine &main::func1 called at..."

if i inject an error into the module itself, i get errors back which tells me it's finding the module.

what could i be missing here?

luma::s-video

[luma]

perhaps my actual example might help:

package ParseFiles;

#use strict;
use vars qw(@ISA @EXPORT $VERSION);

use Exporter;

$VERSION = 0.01;
@ISA = qw(Exporter);
@EXPORT = qw(&wad_parsefiles);
$VERSION = 0.01;

sub wad_parsefiles (@);



###################################################
# sub parsefiles - args (@file list) return (@expanded file list)
# take a list of filename arguments and expand it to a full
# list, with wildcards globbed and @filelists opened
# and included
sub wad_parsefiles {
    my ($filespec, @files, @readfile);
    foreach $filespec (@_) {

    # convert drive:\dir\file to drive:\\dir\\file to make perl happy
    $filespec =~ s/\\/\\\\/g;

    # check if arg begins w/ "@", treat as list if so
    if ( $filespec =~ /^@/ ) {
        # remove leading @
        $filespec =~ s/^@//;
        # open the list and dump contents into @files
        if (open(FILELIST, "$filespec")){
          @readfile = <FILELIST>;
          chomp(@readfile);
          close(FILELIST);
          @files = (@files, @readfile);
        }
    }
      # glob it?
      elsif ( $filespec =~ /\*/ || $filespec =~ /\?/ ) {
          @files = (@files, glob("$filespec"));
        }
        else {
            @files = (@files, "$filespec");  
      }
    }
    return @files;
}

first: apologies for sloppy syntax, i'm trying to get this thing to work at all before i clean up the mess. variable declarations and their ilk have been changed many times just trying to get this to run, so it might look weird in it's current state.

second: what i'd like to do here is to have this function to see a list of file specs (as provided on the cmd line or wherever), to expand that list with globbing and what have you, and than present the list to whomever calls this function. i'd really like it to be totally private outside of the function itself so i don't kill myself in namespace land. any thoughts on what's here? any idea what the heck i'm doing wrong?

luma::s-video

[Zaxo]

"what would be really great would be a nice generic template of a .pm (i know where to put them) that can export a single function (prototype sub myfunc (@)) that returns a @list. any help?"

h2xs produces a skeleton source tree with CPAN/MakeMaker style build magic, testsuite, and modules. Both the Cookbook and the Camel cover h2xs enough to get you started. It is heavyweight for for the kind of exercise you're talking about, but you might like it anyway.

Btw, for the filename globbing function you present in your followup, you might want to look at the diamond operator <> with glob arguments.

After Compline,
Zaxo

[Wookie]

If you're having trouble with module logic - there is a pretty straight forward way to import subs without making it a module.

If you create a file containing your sub-routine (say called mysub.pl) something like:

#!/usr/bin/perl -w

sub my_sub {
    code.....
}

1;

Then in your program simply:

require mysub.pl;

that will include that sub in that program for you.

I don't know whether this is the most efficent way to do it - and you do lose the ability to hide variables etc. - but it is probably worth a try :).

---

game(Wookie,opponent) eq 'Wookie' ? undef $problem : remove_limbs(arms,opponent);