mingw/html/ext/Filter/Util/Call/Call.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Filter::Util::Call - Perl Source Filter Utility Module</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Filter::Util::Call - Perl Source Filter Utility Module</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <ul>
  26
  27                 <li><a href="#use_filter__util__call"><strong>use Filter::Util::Call</strong></a></li>
  28                 <li><a href="#import__"><strong>import()</strong></a></li>
  29                 <li><a href="#filter___and_anonymous_sub"><strong>filter() and anonymous sub</strong></a></li>
  30         </ul>
  31
  32         <li><a href="#examples">EXAMPLES</a></li>
  33         <ul>
  34
  35                 <li><a href="#example_1__a_simple_filter_">Example 1: A simple filter.</a></li>
  36                 <li><a href="#example_2__using_the_context">Example 2: Using the context</a></li>
  37                 <li><a href="#example_3__using_the_context_within_the_filter">Example 3: Using the context within the filter</a></li>
  38                 <li><a href="#example_4__using_filter_del">Example 4: Using filter_del</a></li>
  39         </ul>
  40
  41         <li><a href="#filter__simple">Filter::Simple</a></li>
  42         <li><a href="#author">AUTHOR</a></li>
  43         <li><a href="#date">DATE</a></li>
  44 </ul>
  45 <!-- INDEX END -->
  46
  47 <hr />
  48 <p>
  49 </p>
  50 <h1><a name="name">NAME</a></h1>
  51 <p>Filter::Util::Call - Perl Source Filter Utility Module</p>
  52 <p>
  53 </p>
  54 <hr />
  55 <h1><a name="synopsis">SYNOPSIS</a></h1>
  56 <pre>
  57     use Filter::Util::Call ;</pre>
  58 <p>
  59 </p>
  60 <hr />
  61 <h1><a name="description">DESCRIPTION</a></h1>
  62 <p>This module provides you with the framework to write <em>Source Filters</em>
  63 in Perl.</p>
  64 <p>An alternate interface to Filter::Util::Call is now available. See
  65 <a href="file://C|\msysgit\mingw\html/lib/Filter/Simple.html">the Filter::Simple manpage</a> for more details.</p>
  66 <p>A <em>Perl Source Filter</em> is implemented as a Perl module. The structure
  67 of the module can take one of two broadly similar formats. To
  68 distinguish between them, the first will be referred to as <em>method
  69 filter</em> and the second as <em>closure filter</em>.</p>
  70 <p>Here is a skeleton for the <em>method filter</em>:</p>
  71 <pre>
  72     package MyFilter ;</pre>
  73 <pre>
  74     use Filter::Util::Call ;</pre>
  75 <pre>
  76     sub import
  77     {
  78         my($type, @arguments) = @_ ;
  79         filter_add([]) ;
  80     }</pre>
  81 <pre>
  82     sub filter
  83     {
  84         my($self) = @_ ;
  85         my($status) ;</pre>
  86 <pre>
  87         $status = filter_read() ;
  88         $status ;
  89     }</pre>
  90 <pre>
  91     1 ;</pre>
  92 <p>and this is the equivalent skeleton for the <em>closure filter</em>:</p>
  93 <pre>
  94     package MyFilter ;</pre>
  95 <pre>
  96     use Filter::Util::Call ;</pre>
  97 <pre>
  98     sub import
  99     {
 100         my($type, @arguments) = @_ ;</pre>
 101 <pre>
 102         filter_add(
 103             sub
 104             {
 105                 my($status) ;
 106                 $status = filter_read() ;
 107                 $status ;
 108             } )
 109     }</pre>
 110 <pre>
 111     1 ;</pre>
 112 <p>To make use of either of the two filter modules above, place the line
 113 below in a Perl source file.</p>
 114 <pre>
 115     use MyFilter;</pre>
 116 <p>In fact, the skeleton modules shown above are fully functional <em>Source
 117 Filters</em>, albeit fairly useless ones. All they does is filter the
 118 source stream without modifying it at all.</p>
 119 <p>As you can see both modules have a broadly similar structure. They both
 120 make use of the <code>Filter::Util::Call</code> module and both have an <code>import</code>
 121 method. The difference between them is that the <em>method filter</em>
 122 requires a <em>filter</em> method, whereas the <em>closure filter</em> gets the
 123 equivalent of a <em>filter</em> method with the anonymous sub passed to
 124 <em>filter_add</em>.</p>
 125 <p>To make proper use of the <em>closure filter</em> shown above you need to
 126 have a good understanding of the concept of a <em>closure</em>. See
 127 <a href="file://C|\msysgit\mingw\html/pod/perlref.html">the perlref manpage</a> for more details on the mechanics of <em>closures</em>.</p>
 128 <p>
 129 </p>
 130 <h2><a name="use_filter__util__call"><strong>use Filter::Util::Call</strong></a></h2>
 131 <p>The following functions are exported by <code>Filter::Util::Call</code>:</p>
 132 <pre>
 133     filter_add()
 134     filter_read()
 135     filter_read_exact()
 136     filter_del()</pre>
 137 <p>
 138 </p>
 139 <h2><a name="import__"><strong>import()</strong></a></h2>
 140 <p>The <code>import</code> method is used to create an instance of the filter. It is
 141 called indirectly by Perl when it encounters the <code>use MyFilter</code> line
 142 in a source file (See <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#import">import in the perlfunc manpage</a> for more details on
 143 <code>import</code>).</p>
 144 <p>It will always have at least one parameter automatically passed by Perl
 145 - this corresponds to the name of the package. In the example above it
 146 will be <code>&quot;MyFilter&quot;</code>.</p>
 147 <p>Apart from the first parameter, import can accept an optional list of
 148 parameters. These can be used to pass parameters to the filter. For
 149 example:</p>
 150 <pre>
 151     use MyFilter qw(a b c) ;</pre>
 152 <p>will result in the <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item___"><code>@_</code></a> array having the following values:</p>
 153 <pre>
 154     @_ [0] =&gt; &quot;MyFilter&quot;
 155     @_ [1] =&gt; &quot;a&quot;
 156     @_ [2] =&gt; &quot;b&quot;
 157     @_ [3] =&gt; &quot;c&quot;</pre>
 158 <p>Before terminating, the <code>import</code> function must explicitly install the
 159 filter by calling <code>filter_add</code>.</p>
 160 <p><strong>filter_add()</strong></p>
 161 <p>The function, <code>filter_add</code>, actually installs the filter. It takes one
 162 parameter which should be a reference. The kind of reference used will
 163 dictate which of the two filter types will be used.</p>
 164 <p>If a CODE reference is used then a <em>closure filter</em> will be assumed.</p>
 165 <p>If a CODE reference is not used, a <em>method filter</em> will be assumed.
 166 In a <em>method filter</em>, the reference can be used to store context
 167 information. The reference will be <em>blessed</em> into the package by
 168 <code>filter_add</code>.</p>
 169 <p>See the filters at the end of this documents for examples of using
 170 context information using both <em>method filters</em> and <em>closure
 171 filters</em>.</p>
 172 <p>
 173 </p>
 174 <h2><a name="filter___and_anonymous_sub"><strong>filter() and anonymous sub</strong></a></h2>
 175 <p>Both the <code>filter</code> method used with a <em>method filter</em> and the
 176 anonymous sub used with a <em>closure filter</em> is where the main
 177 processing for the filter is done.</p>
 178 <p>The big difference between the two types of filter is that the <em>method
 179 filter</em> uses the object passed to the method to store any context data,
 180 whereas the <em>closure filter</em> uses the lexical variables that are
 181 maintained by the closure.</p>
 182 <p>Note that the single parameter passed to the <em>method filter</em>,
 183 <code>$self</code>, is the same reference that was passed to <code>filter_add</code>
 184 blessed into the filter's package. See the example filters later on for
 185 details of using <code>$self</code>.</p>
 186 <p>Here is a list of the common features of the anonymous sub and the
 187 <code>filter()</code> method.</p>
 188 <dl>
 189 <dt><strong><a name="item___"><strong>$_</strong></a></strong>
 190
 191 <dd>
 192 <p>Although <a href="#item___"><code>$_</code></a> doesn't actually appear explicitly in the sample filters
 193 above, it is implicitly used in a number of places.</p>
 194 </dd>
 195 <dd>
 196 <p>Firstly, when either <code>filter</code> or the anonymous sub are called, a local
 197 copy of <a href="#item___"><code>$_</code></a> will automatically be created. It will always contain the
 198 empty string at this point.</p>
 199 </dd>
 200 <dd>
 201 <p>Next, both <code>filter_read</code> and <code>filter_read_exact</code> will append any
 202 source data that is read to the end of <a href="#item___"><code>$_</code></a>.</p>
 203 </dd>
 204 <dd>
 205 <p>Finally, when <code>filter</code> or the anonymous sub are finished processing,
 206 they are expected to return the filtered source using <a href="#item___"><code>$_</code></a>.</p>
 207 </dd>
 208 <dd>
 209 <p>This implicit use of <a href="#item___"><code>$_</code></a> greatly simplifies the filter.</p>
 210 </dd>
 211 </li>
 212 <dt><strong><a name="item__status"><strong>$status</strong></a></strong>
 213
 214 <dd>
 215 <p>The status value that is returned by the user's <code>filter</code> method or
 216 anonymous sub and the <code>filter_read</code> and <code>read_exact</code> functions take
 217 the same set of values, namely:</p>
 218 </dd>
 219 <dd>
 220 <pre>
 221     &lt; 0  Error
 222     = 0  EOF
 223     &gt; 0  OK</pre>
 224 </dd>
 225 </li>
 226 <dt><strong><a name="item_filter_read_and_filter_read_exact"><strong>filter_read</strong> and <strong>filter_read_exact</strong></a></strong>
 227
 228 <dd>
 229 <p>These functions are used by the filter to obtain either a line or block
 230 from the next filter in the chain or the actual source file if there
 231 aren't any other filters.</p>
 232 </dd>
 233 <dd>
 234 <p>The function <code>filter_read</code> takes two forms:</p>
 235 </dd>
 236 <dd>
 237 <pre>
 238     $status = filter_read() ;
 239     $status = filter_read($size) ;</pre>
 240 </dd>
 241 <dd>
 242 <p>The first form is used to request a <em>line</em>, the second requests a
 243 <em>block</em>.</p>
 244 </dd>
 245 <dd>
 246 <p>In line mode, <code>filter_read</code> will append the next source line to the
 247 end of the <a href="#item___"><code>$_</code></a> scalar.</p>
 248 </dd>
 249 <dd>
 250 <p>In block mode, <code>filter_read</code> will append a block of data which is &lt;=
 251 <code>$size</code> to the end of the <a href="#item___"><code>$_</code></a> scalar. It is important to emphasise
 252 the that <code>filter_read</code> will not necessarily read a block which is
 253 <em>precisely</em> <code>$size</code> bytes.</p>
 254 </dd>
 255 <dd>
 256 <p>If you need to be able to read a block which has an exact size, you can
 257 use the function <code>filter_read_exact</code>. It works identically to
 258 <code>filter_read</code> in block mode, except it will try to read a block which
 259 is exactly <code>$size</code> bytes in length. The only circumstances when it
 260 will not return a block which is <code>$size</code> bytes long is on EOF or
 261 error.</p>
 262 </dd>
 263 <dd>
 264 <p>It is <em>very</em> important to check the value of <a href="#item__status"><code>$status</code></a> after <em>every</em>
 265 call to <code>filter_read</code> or <code>filter_read_exact</code>.</p>
 266 </dd>
 267 </li>
 268 <dt><strong><a name="item_filter_del"><strong>filter_del</strong></a></strong>
 269
 270 <dd>
 271 <p>The function, <a href="#item_filter_del"><code>filter_del</code></a>, is used to disable the current filter. It
 272 does not affect the running of the filter. All it does is tell Perl not
 273 to call filter any more.</p>
 274 </dd>
 275 <dd>
 276 <p>See <a href="#example_4__using_filter_del">Example 4: Using filter_del</a> for details.</p>
 277 </dd>
 278 </li>
 279 </dl>
 280 <p>
 281 </p>
 282 <hr />
 283 <h1><a name="examples">EXAMPLES</a></h1>
 284 <p>Here are a few examples which illustrate the key concepts - as such
 285 most of them are of little practical use.</p>
 286 <p>The <code>examples</code> sub-directory has copies of all these filters
 287 implemented both as <em>method filters</em> and as <em>closure filters</em>.</p>
 288 <p>
 289 </p>
 290 <h2><a name="example_1__a_simple_filter_">Example 1: A simple filter.</a></h2>
 291 <p>Below is a <em>method filter</em> which is hard-wired to replace all
 292 occurrences of the string <code>&quot;Joe&quot;</code> to <code>&quot;Jim&quot;</code>. Not particularly
 293 Useful, but it is the first example and I wanted to keep it simple.</p>
 294 <pre>
 295     package Joe2Jim ;</pre>
 296 <pre>
 297     use Filter::Util::Call ;</pre>
 298 <pre>
 299     sub import
 300     {
 301         my($type) = @_ ;</pre>
 302 <pre>
 303         filter_add(bless []) ;
 304     }</pre>
 305 <pre>
 306     sub filter
 307     {
 308         my($self) = @_ ;
 309         my($status) ;</pre>
 310 <pre>
 311         s/Joe/Jim/g
 312             if ($status = filter_read()) &gt; 0 ;
 313         $status ;
 314     }</pre>
 315 <pre>
 316     1 ;</pre>
 317 <p>Here is an example of using the filter:</p>
 318 <pre>
 319     use Joe2Jim ;
 320     print &quot;Where is Joe?\n&quot; ;</pre>
 321 <p>And this is what the script above will print:</p>
 322 <pre>
 323     Where is Jim?</pre>
 324 <p>
 325 </p>
 326 <h2><a name="example_2__using_the_context">Example 2: Using the context</a></h2>
 327 <p>The previous example was not particularly useful. To make it more
 328 general purpose we will make use of the context data and allow any
 329 arbitrary <em>from</em> and <em>to</em> strings to be used. This time we will use a
 330 <em>closure filter</em>. To reflect its enhanced role, the filter is called
 331 <code>Subst</code>.</p>
 332 <pre>
 333     package Subst ;</pre>
 334 <pre>
 335     use Filter::Util::Call ;
 336     use Carp ;</pre>
 337 <pre>
 338     sub import
 339     {
 340         croak(&quot;usage: use Subst qw(from to)&quot;)
 341             unless @_ == 3 ;
 342         my ($self, $from, $to) = @_ ;
 343         filter_add(
 344             sub
 345             {
 346                 my ($status) ;
 347                 s/$from/$to/
 348                     if ($status = filter_read()) &gt; 0 ;
 349                 $status ;
 350             })
 351     }
 352     1 ;</pre>
 353 <p>and is used like this:</p>
 354 <pre>
 355     use Subst qw(Joe Jim) ;
 356     print &quot;Where is Joe?\n&quot; ;</pre>
 357 <p>
 358 </p>
 359 <h2><a name="example_3__using_the_context_within_the_filter">Example 3: Using the context within the filter</a></h2>
 360 <p>Here is a filter which a variation of the <code>Joe2Jim</code> filter. As well as
 361 substituting all occurrences of <code>&quot;Joe&quot;</code> to <code>&quot;Jim&quot;</code> it keeps a count
 362 of the number of substitutions made in the context object.</p>
 363 <p>Once EOF is detected (<a href="#item__status"><code>$status</code></a> is zero) the filter will insert an
 364 extra line into the source stream. When this extra line is executed it
 365 will print a count of the number of substitutions actually made.
 366 Note that <a href="#item__status"><code>$status</code></a> is set to <code>1</code> in this case.</p>
 367 <pre>
 368     package Count ;</pre>
 369 <pre>
 370     use Filter::Util::Call ;</pre>
 371 <pre>
 372     sub filter
 373     {
 374         my ($self) = @_ ;
 375         my ($status) ;</pre>
 376 <pre>
 377         if (($status = filter_read()) &gt; 0 ) {
 378             s/Joe/Jim/g ;
 379             ++ $$self ;
 380         }
 381         elsif ($$self &gt;= 0) { # EOF
 382             $_ = &quot;print q[Made ${$self} substitutions\n]&quot; ;
 383             $status = 1 ;
 384             $$self = -1 ;
 385         }</pre>
 386 <pre>
 387         $status ;
 388     }</pre>
 389 <pre>
 390     sub import
 391     {
 392         my ($self) = @_ ;
 393         my ($count) = 0 ;
 394         filter_add(\$count) ;
 395     }</pre>
 396 <pre>
 397     1 ;</pre>
 398 <p>Here is a script which uses it:</p>
 399 <pre>
 400     use Count ;
 401     print &quot;Hello Joe\n&quot; ;
 402     print &quot;Where is Joe\n&quot; ;</pre>
 403 <p>Outputs:</p>
 404 <pre>
 405     Hello Jim
 406     Where is Jim
 407     Made 2 substitutions</pre>
 408 <p>
 409 </p>
 410 <h2><a name="example_4__using_filter_del">Example 4: Using filter_del</a></h2>
 411 <p>Another variation on a theme. This time we will modify the <code>Subst</code>
 412 filter to allow a starting and stopping pattern to be specified as well
 413 as the <em>from</em> and <em>to</em> patterns. If you know the <em>vi</em> editor, it is
 414 the equivalent of this command:</p>
 415 <pre>
 416     :/start/,/stop/s/from/to/</pre>
 417 <p>When used as a filter we want to invoke it like this:</p>
 418 <pre>
 419     use NewSubst qw(start stop from to) ;</pre>
 420 <p>Here is the module.</p>
 421 <pre>
 422     package NewSubst ;</pre>
 423 <pre>
 424     use Filter::Util::Call ;
 425     use Carp ;</pre>
 426 <pre>
 427     sub import
 428     {
 429         my ($self, $start, $stop, $from, $to) = @_ ;
 430         my ($found) = 0 ;
 431         croak(&quot;usage: use Subst qw(start stop from to)&quot;)
 432             unless @_ == 5 ;</pre>
 433 <pre>
 434         filter_add(
 435             sub
 436             {
 437                 my ($status) ;</pre>
 438 <pre>
 439                 if (($status = filter_read()) &gt; 0) {</pre>
 440 <pre>
 441                     $found = 1
 442                         if $found == 0 and /$start/ ;</pre>
 443 <pre>
 444                     if ($found) {
 445                         s/$from/$to/ ;
 446                         filter_del() if /$stop/ ;
 447                     }</pre>
 448 <pre>
 449                 }
 450                 $status ;
 451             } )</pre>
 452 <pre>
 453     }</pre>
 454 <pre>
 455     1 ;</pre>
 456 <p>
 457 </p>
 458 <hr />
 459 <h1><a name="filter__simple">Filter::Simple</a></h1>
 460 <p>If you intend using the Filter::Call functionality, I would strongly
 461 recommend that you check out Damian Conway's excellent Filter::Simple
 462 module. Damian's module provides a much cleaner interface than
 463 Filter::Util::Call. Although it doesn't allow the fine control that
 464 Filter::Util::Call does, it should be adequate for the majority of
 465 applications. It's available at</p>
 466 <pre>
 467    <a href="http://www.cpan.org/modules/by-author/Damian_Conway/Filter-Simple.tar.gz">http://www.cpan.org/modules/by-author/Damian_Conway/Filter-Simple.tar.gz</a>
 468    <a href="http://www.csse.monash.edu.au/~damian/CPAN/Filter-Simple.tar.gz">http://www.csse.monash.edu.au/~damian/CPAN/Filter-Simple.tar.gz</a></pre>
 469 <p>
 470 </p>
 471 <hr />
 472 <h1><a name="author">AUTHOR</a></h1>
 473 <p>Paul Marquess</p>
 474 <p>
 475 </p>
 476 <hr />
 477 <h1><a name="date">DATE</a></h1>
 478 <p>26th January 1996</p>
 479 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 480 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 481 <big><strong><span class="block">&nbsp;Filter::Util::Call - Perl Source Filter Utility Module</span></strong></big>
 482 </td></tr>
 483 </table>
 484
 485 </body>
 486
 487 </html>