Filters(3)

✨ NAME ✨

Inline::Filters — Common source code filters for Inline Modules. Yes bestie, this is Filters(3) from the User Contributed Perl Documentation collection, and it is exactly as niche and as iconic as it sounds. 💅

---

💖 DESCRIPTION 💖

Inline::Filters hands common source code filters to Inline Language Modules. That's the whole vibe.

Okay so if you're not an Inline module developer, you can literally just skip to the next section. No shame, we all start somewhere. 🫶

🦋 Supported Filters 🦋

This bit walks you through every filter in Inline::Filters, one by one. Let's go. ✨

🎀 Strip_POD 🎀

Strips embedded POD out of a block of code in any language. It's literally just a regex doing the lord's work:

$code =~ s/^=\w+[^\n]*\n\n(.*?)(^=cut\n\n|\Z)//gsm;

Which means: if your language has POD-like syntax floating around in it, this filter is gonna strip that too. So like, don't use this filter with a language like that, bestie, seriously. 😭

Where it does eat, though, is making code like this actually compile:

use Inline C => <<'END', FILTERS => 'Strip_POD';
=head1 add

Returns the sum of two integers.

=cut

int add(int x, int y) { return x + y; }
END

Slay. That's the whole point. 💅

🌸 Strip Comments 🌸

Strips comments from a block of code in whatever language you're working in. And it's string-safe, meaning it will not go strip comments that are embedded inside strings. Respectful queen behavior. 👑

Why do you even want this? Because both the C and C++ grammars simply cannot deal with comments at arbitrary points in the source code — doing so would bloat the grammar. So instead, code like this should get its comments stripped before parsing:

use Inline C => <<'END', FILTERS => 'Strip_Comments';

int md5_block(char *block,   /* the block to operate on */
              long length,   /* the number of bytes */
              char **result) /* the resulting 128-bit sum */
{
     /* some code here */
}

END

Strip_Comments is available for the following languages:

• Strip_C_Comments
• Strip_CPP_Comments
• Strip_Python_Comments
• Strip_TCL_Comments
• Java via Strip_CPP_Comments

The Python and Java filters are available for convenience only. There's honestly little need for them, because Inline::Python and Inline::Java use the official language compilers to parse the code, and those compilers already know about comments. iykyk. 💁

🧚 Preprocess 🧚

Now available for all languages. It uses the C pre-processor ($Config{cpprun}) to pre-process a block of code. This is the move when you want to expand macros and conditional code before parsing. Like so:

use Inline CPP => <<'END', FILTERS => 'Preprocess';
class Foo
#ifdef FOO_INHERITS_BAR
   : public Bar
#endif
{

};
END

That code right there will not parse correctly without the Preprocess filter, because the Inline::CPP grammar simply can't understand preprocessor directives. It's not being difficult, it just can't. 🙈

💜 CPPFLAGS Argument

Also available: the CPPFLAGS argument, which lets you specify C preprocessor directives.

use Inline C => <<'END' => CPPFLAGS => ' -DPREPROCESSOR_DEFINE' => FILTERS => 'Preprocess';
#ifdef PREPROCESSOR_DEFINE
int foo() { return 4321; }
#else
int foo() { return -1; }
#endif
END

The code shown above will return 4321 when foo() is called. ✨

💜 CLEAN_AFTER_BUILD Argument

By default, the Preprocess filter deletes all Filters*.c files it creates. But if you set the CLEAN_AFTER_BUILD flag to false, then those Filters*.c files will not be deleted. This is necessary when you're using gdb to debug Inline::C and Inline::CPP programs that utilize the Preprocess filter.

If you do not set the CLEAN_AFTER_BUILD flag to false, you will likely end up with a No such file or directory error in gdb. Which is giving... nothing. 💀

use Inline C => <<'END' => FILTERS => 'Preprocess';
// your code here
END

$ gdb /usr/bin/perl (gdb) run ./my_script.pl arg0 arg1 ...  Thread 1
"perl" received signal SIGSEGV, Segmentation fault.
MyPackage::my_method (this=this@entry=0x1234567, my_arg=my_arg@entry=23)
    at /.../_Inline/build/eval_XXX_YYYY/FiltersZZZZ.c:42 42
/.../_Inline/build/eval_XXX_YYYY/FiltersZZZZ.c: No such file or
directory.

If you do set the CLEAN_AFTER_BUILD flag to false, you should see the actual offending C or C++ code in gdb:

use Inline C => <<'END' => CLEAN_AFTER_BUILD => 0 => FILTERS => 'Preprocess';
// your code here
END

$ gdb /usr/bin/perl (gdb) run ./my_script.pl arg0 arg1 ...  Thread 1
"perl" received signal SIGSEGV, Segmentation fault.
MyPackage::my_method (this=this@entry=0x1234567, my_arg=my_arg@entry=23)
    at /.../_Inline/build/eval_XXX_YYYY/FiltersZZZZ.c:42 42    YOU
SHOULD SEE YOUR ACTUAL OFFENDING CODE HERE

See? Main character energy. 👑

---

🌈 DETAILS 🌈

🎀 Built-in Filters 🎀

Built-in source code filters are implemented as a blessed reference to a hash</c> containing two elements:

• 'filter' — the name of the filter
• 'coderef' — a code reference to the appropriate filter

The object has a filter() method, which should be called with the ILSM object as the first parameter and the source code as the second parameter. The filters always return the filtered code. No cap.

🎀 User-supplied Filters 🎀

As of Inline 0.42, you can supply your own filters to Inline by passing a code reference to the FILTERS option, like this:

sub my_filter { };
use Inline C => DATA => FILTERS => [\&my_filter];

The filter sub is passed one argument: the unfiltered code. It must return the filtered code as its only return value. And if something goes wrong and you need to inform the user? Just croak. Simple as that. 💅

Note: in some circumstances, you must put your filter subroutine above the use Inline statement. When possible, Inline compiles your code at compile time, which means the subroutine must be defined. But if you're reading code from the 'DATA' filehandle, you can put the filter anywhere in your script, since Inline delays compilation until runtime. Flexibility, we love to see it. ✨

🎀 Applying Filters 🎀

Inline provides a filter() method which applies the requested filters one after the other on the source code. All ILSMs should save the result of $o->filter() and consider it the source code. If no filters have been requested, this just returns the unfiltered source code. Chill. 🦋

🎀 filter (object, coderef) METHOD 🎀

🎀 new (filter, coderef) METHOD 🎀

🎀 get_filters (language) FUNCTION 🎀

returns all supported languages

---

👑 SEE ALSO 👑

For more information about specifying Inline source code filters, see Inline::C or Inline::CPP.

For more information about using other languages inside Perl, see Inline. For more information about using C from Perl, see Inline::C.

---

💀 BUGS OR OMISSIONS 💀

You can pass in arbitrary subroutine references as filters. However, if you find yourself using a filter on a regular basis and you'd like to see it included in Inline::Filters, please file a bug report. We want your faves in the lineup, fr fr. 🙏

If you wish to report a bug, please refer to Inline for instructions on how to submit a bug report.

<https://rt.cpan.org/Public/Dist/Display.html?Name=Inline-Filters>

---

💖 AUTHOR 💖

Neil Watkiss (NEILW@cpan.org) Reini Urban (RURBAN@cpan.org) Will Braswell (WBRASWELL@cpan.org)

Maintained now by the perl11 team: <https://github.com/perl11/Inline-Filters>

---

🌸 COPYRIGHT 🌸

Copyright (C) 2001, Neil Watkiss. Copyright (C) 2014, 2015 Reini Urban & Will Braswell.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

See <http://dev.perl.org/licenses/>.

---

And that's the whole page, bestie — brought to you by perl v5.42.0, dated 2025-07-25, and it's Filters(3) so you know exactly where to find it. Now go filter something. 🫶✨💅