ch12_01.htm

By Tom Christiansen and Nathan Torkington ISBN 1-56592-243-3 First Edition, published August 1998

></A
></PRE
></DIV
><DIV
CLASS="sect2"
><H3
CLASS="sect2"
><A
CLASS="title"
NAME="ch12-chap12_import_export_0"
>Import/Export Regulations</A
></H3
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="ch12-idx-1000005134-0"
></A
>The following is a typical setup for a hypothetical module named Cards::Poker that demonstrates how to manage its exports. The code goes in the file named <EM
CLASS="emphasis"
>Poker.pm</EM
> within the directory <EM
CLASS="emphasis"
>Cards</EM
>: that is, <EM
CLASS="emphasis"
>Cards/Poker.pm</EM
>. (See <A
CLASS="xref"
HREF="ch12_08.htm"
TITLE="Keeping Your Own Module Directory"
>Recipe 12.7</A
> for where the <EM
CLASS="emphasis"
>Cards</EM
> directory should reside.) Here's that file, with line numbers included for reference:</P
><PRE
CLASS="programlisting"
>1    package Cards::Poker;
2    use Exporter;
3    @ISA = ('Exporter');
4    @EXPORT = qw(&amp;shuffle @card_deck);
5    @card_deck = ();                       # initialize package global
6    sub shuffle { }                        # fill-in definition later
7    1;                                     # don't forget this</PRE
><P
CLASS="para"
>Line 1 declares the package that the module will put its global variables and functions in. Typically, a module first switches to a particular package so that it has its own place for global variables and functions, one that won't conflict with that of another program. This <EM
CLASS="emphasis"
>must</EM
> be written exactly as the corresponding <CODE
CLASS="literal"
>use</CODE
> statement will be written when the module is loaded.</P
><P
CLASS="para"
>Don't say <CODE
CLASS="literal"
>package</CODE
> <CODE
CLASS="literal"
>Poker</CODE
> just because the basename of your file is <EM
CLASS="emphasis"
>Poker.pm</EM
>. Rather, say <CODE
CLASS="literal"
>package</CODE
> <CODE
CLASS="literal"
>Cards::Poker</CODE
> because your users will say <CODE
CLASS="literal"
>use</CODE
> <CODE
CLASS="literal"
>Cards::Poker</CODE
>. This common problem is hard to debug. If you don't make the <CODE
CLASS="literal"
>package</CODE
> and <CODE
CLASS="literal"
>use</CODE
> statements exactly the same, you won't see a problem until you try to call imported functions or access imported variables, which will be mysteriously missing.</P
><P
CLASS="para"
>Line 2 loads in the <A
CLASS="indexterm"
NAME="ch12-idx-1000005150-0"
></A
>Exporter module, which manages your module's public interface as described below. Line 3 initializes the special, per-package array <CODE
CLASS="literal"
>@ISA</CODE
> to contain the word <CODE
CLASS="literal"
>&quot;Exporter&quot;</CODE
>. When a user says <CODE
CLASS="literal"
>use</CODE
> <CODE
CLASS="literal"
>Cards::Poker</CODE
>, Perl implicitly calls a special method, <CODE
CLASS="literal"
>Cards::Poker-&gt;import()</CODE
>. You don't have an <CODE
CLASS="literal"
>import</CODE
> method in your package, but that's OK, because the Exporter package does, and you're <EM
CLASS="emphasis"
>inheriting</EM
> from it because of the assignment to <CODE
CLASS="literal"
>@ISA</CODE
> (<EM
CLASS="emphasis"
>is a</EM
>). Perl looks at the package's <CODE
CLASS="literal"
>@ISA</CODE
> for resolution of undefined methods. Inheritance is a topic of <A
CLASS="xref"
HREF="ch13_01.htm"
TITLE="Classes, Objects, and Ties"
>Chapter 13, <CITE
CLASS="chapter"
>Classes, Objects, and Ties</CITE
></A
>. You may ignore it for now &nbsp;-  so long as you put code as shown in lines 2 and 3 into each module you write.</P
><P
CLASS="para"
>Line 4 assigns the list <CODE
CLASS="literal"
>('&amp;shuffle',</CODE
> <CODE
CLASS="literal"
>'@card_deck')</CODE
> to the special, per-package array <CODE
CLASS="literal"
>@EXPORT</CODE
>. When someone imports this module, variables and functions listed in that array are aliased into the caller's own package. That way they don't have to call the function <CODE
CLASS="literal"
>Poker::Deck::shuffle(23)</CODE
> after the import. They can just write <CODE
CLASS="literal"
>shuffle(23)</CODE
> instead. This won't happen if they load Cards::Poker with <CODE
CLASS="literal"
>require</CODE
> <CODE
CLASS="literal"
>Cards::Poker</CODE
>; only a <CODE
CLASS="literal"
>use</CODE
> imports.</P
><P
CLASS="para"
>Lines 5 and 6 set up the package global variables and functions to be exported. (We presume you'll actually flesh out their initializations and definitions more than in these examples.) You're free to add other variables and functions to your module as well, including ones you don't put in the public interface via <CODE
CLASS="literal"
>@EXPORT</CODE
>. See <A
CLASS="xref"
HREF="ch12_02.htm"
TITLE="Defining a Module's Interface"
>Recipe 12.1</A
> for more about using the Exporter.</P
><P
CLASS="para"
>Finally, line 7 is a simple <CODE
CLASS="literal"
>1</CODE
>, indicating the overall return value of the module. If the last evaluated expression in the module doesn't produce a true value, an exception will be raised. Trapping this is the topic of <A
CLASS="xref"
HREF="ch12_03.htm"
TITLE="Trapping Errors in require or use"
>Recipe 12.2</A
>. Any old true value will do, like 6.02e23 or <CODE
CLASS="literal"
>&quot;Because</CODE
> <CODE
CLASS="literal"
>tchrist</CODE
> <CODE
CLASS="literal"
>and</CODE
> <CODE
CLASS="literal"
>gnat</CODE
> <CODE
CLASS="literal"
>told</CODE
> <CODE
CLASS="literal"
>us</CODE
> <CODE
CLASS="literal"
>to</CODE
> <CODE
CLASS="literal"
>put</CODE
> <CODE
CLASS="literal"
>this</CODE
> <CODE
CLASS="literal"
>here&quot;</CODE
>; however, <CODE
CLASS="literal"
>1</CODE
> is the canonical true value used by almost every module.</P
><P
CLASS="para"
>Packages group and organize global identifiers. They have nothing to do with privacy. Code compiled in package <CODE
CLASS="literal"
>Church</CODE
> can freely examine and alter variables in package <CODE
CLASS="literal"
>State</CODE
>. Package variables are always global and are used for sharing. But that's okay, because a module is more than just a package; it's also a file, and files count as their own scope. So if you want privacy, use lexical variables instead of globals. This is the topic of <A
CLASS="xref"
HREF="ch12_05.htm"
TITLE="Making Variables Private to a Module"
>Recipe 12.4</A
>.<A
CLASS="indexterm"
NAME="ch12-idx-1000005135-0"
></A
><A
CLASS="indexterm"
NAME="ch12-idx-1000005135-1"
></A
></P
></DIV
><DIV
CLASS="sect2"
><H3
CLASS="sect2"
><A
CLASS="title"
NAME="ch12-chap12_other_0"
>Other Kinds of Library Files</A
></H3
><P
CLASS="para"
><A
CLASS="indexterm"
NAME="ch12-idx-1000005136-0"
></A
>A library is a collection of loosely related functions designed to be used by other programs. It lacks the rigorous semantics of a Perl module. The file extension <CODE
CLASS="literal"
>.pl</CODE
> indicates that it's a Perl library file. Examples include <EM
CLASS="emphasis"
>syslog.pl</EM
> and <EM
CLASS="emphasis"
>chat2.pl</EM
>.</P
><P
CLASS="para"
>Perl libraries &nbsp;-  or in fact, any arbitrary file with Perl code in it &nbsp;-  can be loaded in using <CODE
CLASS="literal"
>do</CODE
> <CODE
CLASS="literal"
>'file.pl'</CODE
> or with <CODE
CLASS="literal"
>require</CODE
> <CODE
CLASS="literal"
>'file.pl'</CODE
>. The latter is preferred in most situations, because unlike <CODE
CLASS="literal"
>do</CODE
>, <CODE
CLASS="literal"
>require</CODE
> does implicit error checking. It raises an exception if the file can't be found in your <CODE
CLASS="literal"
>@INC</CODE
> path, doesn't compile, or if it doesn't return a true value when any initialization code is run. (The last part is what the <CODE
CLASS="literal"
>1;</CODE
> was for earlier.) Another advantage of <CODE
CLASS="literal"
>require</CODE
> is that it keeps track of which files have already been loaded in the global hash <CODE
CLASS="literal"
>%INC</CODE
>. It doesn't reload the file if <CODE
CLASS="literal"
>%INC</CODE
> indicates that the file has already been read in.</P
><P
CLASS="para"
>Libraries work well when used by a program, but problems can arise when libraries use one another. Consequently, simple Perl libraries have been rendered mostly obsolete, replaced by the more modern modules. But some programs still use libraries, usually loading them in with <CODE
CLASS="literal"
>require</CODE
> instead of <CODE
CLASS="literal"
>do</CODE
>.</P
><P
CLASS="para"
>Other file extensions are occasionally seen in Perl. A <CODE
CLASS="literal"
>&quot;.ph&quot;</CODE
> is used for C header files that have been translated into Perl libraries using the <EM
CLASS="emphasis"
>h2ph</EM
> tool, as discussed in <A
CLASS="xref"
HREF="ch12_15.htm"
TITLE="Using h2ph to Translate C #include Files"
>Recipe 12.14</A
>. A <CODE
CLASS="literal"
>&quot;.xs&quot;</CODE
> indicates an augmented C source file, possibly created by the <EM
CLASS="emphasis"
>h2xs</EM
> tool, which will be compiled by the <EM
CLASS="emphasis"
>xsubpp</EM
> tool and your C compiler into native machine code. This process of creating mixed-language modules is discussed in <A
CLASS="xref"
HREF="ch12_16.htm"
TITLE="Using h2xs to Make a Module with C Code"
>Recipe 12.15</A
>.</P
><P
CLASS="para"
>So far we've only talked about traditional modules, which export their interface by allowing the caller direct access to particular subroutines and variables. Most modules fall into this category. But some problems &nbsp;-  and some programmers &nbsp;- lend themselves to more intricately designed modules, those involving objects. An object-oriented module seldom uses the import-export mechanism at all. Instead, it provides an object-oriented interface full of constructors, destructors, methods, inheritance, and operator overloading. This is the subject of <A
CLASS="xref"
HREF="ch13_01.htm"
TITLE="Classes, Objects, and Ties"
>Chapter 13</A
>.<A
CLASS="indexterm"
NAME="ch12-idx-1000005137-0"
></A
></P
></DIV
><DIV
CLASS="sect2"
><H3
CLASS="sect2"
><A
CLASS="title"
NAME="ch12-chap12_not_0"
>Not Reinventing the Wheel</A
></H3
><P
CLASS="para"
>CPAN, the <A
CLASS="indexterm"
NAME="ch12-idx-1000005138-0"
></A
><A
CLASS="indexterm"
NAME="ch12-idx-1000005138-1"
></A
>Comprehensive Perl Archive Network, is a gigantic repository of nearly everything about Perl you could imagine, including source, documentation, alternate ports, and above all, modules. Before you write a new module, check with CPAN to see whether one already exists that does what you need. Even if one doesn't, something close enough might give you ideas.</P
><P
CLASS="para"
>You can access CPAN at <A
CLASS="systemitem.url"
HREF="http://www.perl.com/CPAN/CPAN.html"
>http://www.perl.com/CPAN/CPAN.html</A
> (or <A
CLASS="systemitem.url"
HREF="ftp://www.perl.com/pub/perl/CPAN/CPAN.html "
>ftp://www.perl.com/pub/perl/CPAN/CPAN.html </A
>). This file briefly describes each of CPAN's modules, but because it's manually edited, it may not always have the very latest modules' descriptions. You can find out about those in the <EM
CLASS="emphasis"
>CPAN/RECENT</EM
> or <EM
CLASS="emphasis"
>CPAN/RECENT.html</EM
> file.</P
><P
CLASS="para"
>The module directory itself is in <EM
CLASS="emphasis"
>CPAN/modules</EM
>. It contains indices of all registered modules plus three convenient subdirectories: <EM
CLASS="emphasis"
>by-module</EM
>, <EM
CLASS="emphasis"
>by-author</EM
>, and <EM
CLASS="emphasis"
>by-category</EM
>. All modules are available through each of these, but the <EM
CLASS="emphasis"
>by-category</EM
> directory is probably the most useful. There you will find directories covering specific applications areas including operating system interfaces; networking, modems, and interprocess communication; database interfaces; user interfaces; interfaces to other programming languages; authentication, security, and encryption; World Wide Web, HTML, HTTP, CGI, and MIME; images, pixmap and bitmap manipulation, drawing, and graphing &nbsp;-  just to name a few.</P
></DIV
><DIV
CLASS="sect2"
><H3
CLASS="sect2"
><A
CLASS="title"
NAME="ch12-pgfId-1000005847"
>See Also</A
></H3
><P
CLASS="para"
>The sections on <A
CLASS="olink"
HREF="../prog/ch05_01.htm#PERL2-CH-5-SECT-1"
>"Packages"</A
> and on <A
CLASS="olink"
HREF="../prog/ch05_02.htm"
>"Modules"</A
> in <A
CLASS="olink"
HREF="../prog/ch05_01.htm"
>Chapter 5</A
> of <A
CLASS="citetitle"
HREF="../prog/index.htm"
TITLE="Programming Perl"
><CITE
CLASS="citetitle"
>Programming Perl</CITE
></A
> and in <I
CLASS="filename"
>perlmod </I
>(1)</P
></DIV
></DIV
></DIV
><DIV
CLASS="htmlnav"
><P
></P
><HR
ALIGN="LEFT"
WIDTH="684"
TITLE="footer"><TABLE
WIDTH="684"
BORDER="0"
CELLSPACING="0"
CELLPADDING="0"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="228"
><A
CLASS="sect1"
HREF="ch11_16.htm"
TITLE="11.15. Program: Binary Trees"
><IMG
SRC="../gifs/txtpreva.gif"
ALT="Previous: 11.15. Program: Binary Trees"
BORDER="0"></A
></TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
WIDTH="228"
><A
CLASS="book"
HREF="index.htm"
TITLE="Perl Cookbook"
><IMG
SRC="../gifs/txthome.gif"
ALT="Perl Cookbook"
BORDER="0"></A
></TD
><TD
ALIGN="RIGHT"
VALIGN="TOP"
WIDTH="228"
><A
CLASS="sect1"
HREF="ch12_02.htm"
TITLE="12.1. Defining a Module's Interface"
><IMG
SRC="../gifs/txtnexta.gif"
ALT="Next: 12.1. Defining a Module's Interface"
BORDER="0"></A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="228"
>11.15. Program: Binary Trees</TD
><TD
ALIGN="CENTER"
VALIGN="TOP"
WIDTH="228"
><A
CLASS="index"
HREF="index/index.htm"
TITLE="Book Index"
><IMG
SRC="../gifs/index.gif"
ALT="Book Index"
BORDER="0"></A
></TD
><TD
ALIGN="RIGHT"
VALIGN="TOP"
WIDTH="228"
>12.1. Defining a Module's Interface</TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="684"
TITLE="footer"><FONT
SIZE="-1"
></DIV<!-- LIBRARY NAV BAR --> <img src="../gifs/smnavbar.gif" usemap="#library-map" border="0" alt="Library Navigation Links"><p> <a href="copyrght.htm">Copyright &copy; 2002</a> O'Reilly &amp; Associates. All rights reserved.</font> </p> <map name="library-map"> <area shape="rect" coords="1,0,85,94" href="../index.htm"><area shape="rect" coords="86,1,178,103" href="../lwp/index.htm"><area shape="rect" coords="180,0,265,103" href="../lperl/index.htm"><area shape="rect" coords="267,0,353,105" href="../perlnut/index.htm"><area shape="rect" coords="354,1,446,115" href="../prog/index.htm"><area shape="rect" coords="448,0,526,132" href="../tk/index.htm"><area shape="rect" coords="528,1,615,119" href="../cookbook/index.htm"><area shape="rect" coords="617,0,690,135" href="../pxml/index.htm"></map> </BODY
></HTML
>