Perl module Guide (zz)

Document directory

• MySciprt. pl (an example using MyModule)

Zz from http://fanqiang.chinaunix.net/program/perl/2005-06-28/3349.shtml

 

Do you think the module documentation in perl is difficult? Okay, here is the simplest module in the world. It will be used to demonstrate all the features of the (demonstrate) Exporter module. There is also a script for using this module. At the same time, we will also provide a brief description of @ INC. Finally, we will also talk about the use of using warnings and use modules.

The content of this module is as follows:

MyModule. pm

package MyModule;

use strict;
use Exporter;
use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);

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

sub func1  { return reverse @_  }
sub func2  { return map{ uc }@_ }

1;

First, we will get a namespace by declaring the "package" name. This will ensure that the methods and variables in the module are separated from the code that calls them. Use strict is a good practice in the module, which enables Perl to make certain constraints on using global variables. For details, see "use strict warnings and diagnostics or die ".

We need to use the Exporter module to output our functions from MyModule: namespace to main: namespace, so that MyModule programs can use these functions. To use strict, we must use vars to declare some variables. Of course, we can also use our to declare variables in Versions later than 5.6. Now we set a $ VERSION value, and use @ ISA to make the Exporter A Part Of The MyModule. For details about @ ISA and how to use it, see "perlboot ".

@ EXPORT contains the list of functions to be output by default. Here, it is empty. Generally, the less @ EXPROT output by default, the better. Because the program that calls this module may have functions or code that conflict with the functions in the module. If the program needs to call a specified function, make it actively request. @ EXPORT_ OK contains the list of functions to be output during the call. We only output & func1 and & func2. This method takes precedence over the blind use of @ EXPORT to output functions. You can also output global variables such as $ CONFIG, which are not defined by my. (You can refer to "our" or use vars to declare global variables) % EXPORT_TAGS. For convenience, we have defined two sets of output labels. The ': default' tag outputs only the & func1;': Both 'tag, and the & func1 and & func2 tags are output. This hash table stores tags that point to array references. Note: The array here is anonymous. Finally, we need to add a "1;" at the end of the module ;". When perl loads a module, it checks whether the module returns a true value at the end and determines whether the module is successfully loaded. Of course, you can add any true value at the end (see "Code: Police"), but 1 is the most convenient.

MySciprt. pl (an example using MyModule)

#!/usr/bin/perl -w

use strict;

# you may need to set @INC here (see below)

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 qw(&func1);
# 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(:Both);
# print func1(@list),"/n";
# print func2(@list),"/n";

As we can see above, we use MyModule in MyScript. pl. Remove the comments in the middle to see what will happen. Remove all at once. Case1: because our module has no output by default (no output & func1 and & func2), we will get an error that does not exist in main: namespace. Case2: this operation is normal. We let the module output & func1, so we can use it normally. Although we have not output & func2, we use the complete & func2 package path, so it can also work properly. Case3: ': default' label should output & func1, so you should expect an error Missing & func2 function to be returned. But in fact perl has to find the trouble of & func1 (the error message prompts undefined & func1 function ). Well, what happened here? Originally, the DEFAULT label name is special. In our module, the % EXPORT_TAGS hash table will be automatically set to this DEFAULT =>/@ EXPROT. that is to say, DEFAULT exports the functions from the @ EXPROT array by DEFAULT. Case4: we specify to use the ': Both' label to implement the output of Both functions. * Notes about @ INC * when you submit a use MyModule, it instructs perl to search for the module name in the @ INC array. @ INC usually includes:

/perl/lib 
/perl/site/lib
.

"." Indicates the current working directory. The core module is installed in the perl/lib directory, and the non-core module is installed in the perl/site/lib directory. You can add a custom directory to @ INC. As shown below:

BEGIN { push @INC, '/my/dir' }
# or
BEGIN { unshift @INC, '/my/dir' }
# or
use lib '/my/dir';

We need to use the BEGIN block to add value to @ INC during compilation. This is the time when the perl check module is used.

If you wait until the program is compiled too late, perl will throw an exception saying "MyModule cannot be found in @ INC ". the difference between using the push or unshift method to add values is that the perl search @ INC sequence starts from the first directory in @ INC. If you have a MyModule in/perl/lib/,/perl/site/lib/, and./, the modules in/perl/lib will be first found and used. Use lib usage can play the same effect as BEGIN {unshift @ INC, $ dir}-see "perlman: lib": http://www.perlmonks.org /? Node = perlman % 3 Alib % 3 Alib. * use Foo: What does Bar mean? * use Foo: Bar does not mean to find a file named Foo: Bar in the @ INC directory. pm module File. It means to find a "sub-directory" named 'foo' in the @ INC directory, and then find a "module" named "Bar. pm" in it ". Now, if we have successfully "use" a module, we can use all the functions in this module through the complete PACKAGE path syntax & PACKAGE: FUNCTION. When we say & Foo: Bar: some_func, we mean "package name" instead of the file name that contains the path used in use. This allows you to include many package names in a file that has been used. In actual use, these names are usually the same.

Use warnings;

You should open warnings to detect your module, because it can detect many minor errors. You can enable the warning option by adding the-w parameter to the test module code. If you have added use warnings to the module, your module must be running at perl5.6 or later. Otherwise, it is not supported. If you add $ ^ W ++ at the top of the module, you will enable the warning option globally-this will affect other modules, you 'd better use it only in your own program, because it is somewhat overbearing. This has an expert written called "tye": http://www.perlmonks.org /? Node = tye code to test the warning option, but it is not directly included in his/her own modules. I hope this will tell you how it works. Tachyon