1Filters(3) User Contributed Perl Documentation Filters(3)
2
6 Inline::Filters - Common source code filters for Inline Modules.
7
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
14 This section describes each filter in Inline::Filters.
15 Strip_POD
17 Strips embedded POD from a block of code in any language. This is
18 implemented as a regular expression:
19 $code =~ s/^=\w+[^\n]*\n\n(.*?)(^=cut\n\n|\Z)//gsm;
21 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 use Inline C => <<'END', FILTERS => 'Strip_POD';
27 =head1 add
28 Returns the sum of two integers.
30 =cut
32 int add(int x, int y) { return x + y; }
34 END
35 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 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 use Inline C => <<'END', FILTERS => 'Strip_Comments';
47 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 END
56 Strip_Comments is available for the following languages:
58 Strip_C_Comments
60 Strip_CPP_Comments
61 Strip_Python_Comments
62 Strip_TCL_Comments
63 Java via Strip_CPP_Comments
64 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 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 use Inline CPP => <<'END', FILTERS => 'Preprocess';
76 class Foo
77 #ifdef FOO_INHERITS_BAR
78 : public Bar
79 #endif
80 {
81 };
83 END
84 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 CPPFLAGS Argument
90 Also available is the CPPFLAGS argument, to specify C preprocessor
92 directives.
93 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 The code shown above will return 4321 when foo() is called.
103 CLEAN_AFTER_BUILD Argument
105 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 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 use Inline C => <<'END' => FILTERS => 'Preprocess';
116 // your code here
117 END
118 $ 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 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 use Inline C => <<'END' => CLEAN_AFTER_BUILD => 0 => FILTERS => 'Preprocess';
131 // your code here
132 END
133 $ 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
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 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 sub my_filter { };
155 use Inline C => DATA => FILTERS => [\&my_filter];
156 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 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 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 filter (object, coderef) METHOD
174 new (filter, coderef) METHOD
175 get_filters (language) FUNCTION
176 returns all supported languages
177
179 For more information about specifying Inline source code filters, see
180 Inline::C or Inline::CPP.
181 For more information about using other languages inside Perl, see
183 Inline. For more information about using C from Perl, see Inline::C.
184
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 If you wish to report a bug, please refer to Inline for instructions on
191 how to submit a bug report.
192 <https://rt.cpan.org/Public/Dist/Display.html?Name=Inline-Filters>
194
196 Neil Watkiss (NEILW@cpan.org) Reini Urban (RURBAN@cpan.org) Will
197 Braswell (WBRASWELL@cpan.org)
198 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 This module is free software. It may be used, redistributed and/or
207 modified under the same terms as Perl itself.
208 See <http://dev.perl.org/licenses/>.
210perl v5.36.0 2023-01-20 Filters(3)