cpan.html

来自「perl教程」· HTML 代码 · 共 1,396 行 · 第 1/4 页

<dd>
<p>The IDs of all objects available within a program are strings that can
be expanded to the corresponding real objects with the
<a href="#item_expand"><code>CPAN::Shell-&gt;expand(&quot;Module&quot;,@things)</code></a> method. Expand returns a
list of CPAN::Module objects according to the <code>@things</code> arguments
given. In scalar context it only returns the first element of the
list.</p>
</dd>
</li>
<dt><strong><a name="item_expandany"><code>expandany(@things)</code></a></strong>

<dd>
<p>Like expand, but returns objects of the appropriate type, i.e.
CPAN::Bundle objects for bundles, CPAN::Module objects for modules and
CPAN::Distribution objects fro distributions.</p>
</dd>
</li>
<dt><strong><a name="item_programming_examples">Programming Examples</a></strong>

<dd>
<p>This enables the programmer to do operations that combine
functionalities that are available in the shell.</p>
</dd>
<dd>
<pre>
    # install everything that is outdated on my disk:
    perl -MCPAN -e 'CPAN::Shell-&gt;install(CPAN::Shell-&gt;r)'</pre>
</dd>
<dd>
<pre>
    <span class="comment"># install my favorite programs if necessary:</span>
    <span class="keyword">for</span> <span class="variable">$mod</span> <span class="operator">(</span><span class="string">qw(Net::FTP Digest::MD5 Data::Dumper)</span><span class="operator">){</span>
        <span class="keyword">my</span> <span class="variable">$obj</span> <span class="operator">=</span> <span class="variable">CPAN::Shell</span><span class="operator">-&gt;</span><span class="variable">expand</span><span class="operator">(</span><span class="string">'Module'</span><span class="operator">,</span><span class="variable">$mod</span><span class="operator">);</span>
        <span class="variable">$obj</span><span class="operator">-&gt;</span><span class="variable">install</span><span class="operator">;</span>
    <span class="operator">}</span>
</pre>
</dd>
<dd>
<pre>
    <span class="comment"># list all modules on my disk that have no VERSION number</span>
    <span class="keyword">for</span> <span class="variable">$mod</span> <span class="operator">(</span><span class="variable">CPAN::Shell</span><span class="operator">-&gt;</span><span class="variable">expand</span><span class="operator">(</span><span class="string">"Module"</span><span class="operator">,</span><span class="string">"/./"</span><span class="operator">)){</span>
        <span class="keyword">next</span> <span class="keyword">unless</span> <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">inst_file</span><span class="operator">;</span>
        <span class="comment"># MakeMaker convention for undefined $VERSION:</span>
        <span class="keyword">next</span> <span class="keyword">unless</span> <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">inst_version</span> <span class="keyword">eq</span> <span class="string">"undef"</span><span class="operator">;</span>
        <span class="keyword">print</span> <span class="string">"No VERSION in "</span><span class="operator">,</span> <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">id</span><span class="operator">,</span> <span class="string">"\n"</span><span class="operator">;</span>
    <span class="operator">}</span>
</pre>
</dd>
<dd>
<pre>
    # find out which distribution on CPAN contains a module:
    print CPAN::Shell-&gt;expand(&quot;Module&quot;,&quot;Apache::Constants&quot;)-&gt;cpan_file</pre>
</dd>
<dd>
<p>Or if you want to write a cronjob to watch The CPAN, you could list
all modules that need updating. First a quick and dirty way:</p>
</dd>
<dd>
<pre>
    <span class="variable">perl</span> <span class="keyword">-e</span> <span class="string">'use CPAN; CPAN::Shell-&gt;r;'</span>
</pre>
</dd>
<dd>
<p>If you don't want to get any output in the case that all modules are
up to date, you can parse the output of above command for the regular
expression //modules are up to date// and decide to mail the output
only if it doesn't match. Ick?</p>
</dd>
<dd>
<p>If you prefer to do it more in a programmer style in one single
process, maybe something like this suits you better:</p>
</dd>
<dd>
<pre>
  <span class="comment"># list all modules on my disk that have newer versions on CPAN</span>
  <span class="keyword">for</span> <span class="variable">$mod</span> <span class="operator">(</span><span class="variable">CPAN::Shell</span><span class="operator">-&gt;</span><span class="variable">expand</span><span class="operator">(</span><span class="string">"Module"</span><span class="operator">,</span><span class="string">"/./"</span><span class="operator">)){</span>
    <span class="keyword">next</span> <span class="keyword">unless</span> <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">inst_file</span><span class="operator">;</span>
    <span class="keyword">next</span> <span class="keyword">if</span> <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">uptodate</span><span class="operator">;</span>
    <span class="keyword">printf</span> <span class="string">"Module %s is installed as %s, could be updated to %s from CPAN\n"</span><span class="operator">,</span>
        <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">id</span><span class="operator">,</span> <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">inst_version</span><span class="operator">,</span> <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">cpan_version</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
</dd>
<dd>
<p>If that gives you too much output every day, you maybe only want to
watch for three modules. You can write</p>
</dd>
<dd>
<pre>
  <span class="keyword">for</span> <span class="variable">$mod</span> <span class="operator">(</span><span class="variable">CPAN::Shell</span><span class="operator">-&gt;</span><span class="variable">expand</span><span class="operator">(</span><span class="string">"Module"</span><span class="operator">,</span><span class="string">"/Apache|LWP|CGI/"</span><span class="operator">)){</span>
</pre>
</dd>
<dd>
<p>as the first line instead. Or you can combine some of the above
tricks:</p>
</dd>
<dd>
<pre>
  <span class="comment"># watch only for a new mod_perl module</span>
  <span class="variable">$mod</span> <span class="operator">=</span> <span class="variable">CPAN::Shell</span><span class="operator">-&gt;</span><span class="variable">expand</span><span class="operator">(</span><span class="string">"Module"</span><span class="operator">,</span><span class="string">"mod_perl"</span><span class="operator">);</span>
  <span class="keyword">exit</span> <span class="keyword">if</span> <span class="variable">$mod</span><span class="operator">-&gt;</span><span class="variable">uptodate</span><span class="operator">;</span>
  <span class="comment"># new mod_perl arrived, let me know all update recommendations</span>
  <span class="variable">CPAN::Shell</span><span class="operator">-&gt;</span>r<span class="operator">;</span>
</pre>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="methods_in_the_other_classes">Methods in the other Classes</a></h2>
<p>The programming interface for the classes CPAN::Module,
CPAN::Distribution, CPAN::Bundle, and CPAN::Author is still considered
beta and partially even alpha. In the following paragraphs only those
methods are documented that have proven useful over a longer time and
thus are unlikely to change.</p>
<dl>
<dt><strong><a name="item_as_glimpse">CPAN::Author::as_glimpse()</a></strong>

<dd>
<p>Returns a one-line description of the author</p>
</dd>
</li>
<dt><strong><a name="item_as_string">CPAN::Author::as_string()</a></strong>

<dd>
<p>Returns a multi-line description of the author</p>
</dd>
</li>
<dt><strong><a name="item_email">CPAN::Author::email()</a></strong>

<dd>
<p>Returns the author's email address</p>
</dd>
</li>
<dt><strong><a name="item_fullname">CPAN::Author::fullname()</a></strong>

<dd>
<p>Returns the author's name</p>
</dd>
</li>
<dt><strong><a name="item_name">CPAN::Author::name()</a></strong>

<dd>
<p>An alias for fullname</p>
</dd>
</li>
<dt><strong>CPAN::Bundle::as_glimpse()</strong>

<dd>
<p>Returns a one-line description of the bundle</p>
</dd>
</li>
<dt><strong>CPAN::Bundle::as_string()</strong>

<dd>
<p>Returns a multi-line description of the bundle</p>
</dd>
</li>
<dt><strong><a name="item_clean">CPAN::Bundle::clean()</a></strong>

<dd>
<p>Recursively runs the <a href="#item_clean"><code>clean</code></a> method on all items contained in the bundle.</p>
</dd>
</li>
<dt><strong><a name="item_contains">CPAN::Bundle::contains()</a></strong>

<dd>
<p>Returns a list of objects' IDs contained in a bundle. The associated
objects may be bundles, modules or distributions.</p>
</dd>
</li>
<dt><strong><a name="item_force">CPAN::Bundle::force($method,@args)</a></strong>

<dd>
<p>Forces CPAN to perform a task that normally would have failed. Force
takes as arguments a method name to be called and any number of
additional arguments that should be passed to the called method. The
internals of the object get the needed changes so that CPAN.pm does
not refuse to take the action. The <a href="#item_force"><code>force</code></a> is passed recursively to
all contained objects.</p>
</dd>
</li>
<dt><strong><a name="item_get">CPAN::Bundle::get()</a></strong>

<dd>
<p>Recursively runs the <a href="#item_get"><code>get</code></a> method on all items contained in the bundle</p>
</dd>
</li>
<dt><strong><a name="item_inst_file">CPAN::Bundle::inst_file()</a></strong>

<dd>
<p>Returns the highest installed version of the bundle in either @INC or
<code>$CPAN::Config-</code>{cpan_home}&gt;. Note that this is different from
CPAN::Module::inst_file.</p>
</dd>
</li>
<dt><strong><a name="item_inst_version">CPAN::Bundle::inst_version()</a></strong>

<dd>
<p>Like CPAN::Bundle::inst_file, but returns the $VERSION</p>
</dd>
</li>
<dt><strong><a name="item_uptodate">CPAN::Bundle::uptodate()</a></strong>

<dd>
<p>Returns 1 if the bundle itself and all its members are uptodate.</p>
</dd>
</li>
<dt><strong><a name="item_install">CPAN::Bundle::install()</a></strong>

<dd>
<p>Recursively runs the <a href="#item_install"><code>install</code></a> method on all items contained in the bundle</p>
</dd>
</li>
<dt><strong><a name="item_make">CPAN::Bundle::make()</a></strong>

<dd>
<p>Recursively runs the <a href="#item_make"><code>make</code></a> method on all items contained in the bundle</p>
</dd>
</li>
<dt><strong><a name="item_readme">CPAN::Bundle::readme()</a></strong>

<dd>
<p>Recursively runs the <a href="#item_readme"><code>readme</code></a> method on all items contained in the bundle</p>
</dd>
</li>
<dt><strong><a name="item_test">CPAN::Bundle::test()</a></strong>

<dd>
<p>Recursively runs the <a href="#item_test"><code>test</code></a> method on all items contained in the bundle</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::as_glimpse()</strong>

<dd>
<p>Returns a one-line description of the distribution</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::as_string()</strong>

<dd>
<p>Returns a multi-line description of the distribution</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::clean()</strong>

<dd>
<p>Changes to the directory where the distribution has been unpacked and
runs <code>make clean</code> there.</p>
</dd>
</li>
<dt><strong><a name="item_containsmods">CPAN::Distribution::containsmods()</a></strong>

<dd>
<p>Returns a list of IDs of modules contained in a distribution file.
Only works for distributions listed in the 02packages.details.txt.gz
file. This typically means that only the most recent version of a
distribution is covered.</p>
</dd>
</li>
<dt><strong><a name="item_cvs_import">CPAN::Distribution::cvs_import()</a></strong>

<dd>
<p>Changes to the directory where the distribution has been unpacked and
runs something like</p>
</dd>
<dd>
<pre>
    cvs -d $cvs_root import -m $cvs_log $cvs_dir $userid v$version</pre>
</dd>
<dd>
<p>there.</p>
</dd>
</li>
<dt><strong><a name="item_dir">CPAN::Distribution::dir()</a></strong>

<dd>
<p>Returns the directory into which this distribution has been unpacked.</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::force($method,@args)</strong>

<dd>
<p>Forces CPAN to perform a task that normally would have failed. Force
takes as arguments a method name to be called and any number of
additional arguments that should be passed to the called method. The
internals of the object get the needed changes so that CPAN.pm does
not refuse to take the action.</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::get()</strong>

<dd>
<p>Downloads the distribution from CPAN and unpacks it. Does nothing if
the distribution has already been downloaded and unpacked within the
current session.</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::install()</strong>

<dd>
<p>Changes to the directory where the distribution has been unpacked and
runs the external command <code>make install</code> there. If <a href="#item_make"><code>make</code></a> has not
yet been run, it will be run first. A <code>make test</code> will be issued in
any case and if this fails, the install will be canceled. The
cancellation can be avoided by letting <a href="#item_force"><code>force</code></a> run the <a href="#item_install"><code>install</code></a> for
you.</p>
</dd>
</li>
<dt><strong><a name="item_isa_perl">CPAN::Distribution::isa_perl()</a></strong>

<dd>
<p>Returns 1 if this distribution file seems to be a perl distribution.
Normally this is derived from the file name only, but the index from
CPAN can contain a hint to achieve a return value of true for other
filenames too.</p>
</dd>
</li>
<dt><strong><a name="item_look">CPAN::Distribution::look()</a></strong>

<dd>
<p>Changes to the directory where the distribution has been unpacked and
opens a subshell there. Exiting the subshell returns.</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::make()</strong>

<dd>
<p>First runs the <a href="#item_get"><code>get</code></a> method to make sure the distribution is
downloaded and unpacked. Changes to the directory where the
distribution has been unpacked and runs the external commands <code>perl
Makefile.PL</code> and <a href="#item_make"><code>make</code></a> there.</p>
</dd>
</li>
<dt><strong><a name="item_prereq_pm">CPAN::Distribution::prereq_pm()</a></strong>

<dd>
<p>Returns the hash reference that has been announced by a distribution
as the PREREQ_PM hash in the Makefile.PL. Note: works only after an
attempt has been made to <a href="#item_make"><code>make</code></a> the distribution. Returns undef
otherwise.</p>
</dd>
</li>
<dt><strong>CPAN::Distribution::readme()</strong>

<dd>
<p>Downloads the README file associated with a distribution and runs it
through the pager specified in <code>$CPAN::Config-</code>{pager}&gt;.</p>