cgi.html

perl教程

</p>
<hr />
<h1><a name="abstract">ABSTRACT</a></h1>
<p>This perl library uses perl5 objects to make it easy to create Web
fill-out forms and parse their contents.  This package defines CGI
objects, entities that contain the values of the current query string
and other state variables.  Using a CGI object's methods, you can
examine keywords and parameters passed to your script, and create
forms whose initial values are taken from the current query (thereby
preserving state information).  The module provides shortcut functions
that produce boilerplate HTML, reducing typing and coding errors. It
also provides functionality for some of the more advanced features of
CGI scripting, including support for file uploads, cookies, cascading
style sheets, server push, and frames.</p>
<p>CGI.pm also provides a simple function-oriented programming style for
those who don't need its object-oriented features.</p>
<p>The current version of CGI.pm is available at</p>
<pre>
  <a href="http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html">http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html</a>
  <a href="ftp://ftp-genome.wi.mit.edu/pub/software/WWW/">ftp://ftp-genome.wi.mit.edu/pub/software/WWW/</a></pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>
</p>
<h2><a name="programming_style">PROGRAMMING STYLE</a></h2>
<p>There are two styles of programming with CGI.pm, an object-oriented
style and a function-oriented style.  In the object-oriented style you
create one or more CGI objects and then use object methods to create
the various elements of the page.  Each CGI object starts out with the
list of named parameters that were passed to your CGI script by the
server.  You can modify the objects, save them to a file or database
and recreate them.  Because each object corresponds to the &quot;state&quot; of
the CGI script, and because each object's parameter list is
independent of the others, this allows you to save the state of the
script and restore it later.</p>
<p>For example, using the object oriented style, here is how you create
a simple &quot;Hello World&quot; HTML page:</p>
<pre>
   <span class="comment">#!/usr/local/bin/perl -w</span>
   <span class="keyword">use</span> <span class="variable">CGI</span><span class="operator">;</span>                             <span class="comment"># load CGI routines</span>
   <span class="variable">$q</span> <span class="operator">=</span> <span class="variable">new</span> <span class="variable">CGI</span><span class="operator">;</span>                        <span class="comment"># create new CGI object</span>
   <span class="keyword">print</span> <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">header</span><span class="operator">,</span>                    <span class="comment"># create the HTTP header</span>
         <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">start_html</span><span class="operator">(</span><span class="string">'hello world'</span><span class="operator">),</span> <span class="comment"># start the HTML</span>
         <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">h1</span><span class="operator">(</span><span class="string">'hello world'</span><span class="operator">),</span>         <span class="comment"># level 1 header</span>
         <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">end_html</span><span class="operator">;</span>                  <span class="comment"># end the HTML</span>
</pre>
<p>In the function-oriented style, there is one default CGI object that
you rarely deal with directly.  Instead you just call functions to
retrieve CGI parameters, create HTML tags, manage cookies, and so
on.  This provides you with a cleaner programming interface, but
limits you to using one CGI object at a time.  The following example
prints the same page, but uses the function-oriented interface.
The main differences are that we now need to import a set of functions
into our name space (usually the &quot;standard&quot; functions), and we don't
need to create the CGI object.</p>
<pre>
   <span class="comment">#!/usr/local/bin/perl</span>
   <span class="keyword">use</span> <span class="variable">CGI</span> <span class="string">qw/:standard/</span><span class="operator">;</span>           <span class="comment"># load standard CGI routines</span>
   <span class="keyword">print</span> <span class="variable">header</span><span class="operator">,</span>                    <span class="comment"># create the HTTP header</span>
         <span class="variable">start_html</span><span class="operator">(</span><span class="string">'hello world'</span><span class="operator">),</span> <span class="comment"># start the HTML</span>
         <span class="variable">h1</span><span class="operator">(</span><span class="string">'hello world'</span><span class="operator">),</span>         <span class="comment"># level 1 header</span>
         <span class="variable">end_html</span><span class="operator">;</span>                  <span class="comment"># end the HTML</span>
</pre>
<p>The examples in this document mainly use the object-oriented style.
See HOW TO IMPORT FUNCTIONS for important information on
function-oriented programming in CGI.pm</p>
<p>
</p>
<h2><a name="calling_cgi_pm_routines">CALLING CGI.PM ROUTINES</a></h2>
<p>Most CGI.pm routines accept several arguments, sometimes as many as 20
optional ones!  To simplify this interface, all routines use a named
argument calling style that looks like this:</p>
<pre>
   <span class="keyword">print</span> <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">header</span><span class="operator">(</span><span class="string">-type</span><span class="operator">=&gt;</span><span class="string">'image/gif'</span><span class="operator">,</span><span class="string">-expires</span><span class="operator">=&gt;</span><span class="string">'+3d'</span><span class="operator">);</span>
</pre>
<p>Each argument name is preceded by a dash.  Neither case nor order
matters in the argument list.  -type, -Type, and -TYPE are all
acceptable.  In fact, only the first argument needs to begin with a
dash.  If a dash is present in the first argument, CGI.pm assumes
dashes for the subsequent ones.</p>
<p>Several routines are commonly called with just one argument.  In the
case of these routines you can provide the single argument without an
argument name.  <code>header()</code> happens to be one of these routines.  In this
case, the single argument is the document type.</p>
<pre>
   <span class="keyword">print</span> <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">header</span><span class="operator">(</span><span class="string">'text/html'</span><span class="operator">);</span>
</pre>
<p>Other such routines are documented below.</p>
<p>Sometimes named arguments expect a scalar, sometimes a reference to an
array, and sometimes a reference to a hash.  Often, you can pass any
type of argument and the routine will do whatever is most appropriate.
For example, the <code>param()</code> routine is used to set a CGI parameter to a
single or a multi-valued value.  The two cases are shown below:</p>
<pre>
   <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">param</span><span class="operator">(</span><span class="string">-name</span><span class="operator">=&gt;</span><span class="string">'veggie'</span><span class="operator">,</span><span class="string">-value</span><span class="operator">=&gt;</span><span class="string">'tomato'</span><span class="operator">);</span>
   <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">param</span><span class="operator">(</span><span class="string">-name</span><span class="operator">=&gt;</span><span class="string">'veggie'</span><span class="operator">,</span><span class="string">-value</span><span class="operator">=&gt;</span><span class="operator">[</span><span class="string">'tomato'</span><span class="operator">,</span><span class="string">'tomahto'</span><span class="operator">,</span><span class="string">'potato'</span><span class="operator">,</span><span class="string">'potahto'</span><span class="operator">]</span><span class="operator">);</span>
</pre>
<p>A large number of routines in CGI.pm actually aren't specifically
defined in the module, but are generated automatically as needed.
These are the &quot;HTML shortcuts,&quot; routines that generate HTML tags for
use in dynamically-generated pages.  HTML tags have both attributes
(the attribute=&quot;value&quot; pairs within the tag itself) and contents (the
part between the opening and closing pairs.)  To distinguish between
attributes and contents, CGI.pm uses the convention of passing HTML
attributes as a hash reference as the first argument, and the
contents, if any, as any subsequent arguments.  It works out like
this:</p>
<pre>
   <span class="variable">Code</span>                           <span class="variable">Generated</span> <span class="variable">HTML</span>
   <span class="operator">----</span>                           <span class="operator">--------------</span>
   <span class="variable">h1</span><span class="operator">()</span>                           <span class="operator">&lt;</span><span class="variable">h1</span><span class="operator">&gt;</span>
   <span class="variable">h1</span><span class="operator">(</span><span class="string">'some'</span><span class="operator">,</span><span class="string">'contents'</span><span class="operator">);</span>         <span class="operator">&lt;</span><span class="variable">h1</span><span class="operator">&gt;</span><span class="variable">some</span> <span class="variable">contents</span><span class="operator">&lt;/</span><span class="variable">h1</span><span class="operator">&gt;</span>
   <span class="variable">h1</span><span class="operator">(</span><span class="operator">{</span><span class="string">-align</span><span class="operator">=&gt;</span><span class="variable">left</span><span class="operator">}</span><span class="operator">);</span>            <span class="operator">&lt;</span><span class="variable">h1</span> <span class="variable">align</span><span class="operator">=</span><span class="string">"LEFT"</span><span class="operator">&gt;</span>
   <span class="variable">h1</span><span class="operator">(</span><span class="operator">{</span><span class="string">-align</span><span class="operator">=&gt;</span><span class="variable">left</span><span class="operator">}</span><span class="operator">,</span><span class="string">'contents'</span><span class="operator">);</span> <span class="operator">&lt;</span><span class="variable">h1</span> <span class="variable">align</span><span class="operator">=</span><span class="string">"LEFT"</span><span class="operator">&gt;</span><span class="variable">contents</span><span class="operator">&lt;/</span><span class="variable">h1</span><span class="operator">&gt;</span>
</pre>
<p>HTML tags are described in more detail later.</p>
<p>Many newcomers to CGI.pm are puzzled by the difference between the
calling conventions for the HTML shortcuts, which require curly braces
around the HTML tag attributes, and the calling conventions for other
routines, which manage to generate attributes without the curly
brackets.  Don't be confused.  As a convenience the curly braces are
optional in all but the HTML shortcuts.  If you like, you can use
curly braces when calling any routine that takes named arguments.  For
example:</p>
<pre>
   <span class="keyword">print</span> <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">header</span><span class="operator">(</span> <span class="operator">{</span><span class="string">-type</span><span class="operator">=&gt;</span><span class="string">'image/gif'</span><span class="operator">,</span><span class="string">-expires</span><span class="operator">=&gt;</span><span class="string">'+3d'</span><span class="operator">}</span> <span class="operator">);</span>
</pre>
<p>If you use the <strong>-w</strong> switch, you will be warned that some CGI.pm argument
names conflict with built-in Perl functions.  The most frequent of
these is the -values argument, used to create multi-valued menus,
radio button clusters and the like.  To get around this warning, you
have several choices:</p>
<ol>
<li>
<p>Use another name for the argument, if one is available. 
For example, -value is an alias for -values.</p>
</li>
<li>
<p>Change the capitalization, e.g. -Values</p>
</li>
<li>
<p>Put quotes around the argument name, e.g. '-values'</p>
</li>
</ol>
<p>Many routines will do something useful with a named argument that it
doesn't recognize.  For example, you can produce non-standard HTTP
header fields by providing them as named arguments:</p>
<pre>
  <span class="keyword">print</span> <span class="variable">$q</span><span class="operator">-&gt;</span><span class="variable">header</span><span class="operator">(</span><span class="string">-type</span>  <span class="operator">=&gt;</span>  <span class="string">'text/html'</span><span class="operator">,</span>
                   <span class="string">-cost</span>  <span class="operator">=&gt;</span>  <span class="string">'Three smackers'</span><span class="operator">,</span>
                   <span class="string">-annoyance_level</span> <span class="operator">=&gt;</span> <span class="string">'high'</span><span class="operator">,</span>
                   <span class="string">-complaints_to</span>   <span class="operator">=&gt;</span> <span class="string">'bit bucket'</span><span class="operator">);</span>
</pre>
<p>This will produce the following nonstandard HTTP header:</p>
<pre>
   HTTP/1.0 200 OK
   Cost: Three smackers
   Annoyance-level: high
   Complaints-to: bit bucket
   Content-type: text/html</pre>
<p>Notice the way that underscores are translated automatically into
hyphens.  HTML-generating routines perform a different type of
translation.</p>
<p>This feature allows you to keep up with the rapidly changing HTTP and