1Filters(3)            User Contributed Perl Documentation           Filters(3)
2
3
4

NAME

6       Inline::Filters - Common source code filters for Inline Modules.
7

DESCRIPTION

9       "Inline::Filters" provides common source code filters to Inline
10       Language Modules. Unless you're an Inline module developer, you can
11       just read the next section.
12

Supported Filters

14       This section describes each filter in Inline::Filters.
15
16   Strip_POD
17       Strips embedded POD from a block of code in any language. This is
18       implemented as a regular expression:
19
20          $code =~ s/^=\w+[^\n]*\n\n(.*?)(^=cut\n\n|\Z)//gsm;
21
22       That means if you have a language which contains POD-like syntax, it
23       will be stripped by this filter (i.e. don't use this filter with such a
24       language).  This filter is useful for making code like this compile:
25
26          use Inline C => <<'END', FILTERS => 'Strip_POD';
27          =head1 add
28
29          Returns the sum of two integers.
30
31          =cut
32
33          int add(int x, int y) { return x + y; }
34          END
35
36   Strip Comments
37       Strips comments from a block of code in whatever language you are
38       using.  The comment stripper is string-safe -- i.e. it will not strip
39       comments embedded in strings.
40
41       The feature is useful because both the C and C++ grammars cannot deal
42       with comments at arbitrary points in the source code; to do so would
43       bloat the grammar. Instead, code like this should have its comments
44       stripped before parsing:
45
46          use Inline C => <<'END', FILTERS => 'Strip_Comments';
47
48          int md5_block(char *block,   /* the block to operate on */
49                        long length,   /* the number of bytes */
50                        char **result) /* the resulting 128-bit sum */
51          {
52               /* some code here */
53          }
54
55          END
56
57       Strip_Comments is available for the following languages:
58
59       Strip_C_Comments
60       Strip_CPP_Comments
61       Strip_Python_Comments
62       Strip_TCL_Comments
63       Java via Strip_CPP_Comments
64
65       The Python and Java filters are available for convenience only. There
66       is little need for them, since Inline::Python and Inline::Java use the
67       official language compilers to parse the code, and these compilers know
68       about comments.
69
70   Preprocess
71       Now available for all languages. Uses the C pre-processor
72       ($Config{cpprun}) to pre-process a block of code. This is useful if you
73       want to expand macros and conditional code before parsing. For example:
74
75          use Inline CPP => <<'END', FILTERS => 'Preprocess';
76          class Foo
77          #ifdef FOO_INHERITS_BAR
78             : public Bar
79          #endif
80          {
81
82          };
83          END
84
85       The code shown above will not parse correctly without the Preprocess
86       filter, since the Inline::CPP grammar can't understand preprocessor
87       directives.
88
89       CPPFLAGS Argument
90
91       Also available is the CPPFLAGS argument, to specify C preprocessor
92       directives.
93
94           use Inline C => <<'END' => CPPFLAGS => ' -DPREPROCESSOR_DEFINE' => FILTERS => 'Preprocess';
95           #ifdef PREPROCESSOR_DEFINE
96           int foo() { return 4321; }
97           #else
98           int foo() { return -1; }
99           #endif
100           END
101
102       The code shown above will return 4321 when foo() is called.
103
104       CLEAN_AFTER_BUILD Argument
105
106       By default, the Preprocess filter deletes all Filters*.c files it
107       creates.  If you set the CLEAN_AFTER_BUILD flag to false, then the
108       "Filters*.c" files will not be deleted; this is necessary when using
109       "gdb" to debug Inline::C and Inline::CPP programs which utilize the
110       Preprocess filter.
111
112       If you do not set the CLEAN_AFTER_BUILD flag to false, you will likely
113       end up with a "No such file or directory" error in gdb:
114
115           use Inline C => <<'END' => FILTERS => 'Preprocess';
116           // your code here
117           END
118
119       $ gdb /usr/bin/perl (gdb) run ./my_script.pl arg0 arg1 ...  Thread 1
120       "perl" received signal SIGSEGV, Segmentation fault.
121       MyPackage::my_method (this=this@entry=0x1234567,
122       my_arg=my_arg@entry=23)
123           at /.../_Inline/build/eval_XXX_YYYY/FiltersZZZZ.c:42 42
124       /.../_Inline/build/eval_XXX_YYYY/FiltersZZZZ.c: No such file or
125       directory.
126
127       If you do set the CLEAN_AFTER_BUILD flag to false, you should see the
128       actual offending C or C++ code in gdb:
129
130           use Inline C => <<'END' => CLEAN_AFTER_BUILD => 0 => FILTERS => 'Preprocess';
131           // your code here
132           END
133
134       $ gdb /usr/bin/perl (gdb) run ./my_script.pl arg0 arg1 ...  Thread 1
135       "perl" received signal SIGSEGV, Segmentation fault.
136       MyPackage::my_method (this=this@entry=0x1234567,
137       my_arg=my_arg@entry=23)
138           at /.../_Inline/build/eval_XXX_YYYY/FiltersZZZZ.c:42 42    YOU
139       SHOULD SEE YOUR ACTUAL OFFENDING CODE HERE
140

DETAILS

142   Built-in Filters
143       Built-in source code filters are implemented as a blessed reference to
144       a hash containing two elements: 'filter' is the name of the filter, and
145       'coderef' is a code reference to the appropriate filter. The object has
146       a filter() method, which should be called with the ILSM object as the
147       first parameter, and source code as the second parameter. The filters
148       always return the filtered code.
149
150   User-supplied Filters
151       As of Inline 0.42, you can supply your own filters to Inline by passing
152       a code reference to the FILTERS option, like this:
153
154          sub my_filter { };
155          use Inline C => DATA => FILTERS => [\&my_filter];
156
157       The filter sub is passed one argument: the unfiltered code. It must
158       return the filtered code as its only return value. If something goes
159       wrong and you need to pass inform the user, just croak.
160
161       Note: in some circumstances, you must put your filter subroutine above
162       the "use Inline" statement. When possible, Inline compiles your code at
163       compile time, meaning the subroutine must be defined. If you're reading
164       code from the 'DATA' filehandle, you can put the filter anywhere in
165       your script, since Inline delays compilation until runtime.
166
167   Applying Filters
168       "Inline" provides a filter() method which applies the requested filters
169       one after the other on the source code. All ILSMs should save the
170       result of $o->filter() and consider it the source code. If no filters
171       have been requested, this just returns the unfiltered source code.
172
173   filter (object, coderef) METHOD
174   new (filter, coderef) METHOD
175   get_filters (language) FUNCTION
176       returns all supported languages
177

SEE ALSO

179       For more information about specifying Inline source code filters, see
180       Inline::C or Inline::CPP.
181
182       For more information about using other languages inside Perl, see
183       Inline.  For more information about using C from Perl, see Inline::C.
184

BUGS OR OMISSIONS

186       You can pass in arbitrary subroutine references as filters. However, if
187       you find yourself using a filter on a regular basis and you'd like to
188       see it included in Inline::Filters, please file a bug report.
189
190       If you wish to report a bug, please refer to Inline for instructions on
191       how to submit a bug report.
192
193       <https://rt.cpan.org/Public/Dist/Display.html?Name=Inline-Filters>
194

AUTHOR

196       Neil Watkiss (NEILW@cpan.org) Reini Urban (RURBAN@cpan.org) Will
197       Braswell (WBRASWELL@cpan.org)
198
199       Maintained now by the perl11 team:
200       https://github.com/perl11/Inline-Filters
201
203       Copyright (C) 2001, Neil Watkiss.  Copyright (C) 2014, 2015 Reini Urban
204       & Will Braswell.
205
206       This module is free software. It may be used, redistributed and/or
207       modified under the same terms as Perl itself.
208
209       See <http://dev.perl.org/licenses/>.
210
211
212
213perl v5.30.1                      2020-01-30                        Filters(3)
Impressum