Debian Codegraph @

upstream/mageia-cauldron/man3pm/Filter::Util::Call.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Filter::Util::Call 3pm"
61 .TH Filter::Util::Call 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Filter::Util::Call \- Perl Source Filter Utility Module
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Filter::Util::Call ;
72 .Ve
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 This module provides you with the framework to write \fISource Filters\fR
76 in Perl.
77 .PP
78 An alternate interface to Filter::Util::Call is now available. See
79 Filter::Simple for more details.
80 .PP
81 A \fIPerl Source Filter\fR is implemented as a Perl module. The structure
82 of the module can take one of two broadly similar formats. To
83 distinguish between them, the first will be referred to as \fImethod
84 filter\fR and the second as \fIclosure filter\fR.
85 .PP
86 Here is a skeleton for the \fImethod filter\fR:
87 .PP
88 .Vb 1
89 \& package MyFilter ;
90 \&
91 \& use Filter::Util::Call ;
92 \&
93 \& sub import
94 \& {
95 \& my($type, @arguments) = @_ ;
96 \& filter_add([]) ;
97 \& }
98 \&
99 \& sub filter
100 \& {
101 \& my($self) = @_ ;
102 \& my($status) ;
103 \&
104 \& $status = filter_read() ;
105 \& $status ;
106 \& }
107 \&
108 \& 1 ;
109 .Ve
110 .PP
111 and this is the equivalent skeleton for the \fIclosure filter\fR:
112 .PP
113 .Vb 1
114 \& package MyFilter ;
115 \&
116 \& use Filter::Util::Call ;
117 \&
118 \& sub import
119 \& {
120 \& my($type, @arguments) = @_ ;
121 \&
122 \& filter_add(
123 \& sub
124 \& {
125 \& my($status) ;
126 \& $status = filter_read() ;
127 \& $status ;
128 \& } )
129 \& }
130 \&
131 \& 1 ;
132 .Ve
133 .PP
134 To make use of either of the two filter modules above, place the line
135 below in a Perl source file.
136 .PP
137 .Vb 1
138 \& use MyFilter;
139 .Ve
140 .PP
141 In fact, the skeleton modules shown above are fully functional \fISource
142 Filters\fR, albeit fairly useless ones. All they does is filter the
143 source stream without modifying it at all.
144 .PP
145 As you can see both modules have a broadly similar structure. They both
146 make use of the \f(CW\*(C`Filter::Util::Call\*(C'\fR module and both have an \f(CW\*(C`import\*(C'\fR
147 method. The difference between them is that the \fImethod filter\fR
148 requires a \fIfilter\fR method, whereas the \fIclosure filter\fR gets the
149 equivalent of a \fIfilter\fR method with the anonymous sub passed to
150 \&\fIfilter_add\fR.
151 .PP
152 To make proper use of the \fIclosure filter\fR shown above you need to
153 have a good understanding of the concept of a \fIclosure\fR. See
154 perlref for more details on the mechanics of \fIclosures\fR.
155 .SS "\fBuse Filter::Util::Call\fP"
156 .IX Subsection "use Filter::Util::Call"
157 The following functions are exported by \f(CW\*(C`Filter::Util::Call\*(C'\fR:
158 .PP
159 .Vb 4
160 \& filter_add()
161 \& filter_read()
162 \& filter_read_exact()
163 \& filter_del()
164 .Ve
165 .SS \fBimport()\fP
166 .IX Subsection "import()"
167 The \f(CW\*(C`import\*(C'\fR method is used to create an instance of the filter. It is
168 called indirectly by Perl when it encounters the \f(CW\*(C`use MyFilter\*(C'\fR line
169 in a source file (See "import" in perlfunc for more details on
170 \&\f(CW\*(C`import\*(C'\fR).
171 .PP
172 It will always have at least one parameter automatically passed by Perl
173 \&\- this corresponds to the name of the package. In the example above it
174 will be \f(CW"MyFilter"\fR.
175 .PP
176 Apart from the first parameter, import can accept an optional list of
177 parameters. These can be used to pass parameters to the filter. For
178 example:
179 .PP
180 .Vb 1
181 \& use MyFilter qw(a b c) ;
182 .Ve
183 .PP
184 will result in the \f(CW@_\fR array having the following values:
185 .PP
186 .Vb 4
187 \& @_ [0] => "MyFilter"
188 \& @_ [1] => "a"
189 \& @_ [2] => "b"
190 \& @_ [3] => "c"
191 .Ve
192 .PP
193 Before terminating, the \f(CW\*(C`import\*(C'\fR function must explicitly install the
194 filter by calling \f(CW\*(C`filter_add\*(C'\fR.
195 .SS \fBfilter_add()\fP
196 .IX Subsection "filter_add()"
197 The function, \f(CW\*(C`filter_add\*(C'\fR, actually installs the filter. It takes one
198 parameter which should be a reference. The kind of reference used will
199 dictate which of the two filter types will be used.
200 .PP
201 If a CODE reference is used then a \fIclosure filter\fR will be assumed.
202 .PP
203 If a CODE reference is not used, a \fImethod filter\fR will be assumed.
204 In a \fImethod filter\fR, the reference can be used to store context
205 information. The reference will be \fIblessed\fR into the package by
206 \&\f(CW\*(C`filter_add\*(C'\fR, unless the reference was already blessed.
207 .PP
208 See the filters at the end of this documents for examples of using
209 context information using both \fImethod filters\fR and \fIclosure
210 filters\fR.
211 .SS "\fBfilter() and anonymous sub\fP"
212 .IX Subsection "filter() and anonymous sub"
213 Both the \f(CW\*(C`filter\*(C'\fR method used with a \fImethod filter\fR and the
214 anonymous sub used with a \fIclosure filter\fR is where the main
215 processing for the filter is done.
216 .PP
217 The big difference between the two types of filter is that the \fImethod
218 filter\fR uses the object passed to the method to store any context data,
219 whereas the \fIclosure filter\fR uses the lexical variables that are
220 maintained by the closure.
221 .PP
222 Note that the single parameter passed to the \fImethod filter\fR,
223 \&\f(CW$self\fR, is the same reference that was passed to \f(CW\*(C`filter_add\*(C'\fR
224 blessed into the filter\*(Aqs package. See the example filters later on for
225 details of using \f(CW$self\fR.
226 .PP
227 Here is a list of the common features of the anonymous sub and the
228 \&\f(CWfilter()\fR method.
229 .ie n .IP \fR\fB$_\fR\fB\fR 5
230 .el .IP \fR\f(CB$_\fR\fB\fR 5
231 .IX Item "$_"
232 Although \f(CW$_\fR doesn\*(Aqt actually appear explicitly in the sample filters
233 above, it is implicitly used in a number of places.
234 .Sp
235 Firstly, when either \f(CW\*(C`filter\*(C'\fR or the anonymous sub are called, a local
236 copy of \f(CW$_\fR will automatically be created. It will always contain the
237 empty string at this point.
238 .Sp
239 Next, both \f(CW\*(C`filter_read\*(C'\fR and \f(CW\*(C`filter_read_exact\*(C'\fR will append any
240 source data that is read to the end of \f(CW$_\fR.
241 .Sp
242 Finally, when \f(CW\*(C`filter\*(C'\fR or the anonymous sub are finished processing,
243 they are expected to return the filtered source using \f(CW$_\fR.
244 .Sp
245 This implicit use of \f(CW$_\fR greatly simplifies the filter.
246 .ie n .IP \fR\fB$status\fR\fB\fR 5
247 .el .IP \fR\f(CB$status\fR\fB\fR 5
248 .IX Item "$status"
249 The status value that is returned by the user\*(Aqs \f(CW\*(C`filter\*(C'\fR method or
250 anonymous sub and the \f(CW\*(C`filter_read\*(C'\fR and \f(CW\*(C`read_exact\*(C'\fR functions take
251 the same set of values, namely:
252 .Sp
253 .Vb 3
254 \& < 0 Error
255 \& = 0 EOF
256 \& > 0 OK
257 .Ve
258 .IP "\fBfilter_read\fR and \fBfilter_read_exact\fR" 5
259 .IX Item "filter_read and filter_read_exact"
260 These functions are used by the filter to obtain either a line or block
261 from the next filter in the chain or the actual source file if there
262 aren\*(Aqt any other filters.
263 .Sp
264 The function \f(CW\*(C`filter_read\*(C'\fR takes two forms:
265 .Sp
266 .Vb 2
267 \& $status = filter_read() ;
268 \& $status = filter_read($size) ;
269 .Ve
270 .Sp
271 The first form is used to request a \fIline\fR, the second requests a
272 \&\fIblock\fR.
273 .Sp
274 In line mode, \f(CW\*(C`filter_read\*(C'\fR will append the next source line to the
275 end of the \f(CW$_\fR scalar.
276 .Sp
277 In block mode, \f(CW\*(C`filter_read\*(C'\fR will append a block of data which is <=
278 \&\f(CW$size\fR to the end of the \f(CW$_\fR scalar. It is important to emphasise
279 the that \f(CW\*(C`filter_read\*(C'\fR will not necessarily read a block which is
280 \&\fIprecisely\fR \f(CW$size\fR bytes.
281 .Sp
282 If you need to be able to read a block which has an exact size, you can
283 use the function \f(CW\*(C`filter_read_exact\*(C'\fR. It works identically to
284 \&\f(CW\*(C`filter_read\*(C'\fR in block mode, except it will try to read a block which
285 is exactly \f(CW$size\fR bytes in length. The only circumstances when it
286 will not return a block which is \f(CW$size\fR bytes long is on EOF or
287 error.
288 .Sp
289 It is \fIvery\fR important to check the value of \f(CW$status\fR after \fIevery\fR
290 call to \f(CW\*(C`filter_read\*(C'\fR or \f(CW\*(C`filter_read_exact\*(C'\fR.
291 .IP \fBfilter_del\fR 5
292 .IX Item "filter_del"
293 The function, \f(CW\*(C`filter_del\*(C'\fR, is used to disable the current filter. It
294 does not affect the running of the filter. All it does is tell Perl not
295 to call filter any more.
296 .Sp
297 See "Example 4: Using filter_del" for details.
298 .IP \fIreal_import\fR 5
299 .IX Item "real_import"
300 Internal function which adds the filter, based on the filter_add
301 argument type.
302 .IP \fR\f(BIunimport()\fR\fI\fR 5
303 .IX Item "unimport()"
304 May be used to disable a filter, but is rarely needed. See filter_del.
305 .SH LIMITATIONS
306 .IX Header "LIMITATIONS"
307 See "LIMITATIONS" in perlfilter for an overview of the general problems
308 filtering code in a textual line\-level only.
309 .IP "_\|_DATA_\|_ is ignored" 4
310 .IX Item "__DATA__ is ignored"
311 The content from the _\|_DATA_\|_ block is not filtered.
312 This is a serious limitation, e.g. for the Switch module.
313 See <http://search.cpan.org/perldoc?Switch#LIMITATIONS> for more.
314 .IP "Max. codesize limited to 32\-bit" 4
315 .IX Item "Max. codesize limited to 32-bit"
316 Currently internal buffer lengths are limited to 32\-bit only.
317 .SH EXAMPLES
318 .IX Header "EXAMPLES"
319 Here are a few examples which illustrate the key concepts \- as such
320 most of them are of little practical use.
321 .PP
322 The \f(CW\*(C`examples\*(C'\fR sub\-directory has copies of all these filters
323 implemented both as \fImethod filters\fR and as \fIclosure filters\fR.
324 .SS "Example 1: A simple filter."
325 .IX Subsection "Example 1: A simple filter."
326 Below is a \fImethod filter\fR which is hard\-wired to replace all
327 occurrences of the string \f(CW"Joe"\fR to \f(CW"Jim"\fR. Not particularly
328 Useful, but it is the first example and I wanted to keep it simple.
329 .PP
330 .Vb 1
331 \& package Joe2Jim ;
332 \&
333 \& use Filter::Util::Call ;
334 \&
335 \& sub import
336 \& {
337 \& my($type) = @_ ;
338 \&
339 \& filter_add(bless []) ;
340 \& }
341 \&
342 \& sub filter
343 \& {
344 \& my($self) = @_ ;
345 \& my($status) ;
346 \&
347 \& s/Joe/Jim/g
348 \& if ($status = filter_read()) > 0 ;
349 \& $status ;
350 \& }
351 \&
352 \& 1 ;
353 .Ve
354 .PP
355 Here is an example of using the filter:
356 .PP
357 .Vb 2
358 \& use Joe2Jim ;
359 \& print "Where is Joe?\en" ;
360 .Ve
361 .PP
362 And this is what the script above will print:
363 .PP
364 .Vb 1
365 \& Where is Jim?
366 .Ve
367 .SS "Example 2: Using the context"
368 .IX Subsection "Example 2: Using the context"
369 The previous example was not particularly useful. To make it more
370 general purpose we will make use of the context data and allow any
371 arbitrary \fIfrom\fR and \fIto\fR strings to be used. This time we will use a
372 \&\fIclosure filter\fR. To reflect its enhanced role, the filter is called
373 \&\f(CW\*(C`Subst\*(C'\fR.
374 .PP
375 .Vb 1
376 \& package Subst ;
377 \&
378 \& use Filter::Util::Call ;
379 \& use Carp ;
380 \&
381 \& sub import
382 \& {
383 \& croak("usage: use Subst qw(from to)")
384 \& unless @_ == 3 ;
385 \& my ($self, $from, $to) = @_ ;
386 \& filter_add(
387 \& sub
388 \& {
389 \& my ($status) ;
390 \& s/$from/$to/
391 \& if ($status = filter_read()) > 0 ;
392 \& $status ;
393 \& })
394 \& }
395 \& 1 ;
396 .Ve
397 .PP
398 and is used like this:
399 .PP
400 .Vb 2
401 \& use Subst qw(Joe Jim) ;
402 \& print "Where is Joe?\en" ;
403 .Ve
404 .SS "Example 3: Using the context within the filter"
405 .IX Subsection "Example 3: Using the context within the filter"
406 Here is a filter which a variation of the \f(CW\*(C`Joe2Jim\*(C'\fR filter. As well as
407 substituting all occurrences of \f(CW"Joe"\fR to \f(CW"Jim"\fR it keeps a count
408 of the number of substitutions made in the context object.
409 .PP
410 Once EOF is detected (\f(CW$status\fR is zero) the filter will insert an
411 extra line into the source stream. When this extra line is executed it
412 will print a count of the number of substitutions actually made.
413 Note that \f(CW$status\fR is set to \f(CW1\fR in this case.
414 .PP
415 .Vb 1
416 \& package Count ;
417 \&
418 \& use Filter::Util::Call ;
419 \&
420 \& sub filter
421 \& {
422 \& my ($self) = @_ ;
423 \& my ($status) ;
424 \&
425 \& if (($status = filter_read()) > 0 ) {
426 \& s/Joe/Jim/g ;
427 \& ++ $$self ;
428 \& }
429 \& elsif ($$self >= 0) { # EOF
430 \& $_ = "print q[Made ${$self} substitutions\en]" ;
431 \& $status = 1 ;
432 \& $$self = \-1 ;
433 \& }
434 \&
435 \& $status ;
436 \& }
437 \&
438 \& sub import
439 \& {
440 \& my ($self) = @_ ;
441 \& my ($count) = 0 ;
442 \& filter_add(\e$count) ;
443 \& }
444 \&
445 \& 1 ;
446 .Ve
447 .PP
448 Here is a script which uses it:
449 .PP
450 .Vb 3
451 \& use Count ;
452 \& print "Hello Joe\en" ;
453 \& print "Where is Joe\en" ;
454 .Ve
455 .PP
456 Outputs:
457 .PP
458 .Vb 3
459 \& Hello Jim
460 \& Where is Jim
461 \& Made 2 substitutions
462 .Ve
463 .SS "Example 4: Using filter_del"
464 .IX Subsection "Example 4: Using filter_del"
465 Another variation on a theme. This time we will modify the \f(CW\*(C`Subst\*(C'\fR
466 filter to allow a starting and stopping pattern to be specified as well
467 as the \fIfrom\fR and \fIto\fR patterns. If you know the \fIvi\fR editor, it is
468 the equivalent of this command:
469 .PP
470 .Vb 1
471 \& :/start/,/stop/s/from/to/
472 .Ve
473 .PP
474 When used as a filter we want to invoke it like this:
475 .PP
476 .Vb 1
477 \& use NewSubst qw(start stop from to) ;
478 .Ve
479 .PP
480 Here is the module.
481 .PP
482 .Vb 1
483 \& package NewSubst ;
484 \&
485 \& use Filter::Util::Call ;
486 \& use Carp ;
487 \&
488 \& sub import
489 \& {
490 \& my ($self, $start, $stop, $from, $to) = @_ ;
491 \& my ($found) = 0 ;
492 \& croak("usage: use Subst qw(start stop from to)")
493 \& unless @_ == 5 ;
494 \&
495 \& filter_add(
496 \& sub
497 \& {
498 \& my ($status) ;
499 \&
500 \& if (($status = filter_read()) > 0) {
501 \&
502 \& $found = 1
503 \& if $found == 0 and /$start/ ;
504 \&
505 \& if ($found) {
506 \& s/$from/$to/ ;
507 \& filter_del() if /$stop/ ;
508 \& }
509 \&
510 \& }
511 \& $status ;
512 \& } )
513 \&
514 \& }
515 \&
516 \& 1 ;
517 .Ve
518 .SH Filter::Simple
519 .IX Header "Filter::Simple"
520 If you intend using the Filter::Call functionality, I would strongly
521 recommend that you check out Damian Conway\*(Aqs excellent Filter::Simple
522 module. Damian\*(Aqs module provides a much cleaner interface than
523 Filter::Util::Call. Although it doesn\*(Aqt allow the fine control that
524 Filter::Util::Call does, it should be adequate for the majority of
525 applications. It\*(Aqs available at
526 .PP
527 .Vb 1
528 \& http://search.cpan.org/dist/Filter\-Simple/
529 .Ve
530 .SH AUTHOR
531 .IX Header "AUTHOR"
532 Paul Marquess
533 .SH DATE
534 .IX Header "DATE"
535 26th January 1996
536 .SH LICENSE
537 .IX Header "LICENSE"
538 Copyright (c) 1995\-2011 Paul Marquess. All rights reserved.
539 Copyright (c) 2011\-2014, 2018\-2022 Reini Urban. All rights reserved.
540 Copyright (c) 2014\-2017 cPanel Inc. All rights reserved.
541 .PP
542 This program is free software; you can redistribute it and/or
543 modify it under the same terms as Perl itself.