{ "mode": "perldoc", "parameter": "Filter::Util::Call", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/Filter%3A%3AUtil%3A%3ACall/json", "generated": "2026-06-10T01:05:55Z", "synopsis": "use Filter::Util::Call ;", "sections": { "NAME": { "content": "Filter::Util::Call - Perl Source Filter Utility Module\n", "subsections": [] }, "SYNOPSIS": { "content": "use Filter::Util::Call ;\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides you with the framework to write *Source Filters* in Perl.\n\nAn alternate interface to Filter::Util::Call is now available. See Filter::Simple for more\ndetails.\n\nA *Perl Source Filter* is implemented as a Perl module. The structure of the module can take one\nof two broadly similar formats. To distinguish between them, the first will be referred to as\n*method filter* and the second as *closure filter*.\n\nHere is a skeleton for the *method filter*:\n\npackage MyFilter ;\n\nuse Filter::Util::Call ;\n\nsub import\n{\nmy($type, @arguments) = @ ;\nfilteradd([]) ;\n}\n\nsub filter\n{\nmy($self) = @ ;\nmy($status) ;\n\n$status = filterread() ;\n$status ;\n}\n\n1 ;\n\nand this is the equivalent skeleton for the *closure filter*:\n\npackage MyFilter ;\n\nuse Filter::Util::Call ;\n\nsub import\n{\nmy($type, @arguments) = @ ;\n\nfilteradd(\nsub\n{\nmy($status) ;\n$status = filterread() ;\n$status ;\n} )\n}\n\n1 ;\n\nTo make use of either of the two filter modules above, place the line below in a Perl source\nfile.\n\nuse MyFilter;\n\nIn fact, the skeleton modules shown above are fully functional *Source Filters*, albeit fairly\nuseless ones. All they does is filter the source stream without modifying it at all.\n\nAs you can see both modules have a broadly similar structure. They both make use of the\n\"Filter::Util::Call\" module and both have an \"import\" method. The difference between them is\nthat the *method filter* requires a *filter* method, whereas the *closure filter* gets the\nequivalent of a *filter* method with the anonymous sub passed to *filteradd*.\n\nTo make proper use of the *closure filter* shown above you need to have a good understanding of\nthe concept of a *closure*. See perlref for more details on the mechanics of *closures*.\n\nuse Filter::Util::Call\nThe following functions are exported by \"Filter::Util::Call\":\n\nfilteradd()\nfilterread()\nfilterreadexact()\nfilterdel()\n\nimport()\nThe \"import\" method is used to create an instance of the filter. It is called indirectly by Perl\nwhen it encounters the \"use MyFilter\" line in a source file (See \"import\" in perlfunc for more\ndetails on \"import\").\n\nIt will always have at least one parameter automatically passed by Perl - this corresponds to\nthe name of the package. In the example above it will be \"MyFilter\".\n\nApart from the first parameter, import can accept an optional list of parameters. These can be\nused to pass parameters to the filter. For example:\n\nuse MyFilter qw(a b c) ;\n\nwill result in the @ array having the following values:\n\n@ [0] => \"MyFilter\"\n@ [1] => \"a\"\n@ [2] => \"b\"\n@ [3] => \"c\"\n\nBefore terminating, the \"import\" function must explicitly install the filter by calling\n\"filteradd\".\n\nfilteradd()\nThe function, \"filteradd\", actually installs the filter. It takes one parameter which should be\na reference. The kind of reference used will dictate which of the two filter types will be used.\n\nIf a CODE reference is used then a *closure filter* will be assumed.\n\nIf a CODE reference is not used, a *method filter* will be assumed. In a *method filter*, the\nreference can be used to store context information. The reference will be *blessed* into the\npackage by \"filteradd\", unless the reference was already blessed.\n\nSee the filters at the end of this documents for examples of using context information using\nboth *method filters* and *closure filters*.\n\nfilter() and anonymous sub\nBoth the \"filter\" method used with a *method filter* and the anonymous sub used with a *closure\nfilter* is where the main processing for the filter is done.\n\nThe big difference between the two types of filter is that the *method filter* uses the object\npassed to the method to store any context data, whereas the *closure filter* uses the lexical\nvariables that are maintained by the closure.\n\nNote that the single parameter passed to the *method filter*, $self, is the same reference that\nwas passed to \"filteradd\" blessed into the filter's package. See the example filters later on\nfor details of using $self.\n\nHere is a list of the common features of the anonymous sub and the \"filter()\" method.\n\n$ Although $ doesn't actually appear explicitly in the sample filters above, it is\nimplicitly used in a number of places.\n\nFirstly, when either \"filter\" or the anonymous sub are called, a local copy of $ will\nautomatically be created. It will always contain the empty string at this point.\n\nNext, both \"filterread\" and \"filterreadexact\" will append any source data that is read\nto the end of $.\n\nFinally, when \"filter\" or the anonymous sub are finished processing, they are expected to\nreturn the filtered source using $.\n\nThis implicit use of $ greatly simplifies the filter.\n\n$status\nThe status value that is returned by the user's \"filter\" method or anonymous sub and the\n\"filterread\" and \"readexact\" functions take the same set of values, namely:\n\n< 0 Error\n= 0 EOF\n> 0 OK\n\nfilterread and filterreadexact\nThese functions are used by the filter to obtain either a line or block from the next\nfilter in the chain or the actual source file if there aren't any other filters.\n\nThe function \"filterread\" takes two forms:\n\n$status = filterread() ;\n$status = filterread($size) ;\n\nThe first form is used to request a *line*, the second requests a *block*.\n\nIn line mode, \"filterread\" will append the next source line to the end of the $ scalar.\n\nIn block mode, \"filterread\" will append a block of data which is <= $size to the end of\nthe $ scalar. It is important to emphasise the that \"filterread\" will not necessarily\nread a block which is *precisely* $size bytes.\n\nIf you need to be able to read a block which has an exact size, you can use the function\n\"filterreadexact\". It works identically to \"filterread\" in block mode, except it will\ntry to read a block which is exactly $size bytes in length. The only circumstances when it\nwill not return a block which is $size bytes long is on EOF or error.\n\nIt is *very* important to check the value of $status after *every* call to \"filterread\" or\n\"filterreadexact\".\n\nfilterdel\nThe function, \"filterdel\", is used to disable the current filter. It does not affect the\nrunning of the filter. All it does is tell Perl not to call filter any more.\n\nSee \"Example 4: Using filterdel\" for details.\n\n*realimport*\nInternal function which adds the filter, based on the filteradd argument type.\n\n*unimport()*\nMay be used to disable a filter, but is rarely needed. See filterdel.\n", "subsections": [] }, "LIMITATIONS": { "content": "See \"LIMITATIONS\" in perlfilter for an overview of the general problems filtering code in a\ntextual line-level only.\n\nDATA is ignored\nThe content from the DATA block is not filtered. This is a serious limitation, e.g. for\nthe Switch module. See for more.\n\nMax. codesize limited to 32-bit\nCurrently internal buffer lengths are limited to 32-bit only.\n", "subsections": [] }, "EXAMPLES": { "content": "Here are a few examples which illustrate the key concepts - as such most of them are of little\npractical use.\n\nThe \"examples\" sub-directory has copies of all these filters implemented both as *method\nfilters* and as *closure filters*.\n", "subsections": [ { "name": "Example 1: A simple filter.", "content": "Below is a *method filter* which is hard-wired to replace all occurrences of the string \"Joe\" to\n\"Jim\". Not particularly Useful, but it is the first example and I wanted to keep it simple.\n\npackage Joe2Jim ;\n\nuse Filter::Util::Call ;\n\nsub import\n{\nmy($type) = @ ;\n\nfilteradd(bless []) ;\n}\n\nsub filter\n{\nmy($self) = @ ;\nmy($status) ;\n\ns/Joe/Jim/g\nif ($status = filterread()) > 0 ;\n$status ;\n}\n\n1 ;\n\nHere is an example of using the filter:\n\nuse Joe2Jim ;\nprint \"Where is Joe?\\n\" ;\n\nAnd this is what the script above will print:\n\nWhere is Jim?\n" }, { "name": "Example 2: Using the context", "content": "The previous example was not particularly useful. To make it more general purpose we will make\nuse of the context data and allow any arbitrary *from* and *to* strings to be used. This time we\nwill use a *closure filter*. To reflect its enhanced role, the filter is called \"Subst\".\n\npackage Subst ;\n\nuse Filter::Util::Call ;\nuse Carp ;\n\nsub import\n{\ncroak(\"usage: use Subst qw(from to)\")\nunless @ == 3 ;\nmy ($self, $from, $to) = @ ;\nfilteradd(\nsub\n{\nmy ($status) ;\ns/$from/$to/\nif ($status = filterread()) > 0 ;\n$status ;\n})\n}\n1 ;\n\nand is used like this:\n\nuse Subst qw(Joe Jim) ;\nprint \"Where is Joe?\\n\" ;\n" }, { "name": "Example 3: Using the context within the filter", "content": "Here is a filter which a variation of the \"Joe2Jim\" filter. As well as substituting all\noccurrences of \"Joe\" to \"Jim\" it keeps a count of the number of substitutions made in the\ncontext object.\n\nOnce EOF is detected ($status is zero) the filter will insert an extra line into the source\nstream. When this extra line is executed it will print a count of the number of substitutions\nactually made. Note that $status is set to 1 in this case.\n\npackage Count ;\n\nuse Filter::Util::Call ;\n\nsub filter\n{\nmy ($self) = @ ;\nmy ($status) ;\n\nif (($status = filterread()) > 0 ) {\ns/Joe/Jim/g ;\n++ $$self ;\n}\nelsif ($$self >= 0) { # EOF\n$ = \"print q[Made ${$self} substitutions\\n]\" ;\n$status = 1 ;\n$$self = -1 ;\n}\n\n$status ;\n}\n\nsub import\n{\nmy ($self) = @ ;\nmy ($count) = 0 ;\nfilteradd(\\$count) ;\n}\n\n1 ;\n\nHere is a script which uses it:\n\nuse Count ;\nprint \"Hello Joe\\n\" ;\nprint \"Where is Joe\\n\" ;\n\nOutputs:\n\nHello Jim\nWhere is Jim\nMade 2 substitutions\n" }, { "name": "Example 4: Using filterdel", "content": "Another variation on a theme. This time we will modify the \"Subst\" filter to allow a starting\nand stopping pattern to be specified as well as the *from* and *to* patterns. If you know the\n*vi* editor, it is the equivalent of this command:\n\n:/start/,/stop/s/from/to/\n\nWhen used as a filter we want to invoke it like this:\n\nuse NewSubst qw(start stop from to) ;\n\nHere is the module.\n\npackage NewSubst ;\n\nuse Filter::Util::Call ;\nuse Carp ;\n\nsub import\n{\nmy ($self, $start, $stop, $from, $to) = @ ;\nmy ($found) = 0 ;\ncroak(\"usage: use Subst qw(start stop from to)\")\nunless @ == 5 ;\n\nfilteradd(\nsub\n{\nmy ($status) ;\n\nif (($status = filterread()) > 0) {\n\n$found = 1\nif $found == 0 and /$start/ ;\n\nif ($found) {\ns/$from/$to/ ;\nfilterdel() if /$stop/ ;\n}\n\n}\n$status ;\n} )\n\n}\n\n1 ;\n" } ] }, "Filter::Simple": { "content": "If you intend using the Filter::Call functionality, I would strongly recommend that you check\nout Damian Conway's excellent Filter::Simple module. Damian's module provides a much cleaner\ninterface than Filter::Util::Call. Although it doesn't allow the fine control that\nFilter::Util::Call does, it should be adequate for the majority of applications. It's available\nat\n\nhttp://search.cpan.org/dist/Filter-Simple/\n", "subsections": [] }, "AUTHOR": { "content": "Paul Marquess\n", "subsections": [] }, "DATE": { "content": "26th January 1996\n", "subsections": [] }, "LICENSE": { "content": "Copyright (c) 1995-2011 Paul Marquess. All rights reserved. Copyright (c) 2011-2014 Reini Urban.\nAll rights reserved. Copyright (c) 2014-2017 cPanel Inc. All rights reserved.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] } }, "summary": "Filter::Util::Call - Perl Source Filter Utility Module", "flags": [], "examples": [ "Here are a few examples which illustrate the key concepts - as such most of them are of little", "practical use.", "The \"examples\" sub-directory has copies of all these filters implemented both as *method", "filters* and as *closure filters*.", "Below is a *method filter* which is hard-wired to replace all occurrences of the string \"Joe\" to", "\"Jim\". Not particularly Useful, but it is the first example and I wanted to keep it simple.", "package Joe2Jim ;", "use Filter::Util::Call ;", "sub import", "my($type) = @ ;", "filteradd(bless []) ;", "sub filter", "my($self) = @ ;", "my($status) ;", "s/Joe/Jim/g", "if ($status = filterread()) > 0 ;", "$status ;", "1 ;", "Here is an example of using the filter:", "use Joe2Jim ;", "print \"Where is Joe?\\n\" ;", "And this is what the script above will print:", "Where is Jim?", "The previous example was not particularly useful. To make it more general purpose we will make", "use of the context data and allow any arbitrary *from* and *to* strings to be used. This time we", "will use a *closure filter*. To reflect its enhanced role, the filter is called \"Subst\".", "package Subst ;", "use Filter::Util::Call ;", "use Carp ;", "sub import", "croak(\"usage: use Subst qw(from to)\")", "unless @ == 3 ;", "my ($self, $from, $to) = @ ;", "filteradd(", "sub", "my ($status) ;", "s/$from/$to/", "if ($status = filterread()) > 0 ;", "$status ;", "})", "1 ;", "and is used like this:", "use Subst qw(Joe Jim) ;", "print \"Where is Joe?\\n\" ;", "Here is a filter which a variation of the \"Joe2Jim\" filter. As well as substituting all", "occurrences of \"Joe\" to \"Jim\" it keeps a count of the number of substitutions made in the", "context object.", "Once EOF is detected ($status is zero) the filter will insert an extra line into the source", "stream. When this extra line is executed it will print a count of the number of substitutions", "actually made. Note that $status is set to 1 in this case.", "package Count ;", "use Filter::Util::Call ;", "sub filter", "my ($self) = @ ;", "my ($status) ;", "if (($status = filterread()) > 0 ) {", "s/Joe/Jim/g ;", "++ $$self ;", "elsif ($$self >= 0) { # EOF", "$ = \"print q[Made ${$self} substitutions\\n]\" ;", "$status = 1 ;", "$$self = -1 ;", "$status ;", "sub import", "my ($self) = @ ;", "my ($count) = 0 ;", "filteradd(\\$count) ;", "1 ;", "Here is a script which uses it:", "use Count ;", "print \"Hello Joe\\n\" ;", "print \"Where is Joe\\n\" ;", "Outputs:", "Hello Jim", "Where is Jim", "Made 2 substitutions", "Another variation on a theme. This time we will modify the \"Subst\" filter to allow a starting", "and stopping pattern to be specified as well as the *from* and *to* patterns. If you know the", "*vi* editor, it is the equivalent of this command:", ":/start/,/stop/s/from/to/", "When used as a filter we want to invoke it like this:", "use NewSubst qw(start stop from to) ;", "Here is the module.", "package NewSubst ;", "use Filter::Util::Call ;", "use Carp ;", "sub import", "my ($self, $start, $stop, $from, $to) = @ ;", "my ($found) = 0 ;", "croak(\"usage: use Subst qw(start stop from to)\")", "unless @ == 5 ;", "filteradd(", "sub", "my ($status) ;", "if (($status = filterread()) > 0) {", "$found = 1", "if $found == 0 and /$start/ ;", "if ($found) {", "s/$from/$to/ ;", "filterdel() if /$stop/ ;", "$status ;", "} )", "1 ;" ], "see_also": [] }