call.html
来自「perl教程」· HTML 代码 · 共 532 行 · 第 1/2 页
HTML
532 行
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../../displayToc.js"></script>
<script language="JavaScript" src="../../../tocParas.js"></script>
<script language="JavaScript" src="../../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../../scineplex.css">
<title>Filter::Util::Call - Perl Source Filter Utility Module</title>
<link rel="stylesheet" href="../../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<script>writelinks('__top__',3);</script>
<h1><a>Filter::Util::Call - Perl Source Filter Utility Module</a></h1>
<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#use_filter__util__call"><strong>use Filter::Util::Call</strong></a></li>
<li><a href="#import__"><strong>import()</strong></a></li>
<li><a href="#filter___and_anonymous_sub"><strong>filter() and anonymous sub</strong></a></li>
</ul>
<li><a href="#examples">EXAMPLES</a></li>
<ul>
<li><a href="#example_1__a_simple_filter_">Example 1: A simple filter.</a></li>
<li><a href="#example_2__using_the_context">Example 2: Using the context</a></li>
<li><a href="#example_3__using_the_context_within_the_filter">Example 3: Using the context within the filter</a></li>
<li><a href="#example_4__using_filter_del">Example 4: Using filter_del</a></li>
</ul>
<li><a href="#filter__simple">Filter::Simple</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#date">DATE</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Filter::Util::Call - Perl Source Filter Utility Module</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
<span class="keyword">use</span> <span class="variable">Filter::Util::Call</span> <span class="operator">;</span>
</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>This module provides you with the framework to write <em>Source Filters</em>
in Perl.</p>
<p>An alternate interface to Filter::Util::Call is now available. See
<a href="../../../lib/Filter/Simple.html">the Filter::Simple manpage</a> for more details.</p>
<p>A <em>Perl Source Filter</em> is implemented as a Perl module. The structure
of the module can take one of two broadly similar formats. To
distinguish between them, the first will be referred to as <em>method
filter</em> and the second as <em>closure filter</em>.</p>
<p>Here is a skeleton for the <em>method filter</em>:</p>
<pre>
<span class="keyword">package</span> <span class="variable">MyFilter</span> <span class="operator">;</span>
</pre>
<pre>
<span class="keyword">use</span> <span class="variable">Filter::Util::Call</span> <span class="operator">;</span>
</pre>
<pre>
<span class="keyword">sub</span><span class="variable"> import
</span><span class="operator">{</span>
<span class="keyword">my</span><span class="operator">(</span><span class="variable">$type</span><span class="operator">,</span> <span class="variable">@arguments</span><span class="operator">)</span> <span class="operator">=</span> <span class="variable">@_</span> <span class="operator">;</span>
<span class="variable">filter_add</span><span class="operator">(</span><span class="operator">[]</span><span class="operator">)</span> <span class="operator">;</span>
<span class="operator">}</span>
</pre>
<pre>
<span class="keyword">sub</span><span class="variable"> filter
</span><span class="operator">{</span>
<span class="keyword">my</span><span class="operator">(</span><span class="variable">$self</span><span class="operator">)</span> <span class="operator">=</span> <span class="variable">@_</span> <span class="operator">;</span>
<span class="keyword">my</span><span class="operator">(</span><span class="variable">$status</span><span class="operator">)</span> <span class="operator">;</span>
</pre>
<pre>
<span class="variable">$status</span> <span class="operator">=</span> <span class="variable">filter_read</span><span class="operator">()</span> <span class="operator">;</span>
<span class="variable">$status</span> <span class="operator">;</span>
<span class="operator">}</span>
</pre>
<pre>
<span class="number">1</span> <span class="operator">;</span>
</pre>
<p>and this is the equivalent skeleton for the <em>closure filter</em>:</p>
<pre>
<span class="keyword">package</span> <span class="variable">MyFilter</span> <span class="operator">;</span>
</pre>
<pre>
<span class="keyword">use</span> <span class="variable">Filter::Util::Call</span> <span class="operator">;</span>
</pre>
<pre>
<span class="keyword">sub</span><span class="variable"> import
</span><span class="operator">{</span>
<span class="keyword">my</span><span class="operator">(</span><span class="variable">$type</span><span class="operator">,</span> <span class="variable">@arguments</span><span class="operator">)</span> <span class="operator">=</span> <span class="variable">@_</span> <span class="operator">;</span>
</pre>
<pre>
<span class="variable">filter_add</span><span class="operator">(</span>
<span class="keyword">sub</span><span class="variable">
</span><span class="operator">{</span>
<span class="keyword">my</span><span class="operator">(</span><span class="variable">$status</span><span class="operator">)</span> <span class="operator">;</span>
<span class="variable">$status</span> <span class="operator">=</span> <span class="variable">filter_read</span><span class="operator">()</span> <span class="operator">;</span>
<span class="variable">$status</span> <span class="operator">;</span>
<span class="operator">}</span> <span class="operator">)</span>
<span class="operator">}</span>
</pre>
<pre>
<span class="number">1</span> <span class="operator">;</span>
</pre>
<p>To make use of either of the two filter modules above, place the line
below in a Perl source file.</p>
<pre>
<span class="keyword">use</span> <span class="variable">MyFilter</span><span class="operator">;</span>
</pre>
<p>In fact, the skeleton modules shown above are fully functional <em>Source
Filters</em>, albeit fairly useless ones. All they does is filter the
source stream without modifying it at all.</p>
<p>As you can see both modules have a broadly similar structure. They both
make use of the <code>Filter::Util::Call</code> module and both have an <a href="../../../lib/Pod/perlfunc.html#item_import"><code>import</code></a>
method. The difference between them is that the <em>method filter</em>
requires a <em>filter</em> method, whereas the <em>closure filter</em> gets the
equivalent of a <em>filter</em> method with the anonymous sub passed to
<em>filter_add</em>.</p>
<p>To make proper use of the <em>closure filter</em> shown above you need to
have a good understanding of the concept of a <em>closure</em>. See
<a href="../../../lib/Pod/perlref.html">the perlref manpage</a> for more details on the mechanics of <em>closures</em>.</p>
<p>
</p>
<h2><a name="use_filter__util__call"><strong>use Filter::Util::Call</strong></a></h2>
<p>The following functions are exported by <code>Filter::Util::Call</code>:</p>
<pre>
filter_add()
filter_read()
filter_read_exact()
filter_del()</pre>
<p>
</p>
<h2><a name="import__"><strong>import()</strong></a></h2>
<p>The <a href="../../../lib/Pod/perlfunc.html#item_import"><code>import</code></a> method is used to create an instance of the filter. It is
called indirectly by Perl when it encounters the <code>use MyFilter</code> line
in a source file (See <a href="../../../lib/Pod/perlfunc.html#import">import in the perlfunc manpage</a> for more details on
<a href="../../../lib/Pod/perlfunc.html#item_import"><code>import</code></a>).</p>
<p>It will always have at least one parameter automatically passed by Perl
- this corresponds to the name of the package. In the example above it
will be <code>"MyFilter"</code>.</p>
<p>Apart from the first parameter, import can accept an optional list of
parameters. These can be used to pass parameters to the filter. For
example:</p>
<pre>
<span class="keyword">use</span> <span class="variable">MyFilter</span> <span class="string">qw(a b c)</span> <span class="operator">;</span>
</pre>
<p>will result in the <a href="../../../lib/Pod/perlvar.html#item___"><code>@_</code></a> array having the following values:</p>
<pre>
@_ [0] => "MyFilter"
@_ [1] => "a"
@_ [2] => "b"
@_ [3] => "c"</pre>
<p>Before terminating, the <a href="../../../lib/Pod/perlfunc.html#item_import"><code>import</code></a> function must explicitly install the
filter by calling <code>filter_add</code>.</p>
<p><strong>filter_add()</strong></p>
<p>The function, <code>filter_add</code>, actually installs the filter. It takes one
parameter which should be a reference. The kind of reference used will
dictate which of the two filter types will be used.</p>
<p>If a CODE reference is used then a <em>closure filter</em> will be assumed.</p>
<p>If a CODE reference is not used, a <em>method filter</em> will be assumed.
In a <em>method filter</em>, the reference can be used to store context
information. The reference will be <em>blessed</em> into the package by
<code>filter_add</code>.</p>
<p>See the filters at the end of this documents for examples of using
context information using both <em>method filters</em> and <em>closure
filters</em>.</p>
<p>
</p>
<h2><a name="filter___and_anonymous_sub"><strong>filter() and anonymous sub</strong></a></h2>
<p>Both the <code>filter</code> method used with a <em>method filter</em> and the
anonymous sub used with a <em>closure filter</em> is where the main
processing for the filter is done.</p>
<p>The big difference between the two types of filter is that the <em>method
filter</em> uses the object passed to the method to store any context data,
whereas the <em>closure filter</em> uses the lexical variables that are
maintained by the closure.</p>
<p>Note that the single parameter passed to the <em>method filter</em>,
<code>$self</code>, is the same reference that was passed to <code>filter_add</code>
blessed into the filter's package. See the example filters later on for
details of using <code>$self</code>.</p>
<p>Here is a list of the common features of the anonymous sub and the
<code>filter()</code> method.</p>
<dl>
<dt><strong><a name="item___"><strong>$_</strong></a></strong>
<dd>
<p>Although <a href="#item___"><code>$_</code></a> doesn't actually appear explicitly in the sample filters
above, it is implicitly used in a number of places.</p>
</dd>
<dd>
<p>Firstly, when either <code>filter</code> or the anonymous sub are called, a local
copy of <a href="#item___"><code>$_</code></a> will automatically be created. It will always contain the
empty string at this point.</p>
</dd>
<dd>
<p>Next, both <code>filter_read</code> and <code>filter_read_exact</code> will append any
source data that is read to the end of <a href="#item___"><code>$_</code></a>.</p>
</dd>
<dd>
<p>Finally, when <code>filter</code> or the anonymous sub are finished processing,
they are expected to return the filtered source using <a href="#item___"><code>$_</code></a>.</p>
</dd>
<dd>
<p>This implicit use of <a href="#item___"><code>$_</code></a> greatly simplifies the filter.</p>
</dd>
</li>
<dt><strong><a name="item__status"><strong>$status</strong></a></strong>
<dd>
<p>The status value that is returned by the user's <code>filter</code> method or
anonymous sub and the <code>filter_read</code> and <code>read_exact</code> functions take
the same set of values, namely:</p>
</dd>
<dd>
<pre>
< 0 Error
= 0 EOF
> 0 OK</pre>
</dd>
</li>
<dt><strong><a name="item_filter_read_and_filter_read_exact"><strong>filter_read</strong> and <strong>filter_read_exact</strong></a></strong>
<dd>
<p>These functions are used by the filter to obtain either a line or block
from the next filter in the chain or the actual source file if there
aren't any other filters.</p>
</dd>
<dd>
<p>The function <code>filter_read</code> takes two forms:</p>
</dd>
<dd>
<pre>
<span class="variable">$status</span> <span class="operator">=</span> <span class="variable">filter_read</span><span class="operator">()</span> <span class="operator">;</span>
<span class="variable">$status</span> <span class="operator">=</span> <span class="variable">filter_read</span><span class="operator">(</span><span class="variable">$size</span><span class="operator">)</span> <span class="operator">;</span>
</pre>
</dd>
<dd>
<p>The first form is used to request a <em>line</em>, the second requests a
<em>block</em>.</p>
</dd>
<dd>
<p>In line mode, <code>filter_read</code> will append the next source line to the
end of the <a href="#item___"><code>$_</code></a> scalar.</p>
⌨️ 快捷键说明
复制代码Ctrl + C
搜索代码Ctrl + F
全屏模式F11
增大字号Ctrl + =
减小字号Ctrl + -
显示快捷键?