📄 ch12_02.htm
字号:
<HTML><HEAD><TITLE>Recipe 12.1. Defining a Module's Interface (Perl Cookbook)</TITLE><METANAME="DC.title"CONTENT="Perl Cookbook"><METANAME="DC.creator"CONTENT="Tom Christiansen & Nathan Torkington"><METANAME="DC.publisher"CONTENT="O'Reilly & Associates, Inc."><METANAME="DC.date"CONTENT="1999-07-02T01:41:22Z"><METANAME="DC.type"CONTENT="Text.Monograph"><METANAME="DC.format"CONTENT="text/html"SCHEME="MIME"><METANAME="DC.source"CONTENT="1-56592-243-3"SCHEME="ISBN"><METANAME="DC.language"CONTENT="en-US"><METANAME="generator"CONTENT="Jade 1.1/O'Reilly DocBook 3.0 to HTML 4.0"><LINKREV="made"HREF="mailto:online-books@oreilly.com"TITLE="Online Books Comments"><LINKREL="up"HREF="ch12_01.htm"TITLE="12. Packages, Libraries, and Modules"><LINKREL="prev"HREF="ch12_01.htm"TITLE="12.0. Introduction"><LINKREL="next"HREF="ch12_03.htm"TITLE="12.2. Trapping Errors in require or use"></HEAD><BODYBGCOLOR="#FFFFFF"><img alt="Book Home" border="0" src="gifs/smbanner.gif" usemap="#banner-map" /><map name="banner-map"><area shape="rect" coords="1,-2,616,66" href="index.htm" alt="Perl Cookbook"><area shape="rect" coords="629,-11,726,25" href="jobjects/fsearch.htm" alt="Search this book" /></map><div class="navbar"><p><TABLEWIDTH="684"BORDER="0"CELLSPACING="0"CELLPADDING="0"><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="228"><ACLASS="sect1"HREF="ch12_01.htm"TITLE="12.0. Introduction"><IMGSRC="../gifs/txtpreva.gif"ALT="Previous: 12.0. Introduction"BORDER="0"></A></TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="228"><B><FONTFACE="ARIEL,HELVETICA,HELV,SANSERIF"SIZE="-1"><ACLASS="chapter"REL="up"HREF="ch12_01.htm"TITLE="12. Packages, Libraries, and Modules"></A></FONT></B></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="228"><ACLASS="sect1"HREF="ch12_03.htm"TITLE="12.2. Trapping Errors in require or use"><IMGSRC="../gifs/txtnexta.gif"ALT="Next: 12.2. Trapping Errors in require or use"BORDER="0"></A></TD></TR></TABLE></DIV><DIVCLASS="sect1"><H2CLASS="sect1"><ACLASS="title"NAME="ch12-28525">12.1. Defining a Module's Interface</A></H2><DIVCLASS="sect2"><H3CLASS="sect2"><ACLASS="title"NAME="ch12-pgfId-158">Problem<ACLASS="indexterm"NAME="ch12-idx-1000005139-0"></A></A></H3><PCLASS="para">You want the standard <ACLASS="indexterm"NAME="ch12-idx-1000005140-0"></A>Exporter module to define the external interface to your module.</P></DIV><DIVCLASS="sect2"><H3CLASS="sect2"><ACLASS="title"NAME="ch12-pgfId-164">Solution</A></H3><PCLASS="para">In module file <EMCLASS="emphasis">YourModule.pm</EM>, place the following code. Fill in the ellipses as explained in the Discussion section.</P><PRECLASS="programlisting">package YourModule;use strict;use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS $VERSION);use Exporter;$VERSION = 1.00; # Or higher@ISA = qw(Exporter);@EXPORT = qw(...); # Symbols to autoexport (:DEFAULT tag)@EXPORT_OK = qw(...); # Symbols to export on request%EXPORT_TAGS = ( # Define names for sets of symbols TAG1 => [...], TAG2 => [...], ...);######################### your code goes here########################1; # this should be your last line</PRE><PCLASS="para">In other files where you want to use YourModule, choose one of these lines:</P><PRECLASS="programlisting">use YourModule; # Import default symbols into my package.use YourModule qw(...); # Import listed symbols into my package.use YourModule (); # Do not import any symbolsuse YourModule qw(:TAG1); # Import whole tag set</PRE></DIV><DIVCLASS="sect2"><H3CLASS="sect2"><ACLASS="title"NAME="ch12-pgfId-236">Discussion</A></H3><PCLASS="para">The standard Exporter module handles the module's external interface. Although you could define your own <CODECLASS="literal">import</CODE> method for your package, almost no one does this.</P><PCLASS="para">When someone says <CODECLASS="literal">use</CODE> <CODECLASS="literal">YourModule</CODE>, this does a <CODECLASS="literal">require</CODE> <CODECLASS="literal">"YourModule.pm"</CODE> statement followed a <CODECLASS="literal">YourModule->import()</CODE> method call, both during compile time. The <CODECLASS="literal">import</CODE> method inherited from the Exporter package looks for global variables in your package to govern its behavior. Because they must be package globals, we've declared them with the <CODECLASS="literal">use</CODE> <CODECLASS="literal">vars</CODE> pragma to satisfy <CODECLASS="literal">use</CODE> <CODECLASS="literal">strict</CODE>. These variables are:</P><DLCLASS="variablelist"><DTCLASS="term"><CODECLASS="literal">$VERSION</CODE> </DT><DDCLASS="listitem"><PCLASS="para"><ACLASS="indexterm"NAME="ch12-idx-1000005151-0"></A>When a module is loaded, a minimal required version number can be supplied. If the version isn't at least this high, the <CODECLASS="literal">use</CODE> will raise an exception.</P><PCLASS="para">use YourModule 1.86; # If $VERSION < 1.86, fail</P></DD><DTCLASS="term"><CODECLASS="literal">@EXPORT</CODE> </DT><DDCLASS="listitem"><PCLASS="para"><ACLASS="indexterm"NAME="ch12-idx-1000005152-0"></A>This array contains a list of functions and variables that will be exported into the caller's own namespace so they can be accessed without being fully qualified. Typically, a <CODECLASS="literal">qw()</CODE> list is used.</P><PRECLASS="programlisting"> @EXPORT = qw(&F1 &F2 @List); @EXPORT = qw( F1 F2 @List); # same thing</PRE><PCLASS="para">When a simple <CODECLASS="literal">use</CODE> <CODECLASS="literal">YourModule</CODE> call is made, the function <CODECLASS="literal">&F1</CODE> can be called as <CODECLASS="literal">F1()</CODE> rather than <CODECLASS="literal">YourModule::F1()</CODE> and the array can be accessed as <CODECLASS="literal">@List</CODE> instead of <CODECLASS="literal">@YourModule::List</CODE>. The ampersand is optional in front of an exported function specification.</P><PCLASS="para">To load the module at compile time but request that no symbols be exported, use the special form <CODECLASS="literal">use</CODE> <CODECLASS="literal">Exporter</CODE> <CODECLASS="literal">()</CODE>, with empty parentheses.</P></DD><DTCLASS="term"><CODECLASS="literal">@EXPORT_OK</CODE> </DT><DDCLASS="listitem"><PCLASS="para"><ACLASS="indexterm"NAME="ch12-idx-1000005154-0"></A>This array contains symbols that can be imported if they're specifically asked for. If the array were loaded this way:</P><PRECLASS="programlisting"> @EXPORT_OK = qw(Op_Func %Table);</PRE><PCLASS="para">Then the user could load the module like so:</P><PRECLASS="programlisting"> use YourModule qw(Op_Func %Table F1);</PRE><PCLASS="para">and import only the <CODECLASS="literal">Op_Func</CODE> function, the <CODECLASS="literal">%Table</CODE> hash, and the <CODECLASS="literal">F1</CODE> function. The <CODECLASS="literal">F1</CODE> function was listed in the <CODECLASS="literal">@EXPORT</CODE> array. Notice that this does not automatically import <CODECLASS="literal">F2</CODE> or <CODECLASS="literal">@List</CODE>, even though they're in <CODECLASS="literal">@EXPORT</CODE>. To get everything in <CODECLASS="literal">@EXPORT</CODE> plus extras from <CODECLASS="literal">@EXPORT_OK</CODE>, use the special <CODECLASS="literal">:DEFAULT</CODE> tag, such as:</P><PRECLASS="programlisting"> use YourModule qw(:DEFAULT %Table);</PRE></DD><DTCLASS="term"><CODECLASS="literal">%EXPORT_TAGS</CODE> </DT><DDCLASS="listitem"><PCLASS="para">This hash is used by large modules like CGI or POSIX to create higher-level groupings of related import symbols. Its values are references to arrays of symbol names, all of which must be in either <ACLASS="indexterm"NAME="ch12-idx-1000005165-0"></A><CODECLASS="literal">@EXPORT</CODE> or <CODECLASS="literal">@EXPORT_OK</CODE>. Here's a sample initialization:</P><PRECLASS="programlisting"> %EXPORT_TAGS = ( Functions => [ qw(F1 F2 Op_Func) ], Variables => [ qw(@List %Table) ],);</PRE><PCLASS="para">An import symbol with a leading colon means to import a whole group of symbols. Here's an example:</P><PRECLASS="programlisting"> use YourModule qw(:Functions %Table);</PRE><PCLASS="para">That pulls in all the symbols from</P><PRECLASS="programlisting"><CODECLASS="literal"> @{</CODE> <CODECLASS="literal">$YourModule::EXPORT_TAGS{Functions}</CODE> <CODECLASS="literal">}</CODE>, </PRE><PCLASS="para">that is, it pulls in the <CODECLASS="literal">F1</CODE>, <CODECLASS="literal">F2</CODE>, and <CODECLASS="literal">Op_Func</CODE> functions and then the <CODECLASS="literal">%Table</CODE> hash.</P><PCLASS="para">Although you don't list it in <CODECLASS="literal">%EXPORT_TAGS</CODE>, the implicit tag <CODECLASS="literal">:DEFAULT</CODE> automatically means everything in <CODECLASS="literal">@EXPORT</CODE>.</P><PCLASS="para">You don't have to have all those variables defined in your module. You just need the ones that you expect people to be able to use.<ACLASS="indexterm"NAME="ch12-idx-1000005142-0"></A><ACLASS="indexterm"NAME="ch12-idx-1000005142-1"></A></P></DD></DL></DIV><DIVCLASS="sect2"><H3CLASS="sect2"><ACLASS="title"NAME="ch12-pgfId-332">See Also</A></H3><PCLASS="para">The documentation for the standard Exporter module, also found in <ACLASS="olink"HREF="../prog/ch07_01.htm">Chapter 7</A> of <ACLASS="citetitle"HREF="../prog/index.htm"TITLE="Programming Perl"><CITECLASS="citetitle">Programming Perl</CITE></A>; <ACLASS="xref"HREF="ch12_08.htm"TITLE="Keeping Your Own Module Directory">Recipe 12.7</A>; <ACLASS="xref"HREF="ch12_19.htm"TITLE="Example: Module Template">Recipe 12.18</A></P></DIV></DIV><DIVCLASS="htmlnav"><P></P><HRALIGN="LEFT"WIDTH="684"TITLE="footer"><TABLEWIDTH="684"BORDER="0"CELLSPACING="0"CELLPADDING="0"><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="228"><ACLASS="sect1"HREF="ch12_01.htm"TITLE="12.0. Introduction"><IMGSRC="../gifs/txtpreva.gif"ALT="Previous: 12.0. Introduction"BORDER="0"></A></TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="228"><ACLASS="book"HREF="index.htm"TITLE="Perl Cookbook"><IMGSRC="../gifs/txthome.gif"ALT="Perl Cookbook"BORDER="0"></A></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="228"><ACLASS="sect1"HREF="ch12_03.htm"TITLE="12.2. Trapping Errors in require or use"><IMGSRC="../gifs/txtnexta.gif"ALT="Next: 12.2. Trapping Errors in require or use"BORDER="0"></A></TD></TR><TR><TDALIGN="LEFT"VALIGN="TOP"WIDTH="228">12.0. Introduction</TD><TDALIGN="CENTER"VALIGN="TOP"WIDTH="228"><ACLASS="index"HREF="index/index.htm"TITLE="Book Index"><IMGSRC="../gifs/index.gif"ALT="Book Index"BORDER="0"></A></TD><TDALIGN="RIGHT"VALIGN="TOP"WIDTH="228">12.2. Trapping Errors in require or use</TD></TR></TABLE><HRALIGN="LEFT"WIDTH="684"TITLE="footer"><FONTSIZE="-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 © 2002</a> O'Reilly & 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>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -