Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "Filter::Util::Call 3" | |
132 | .TH Filter::Util::Call 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | Filter::Util::Call \- Perl Source Filter Utility Module | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 1 | |
138 | \& use Filter::Util::Call ; | |
139 | .Ve | |
140 | .SH "DESCRIPTION" | |
141 | .IX Header "DESCRIPTION" | |
142 | This module provides you with the framework to write \fISource Filters\fR | |
143 | in Perl. | |
144 | .PP | |
145 | An alternate interface to Filter::Util::Call is now available. See | |
146 | Filter::Simple for more details. | |
147 | .PP | |
148 | A \fIPerl Source Filter\fR is implemented as a Perl module. The structure | |
149 | of the module can take one of two broadly similar formats. To | |
150 | distinguish between them, the first will be referred to as \fImethod | |
151 | filter\fR and the second as \fIclosure filter\fR. | |
152 | .PP | |
153 | Here is a skeleton for the \fImethod filter\fR: | |
154 | .PP | |
155 | .Vb 1 | |
156 | \& package MyFilter ; | |
157 | .Ve | |
158 | .PP | |
159 | .Vb 1 | |
160 | \& use Filter::Util::Call ; | |
161 | .Ve | |
162 | .PP | |
163 | .Vb 5 | |
164 | \& sub import | |
165 | \& { | |
166 | \& my($type, @arguments) = @_ ; | |
167 | \& filter_add([]) ; | |
168 | \& } | |
169 | .Ve | |
170 | .PP | |
171 | .Vb 4 | |
172 | \& sub filter | |
173 | \& { | |
174 | \& my($self) = @_ ; | |
175 | \& my($status) ; | |
176 | .Ve | |
177 | .PP | |
178 | .Vb 3 | |
179 | \& $status = filter_read() ; | |
180 | \& $status ; | |
181 | \& } | |
182 | .Ve | |
183 | .PP | |
184 | .Vb 1 | |
185 | \& 1 ; | |
186 | .Ve | |
187 | .PP | |
188 | and this is the equivalent skeleton for the \fIclosure filter\fR: | |
189 | .PP | |
190 | .Vb 1 | |
191 | \& package MyFilter ; | |
192 | .Ve | |
193 | .PP | |
194 | .Vb 1 | |
195 | \& use Filter::Util::Call ; | |
196 | .Ve | |
197 | .PP | |
198 | .Vb 3 | |
199 | \& sub import | |
200 | \& { | |
201 | \& my($type, @arguments) = @_ ; | |
202 | .Ve | |
203 | .PP | |
204 | .Vb 8 | |
205 | \& filter_add( | |
206 | \& sub | |
207 | \& { | |
208 | \& my($status) ; | |
209 | \& $status = filter_read() ; | |
210 | \& $status ; | |
211 | \& } ) | |
212 | \& } | |
213 | .Ve | |
214 | .PP | |
215 | .Vb 1 | |
216 | \& 1 ; | |
217 | .Ve | |
218 | .PP | |
219 | To make use of either of the two filter modules above, place the line | |
220 | below in a Perl source file. | |
221 | .PP | |
222 | .Vb 1 | |
223 | \& use MyFilter; | |
224 | .Ve | |
225 | .PP | |
226 | In fact, the skeleton modules shown above are fully functional \fISource | |
227 | Filters\fR, albeit fairly useless ones. All they does is filter the | |
228 | source stream without modifying it at all. | |
229 | .PP | |
230 | As you can see both modules have a broadly similar structure. They both | |
231 | make use of the \f(CW\*(C`Filter::Util::Call\*(C'\fR module and both have an \f(CW\*(C`import\*(C'\fR | |
232 | method. The difference between them is that the \fImethod filter\fR | |
233 | requires a \fIfilter\fR method, whereas the \fIclosure filter\fR gets the | |
234 | equivalent of a \fIfilter\fR method with the anonymous sub passed to | |
235 | \&\fIfilter_add\fR. | |
236 | .PP | |
237 | To make proper use of the \fIclosure filter\fR shown above you need to | |
238 | have a good understanding of the concept of a \fIclosure\fR. See | |
239 | perlref for more details on the mechanics of \fIclosures\fR. | |
240 | .Sh "\fBuse Filter::Util::Call\fP" | |
241 | .IX Subsection "use Filter::Util::Call" | |
242 | The following functions are exported by \f(CW\*(C`Filter::Util::Call\*(C'\fR: | |
243 | .PP | |
244 | .Vb 4 | |
245 | \& filter_add() | |
246 | \& filter_read() | |
247 | \& filter_read_exact() | |
248 | \& filter_del() | |
249 | .Ve | |
250 | .Sh "\fB\fP\f(BIimport()\fP\fB\fP" | |
251 | .IX Subsection "import()" | |
252 | The \f(CW\*(C`import\*(C'\fR method is used to create an instance of the filter. It is | |
253 | called indirectly by Perl when it encounters the \f(CW\*(C`use MyFilter\*(C'\fR line | |
254 | in a source file (See \*(L"import\*(R" in perlfunc for more details on | |
255 | \&\f(CW\*(C`import\*(C'\fR). | |
256 | .PP | |
257 | It will always have at least one parameter automatically passed by Perl | |
258 | \&\- this corresponds to the name of the package. In the example above it | |
259 | will be \f(CW"MyFilter"\fR. | |
260 | .PP | |
261 | Apart from the first parameter, import can accept an optional list of | |
262 | parameters. These can be used to pass parameters to the filter. For | |
263 | example: | |
264 | .PP | |
265 | .Vb 1 | |
266 | \& use MyFilter qw(a b c) ; | |
267 | .Ve | |
268 | .PP | |
269 | will result in the \f(CW@_\fR array having the following values: | |
270 | .PP | |
271 | .Vb 4 | |
272 | \& @_ [0] => "MyFilter" | |
273 | \& @_ [1] => "a" | |
274 | \& @_ [2] => "b" | |
275 | \& @_ [3] => "c" | |
276 | .Ve | |
277 | .PP | |
278 | Before terminating, the \f(CW\*(C`import\*(C'\fR function must explicitly install the | |
279 | filter by calling \f(CW\*(C`filter_add\*(C'\fR. | |
280 | .PP | |
281 | \&\fB\f(BIfilter_add()\fB\fR | |
282 | .PP | |
283 | The function, \f(CW\*(C`filter_add\*(C'\fR, actually installs the filter. It takes one | |
284 | parameter which should be a reference. The kind of reference used will | |
285 | dictate which of the two filter types will be used. | |
286 | .PP | |
287 | If a \s-1CODE\s0 reference is used then a \fIclosure filter\fR will be assumed. | |
288 | .PP | |
289 | If a \s-1CODE\s0 reference is not used, a \fImethod filter\fR will be assumed. | |
290 | In a \fImethod filter\fR, the reference can be used to store context | |
291 | information. The reference will be \fIblessed\fR into the package by | |
292 | \&\f(CW\*(C`filter_add\*(C'\fR. | |
293 | .PP | |
294 | See the filters at the end of this documents for examples of using | |
295 | context information using both \fImethod filters\fR and \fIclosure | |
296 | filters\fR. | |
297 | .Sh "\fB\fP\f(BIfilter()\fP\fB and anonymous sub\fP" | |
298 | .IX Subsection "filter() and anonymous sub" | |
299 | Both the \f(CW\*(C`filter\*(C'\fR method used with a \fImethod filter\fR and the | |
300 | anonymous sub used with a \fIclosure filter\fR is where the main | |
301 | processing for the filter is done. | |
302 | .PP | |
303 | The big difference between the two types of filter is that the \fImethod | |
304 | filter\fR uses the object passed to the method to store any context data, | |
305 | whereas the \fIclosure filter\fR uses the lexical variables that are | |
306 | maintained by the closure. | |
307 | .PP | |
308 | Note that the single parameter passed to the \fImethod filter\fR, | |
309 | \&\f(CW$self\fR, is the same reference that was passed to \f(CW\*(C`filter_add\*(C'\fR | |
310 | blessed into the filter's package. See the example filters later on for | |
311 | details of using \f(CW$self\fR. | |
312 | .PP | |
313 | Here is a list of the common features of the anonymous sub and the | |
314 | \&\f(CW\*(C`filter()\*(C'\fR method. | |
315 | .IP "\fB$_\fR" 5 | |
316 | .IX Item "$_" | |
317 | Although \f(CW$_\fR doesn't actually appear explicitly in the sample filters | |
318 | above, it is implicitly used in a number of places. | |
319 | .Sp | |
320 | Firstly, when either \f(CW\*(C`filter\*(C'\fR or the anonymous sub are called, a local | |
321 | copy of \f(CW$_\fR will automatically be created. It will always contain the | |
322 | empty string at this point. | |
323 | .Sp | |
324 | Next, both \f(CW\*(C`filter_read\*(C'\fR and \f(CW\*(C`filter_read_exact\*(C'\fR will append any | |
325 | source data that is read to the end of \f(CW$_\fR. | |
326 | .Sp | |
327 | Finally, when \f(CW\*(C`filter\*(C'\fR or the anonymous sub are finished processing, | |
328 | they are expected to return the filtered source using \f(CW$_\fR. | |
329 | .Sp | |
330 | This implicit use of \f(CW$_\fR greatly simplifies the filter. | |
331 | .IP "\fB$status\fR" 5 | |
332 | .IX Item "$status" | |
333 | The status value that is returned by the user's \f(CW\*(C`filter\*(C'\fR method or | |
334 | anonymous sub and the \f(CW\*(C`filter_read\*(C'\fR and \f(CW\*(C`read_exact\*(C'\fR functions take | |
335 | the same set of values, namely: | |
336 | .Sp | |
337 | .Vb 3 | |
338 | \& < 0 Error | |
339 | \& = 0 EOF | |
340 | \& > 0 OK | |
341 | .Ve | |
342 | .IP "\fBfilter_read\fR and \fBfilter_read_exact\fR" 5 | |
343 | .IX Item "filter_read and filter_read_exact" | |
344 | These functions are used by the filter to obtain either a line or block | |
345 | from the next filter in the chain or the actual source file if there | |
346 | aren't any other filters. | |
347 | .Sp | |
348 | The function \f(CW\*(C`filter_read\*(C'\fR takes two forms: | |
349 | .Sp | |
350 | .Vb 2 | |
351 | \& $status = filter_read() ; | |
352 | \& $status = filter_read($size) ; | |
353 | .Ve | |
354 | .Sp | |
355 | The first form is used to request a \fIline\fR, the second requests a | |
356 | \&\fIblock\fR. | |
357 | .Sp | |
358 | In line mode, \f(CW\*(C`filter_read\*(C'\fR will append the next source line to the | |
359 | end of the \f(CW$_\fR scalar. | |
360 | .Sp | |
361 | In block mode, \f(CW\*(C`filter_read\*(C'\fR will append a block of data which is <= | |
362 | \&\f(CW$size\fR to the end of the \f(CW$_\fR scalar. It is important to emphasise | |
363 | the that \f(CW\*(C`filter_read\*(C'\fR will not necessarily read a block which is | |
364 | \&\fIprecisely\fR \f(CW$size\fR bytes. | |
365 | .Sp | |
366 | If you need to be able to read a block which has an exact size, you can | |
367 | use the function \f(CW\*(C`filter_read_exact\*(C'\fR. It works identically to | |
368 | \&\f(CW\*(C`filter_read\*(C'\fR in block mode, except it will try to read a block which | |
369 | is exactly \f(CW$size\fR bytes in length. The only circumstances when it | |
370 | will not return a block which is \f(CW$size\fR bytes long is on \s-1EOF\s0 or | |
371 | error. | |
372 | .Sp | |
373 | It is \fIvery\fR important to check the value of \f(CW$status\fR after \fIevery\fR | |
374 | call to \f(CW\*(C`filter_read\*(C'\fR or \f(CW\*(C`filter_read_exact\*(C'\fR. | |
375 | .IP "\fBfilter_del\fR" 5 | |
376 | .IX Item "filter_del" | |
377 | The function, \f(CW\*(C`filter_del\*(C'\fR, is used to disable the current filter. It | |
378 | does not affect the running of the filter. All it does is tell Perl not | |
379 | to call filter any more. | |
380 | .Sp | |
381 | See \*(L"Example 4: Using filter_del\*(R" for details. | |
382 | .SH "EXAMPLES" | |
383 | .IX Header "EXAMPLES" | |
384 | Here are a few examples which illustrate the key concepts \- as such | |
385 | most of them are of little practical use. | |
386 | .PP | |
387 | The \f(CW\*(C`examples\*(C'\fR sub-directory has copies of all these filters | |
388 | implemented both as \fImethod filters\fR and as \fIclosure filters\fR. | |
389 | .Sh "Example 1: A simple filter." | |
390 | .IX Subsection "Example 1: A simple filter." | |
391 | Below is a \fImethod filter\fR which is hard-wired to replace all | |
392 | occurrences of the string \f(CW"Joe"\fR to \f(CW"Jim"\fR. Not particularly | |
393 | Useful, but it is the first example and I wanted to keep it simple. | |
394 | .PP | |
395 | .Vb 1 | |
396 | \& package Joe2Jim ; | |
397 | .Ve | |
398 | .PP | |
399 | .Vb 1 | |
400 | \& use Filter::Util::Call ; | |
401 | .Ve | |
402 | .PP | |
403 | .Vb 3 | |
404 | \& sub import | |
405 | \& { | |
406 | \& my($type) = @_ ; | |
407 | .Ve | |
408 | .PP | |
409 | .Vb 2 | |
410 | \& filter_add(bless []) ; | |
411 | \& } | |
412 | .Ve | |
413 | .PP | |
414 | .Vb 4 | |
415 | \& sub filter | |
416 | \& { | |
417 | \& my($self) = @_ ; | |
418 | \& my($status) ; | |
419 | .Ve | |
420 | .PP | |
421 | .Vb 4 | |
422 | \& s/Joe/Jim/g | |
423 | \& if ($status = filter_read()) > 0 ; | |
424 | \& $status ; | |
425 | \& } | |
426 | .Ve | |
427 | .PP | |
428 | .Vb 1 | |
429 | \& 1 ; | |
430 | .Ve | |
431 | .PP | |
432 | Here is an example of using the filter: | |
433 | .PP | |
434 | .Vb 2 | |
435 | \& use Joe2Jim ; | |
436 | \& print "Where is Joe?\en" ; | |
437 | .Ve | |
438 | .PP | |
439 | And this is what the script above will print: | |
440 | .PP | |
441 | .Vb 1 | |
442 | \& Where is Jim? | |
443 | .Ve | |
444 | .Sh "Example 2: Using the context" | |
445 | .IX Subsection "Example 2: Using the context" | |
446 | The previous example was not particularly useful. To make it more | |
447 | general purpose we will make use of the context data and allow any | |
448 | arbitrary \fIfrom\fR and \fIto\fR strings to be used. This time we will use a | |
449 | \&\fIclosure filter\fR. To reflect its enhanced role, the filter is called | |
450 | \&\f(CW\*(C`Subst\*(C'\fR. | |
451 | .PP | |
452 | .Vb 1 | |
453 | \& package Subst ; | |
454 | .Ve | |
455 | .PP | |
456 | .Vb 2 | |
457 | \& use Filter::Util::Call ; | |
458 | \& use Carp ; | |
459 | .Ve | |
460 | .PP | |
461 | .Vb 15 | |
462 | \& sub import | |
463 | \& { | |
464 | \& croak("usage: use Subst qw(from to)") | |
465 | \& unless @_ == 3 ; | |
466 | \& my ($self, $from, $to) = @_ ; | |
467 | \& filter_add( | |
468 | \& sub | |
469 | \& { | |
470 | \& my ($status) ; | |
471 | \& s/$from/$to/ | |
472 | \& if ($status = filter_read()) > 0 ; | |
473 | \& $status ; | |
474 | \& }) | |
475 | \& } | |
476 | \& 1 ; | |
477 | .Ve | |
478 | .PP | |
479 | and is used like this: | |
480 | .PP | |
481 | .Vb 2 | |
482 | \& use Subst qw(Joe Jim) ; | |
483 | \& print "Where is Joe?\en" ; | |
484 | .Ve | |
485 | .Sh "Example 3: Using the context within the filter" | |
486 | .IX Subsection "Example 3: Using the context within the filter" | |
487 | Here is a filter which a variation of the \f(CW\*(C`Joe2Jim\*(C'\fR filter. As well as | |
488 | substituting all occurrences of \f(CW"Joe"\fR to \f(CW"Jim"\fR it keeps a count | |
489 | of the number of substitutions made in the context object. | |
490 | .PP | |
491 | Once \s-1EOF\s0 is detected (\f(CW$status\fR is zero) the filter will insert an | |
492 | extra line into the source stream. When this extra line is executed it | |
493 | will print a count of the number of substitutions actually made. | |
494 | Note that \f(CW$status\fR is set to \f(CW1\fR in this case. | |
495 | .PP | |
496 | .Vb 1 | |
497 | \& package Count ; | |
498 | .Ve | |
499 | .PP | |
500 | .Vb 1 | |
501 | \& use Filter::Util::Call ; | |
502 | .Ve | |
503 | .PP | |
504 | .Vb 4 | |
505 | \& sub filter | |
506 | \& { | |
507 | \& my ($self) = @_ ; | |
508 | \& my ($status) ; | |
509 | .Ve | |
510 | .PP | |
511 | .Vb 9 | |
512 | \& if (($status = filter_read()) > 0 ) { | |
513 | \& s/Joe/Jim/g ; | |
514 | \& ++ $$self ; | |
515 | \& } | |
516 | \& elsif ($$self >= 0) { # EOF | |
517 | \& $_ = "print q[Made ${$self} substitutions\en]" ; | |
518 | \& $status = 1 ; | |
519 | \& $$self = -1 ; | |
520 | \& } | |
521 | .Ve | |
522 | .PP | |
523 | .Vb 2 | |
524 | \& $status ; | |
525 | \& } | |
526 | .Ve | |
527 | .PP | |
528 | .Vb 6 | |
529 | \& sub import | |
530 | \& { | |
531 | \& my ($self) = @_ ; | |
532 | \& my ($count) = 0 ; | |
533 | \& filter_add(\e$count) ; | |
534 | \& } | |
535 | .Ve | |
536 | .PP | |
537 | .Vb 1 | |
538 | \& 1 ; | |
539 | .Ve | |
540 | .PP | |
541 | Here is a script which uses it: | |
542 | .PP | |
543 | .Vb 3 | |
544 | \& use Count ; | |
545 | \& print "Hello Joe\en" ; | |
546 | \& print "Where is Joe\en" ; | |
547 | .Ve | |
548 | .PP | |
549 | Outputs: | |
550 | .PP | |
551 | .Vb 3 | |
552 | \& Hello Jim | |
553 | \& Where is Jim | |
554 | \& Made 2 substitutions | |
555 | .Ve | |
556 | .Sh "Example 4: Using filter_del" | |
557 | .IX Subsection "Example 4: Using filter_del" | |
558 | Another variation on a theme. This time we will modify the \f(CW\*(C`Subst\*(C'\fR | |
559 | filter to allow a starting and stopping pattern to be specified as well | |
560 | as the \fIfrom\fR and \fIto\fR patterns. If you know the \fIvi\fR editor, it is | |
561 | the equivalent of this command: | |
562 | .PP | |
563 | .Vb 1 | |
564 | \& :/start/,/stop/s/from/to/ | |
565 | .Ve | |
566 | .PP | |
567 | When used as a filter we want to invoke it like this: | |
568 | .PP | |
569 | .Vb 1 | |
570 | \& use NewSubst qw(start stop from to) ; | |
571 | .Ve | |
572 | .PP | |
573 | Here is the module. | |
574 | .PP | |
575 | .Vb 1 | |
576 | \& package NewSubst ; | |
577 | .Ve | |
578 | .PP | |
579 | .Vb 2 | |
580 | \& use Filter::Util::Call ; | |
581 | \& use Carp ; | |
582 | .Ve | |
583 | .PP | |
584 | .Vb 6 | |
585 | \& sub import | |
586 | \& { | |
587 | \& my ($self, $start, $stop, $from, $to) = @_ ; | |
588 | \& my ($found) = 0 ; | |
589 | \& croak("usage: use Subst qw(start stop from to)") | |
590 | \& unless @_ == 5 ; | |
591 | .Ve | |
592 | .PP | |
593 | .Vb 4 | |
594 | \& filter_add( | |
595 | \& sub | |
596 | \& { | |
597 | \& my ($status) ; | |
598 | .Ve | |
599 | .PP | |
600 | .Vb 1 | |
601 | \& if (($status = filter_read()) > 0) { | |
602 | .Ve | |
603 | .PP | |
604 | .Vb 2 | |
605 | \& $found = 1 | |
606 | \& if $found == 0 and /$start/ ; | |
607 | .Ve | |
608 | .PP | |
609 | .Vb 4 | |
610 | \& if ($found) { | |
611 | \& s/$from/$to/ ; | |
612 | \& filter_del() if /$stop/ ; | |
613 | \& } | |
614 | .Ve | |
615 | .PP | |
616 | .Vb 3 | |
617 | \& } | |
618 | \& $status ; | |
619 | \& } ) | |
620 | .Ve | |
621 | .PP | |
622 | .Vb 1 | |
623 | \& } | |
624 | .Ve | |
625 | .PP | |
626 | .Vb 1 | |
627 | \& 1 ; | |
628 | .Ve | |
629 | .SH "Filter::Simple" | |
630 | .IX Header "Filter::Simple" | |
631 | If you intend using the Filter::Call functionality, I would strongly | |
632 | recommend that you check out Damian Conway's excellent Filter::Simple | |
633 | module. Damian's module provides a much cleaner interface than | |
634 | Filter::Util::Call. Although it doesn't allow the fine control that | |
635 | Filter::Util::Call does, it should be adequate for the majority of | |
636 | applications. It's available at | |
637 | .PP | |
638 | .Vb 2 | |
639 | \& http://www.cpan.org/modules/by-author/Damian_Conway/Filter-Simple.tar.gz | |
640 | \& http://www.csse.monash.edu.au/~damian/CPAN/Filter-Simple.tar.gz | |
641 | .Ve | |
642 | .SH "AUTHOR" | |
643 | .IX Header "AUTHOR" | |
644 | Paul Marquess | |
645 | .SH "DATE" | |
646 | .IX Header "DATE" | |
647 | 26th January 1996 |