.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Filters 3" .TH Filters 3 2023-07-25 "perl v5.38.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Inline::Filters \- Common source code filters for Inline Modules. .SH DESCRIPTION .IX Header "DESCRIPTION" \&\f(CW\*(C`Inline::Filters\*(C'\fR provides common source code filters to Inline Language Modules. Unless you're an Inline module developer, you can just read the next section. .SH "Supported Filters" .IX Header "Supported Filters" This section describes each filter in Inline::Filters. .SS Strip_POD .IX Subsection "Strip_POD" Strips embedded POD from a block of code in any language. This is implemented as a regular expression: .PP .Vb 1 \& $code =~ s/^=\ew+[^\en]*\en\en(.*?)(^=cut\en\en|\eZ)//gsm; .Ve .PP That means if you have a language which contains POD-like syntax, it will be stripped by this filter (i.e. don't use this filter with such a language). This filter is useful for making code like this compile: .PP .Vb 2 \& use Inline C => <<\*(AqEND\*(Aq, FILTERS => \*(AqStrip_POD\*(Aq; \& =head1 add \& \& Returns the sum of two integers. \& \& =cut \& \& int add(int x, int y) { return x + y; } \& END .Ve .SS "Strip Comments" .IX Subsection "Strip Comments" Strips comments from a block of code in whatever language you are using. The comment stripper is string-safe \-\- i.e. it will not strip comments embedded in strings. .PP The feature is useful because both the C and C++ grammars cannot deal with comments at arbitrary points in the source code; to do so would bloat the grammar. Instead, code like this should have its comments stripped before parsing: .PP .Vb 1 \& use Inline C => <<\*(AqEND\*(Aq, FILTERS => \*(AqStrip_Comments\*(Aq; \& \& 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 .Ve .PP Strip_Comments is available for the following languages: .IP Strip_C_Comments 4 .IX Item "Strip_C_Comments" .PD 0 .IP Strip_CPP_Comments 4 .IX Item "Strip_CPP_Comments" .IP Strip_Python_Comments 4 .IX Item "Strip_Python_Comments" .IP Strip_TCL_Comments 4 .IX Item "Strip_TCL_Comments" .IP "Java via Strip_CPP_Comments" 4 .IX Item "Java via Strip_CPP_Comments" .PD .PP The Python and Java filters are available for convenience only. There is little need for them, since Inline::Python and Inline::Java use the official language compilers to parse the code, and these compilers know about comments. .SS Preprocess .IX Subsection "Preprocess" Now available for all languages. Uses the C pre-processor ($Config{cpprun}) to pre-process a block of code. This is useful if you want to expand macros and conditional code before parsing. For example: .PP .Vb 6 \& use Inline CPP => <<\*(AqEND\*(Aq, FILTERS => \*(AqPreprocess\*(Aq; \& class Foo \& #ifdef FOO_INHERITS_BAR \& : public Bar \& #endif \& { \& \& }; \& END .Ve .PP The code shown above will not parse correctly without the Preprocess filter, since the Inline::CPP grammar can't understand preprocessor directives. .PP \fICPPFLAGS Argument\fR .IX Subsection "CPPFLAGS Argument" .PP Also available is the CPPFLAGS argument, to specify C preprocessor directives. .PP .Vb 7 \& use Inline C => <<\*(AqEND\*(Aq => CPPFLAGS => \*(Aq \-DPREPROCESSOR_DEFINE\*(Aq => FILTERS => \*(AqPreprocess\*(Aq; \& #ifdef PREPROCESSOR_DEFINE \& int foo() { return 4321; } \& #else \& int foo() { return \-1; } \& #endif \& END .Ve .PP The code shown above will return 4321 when \fBfoo()\fR is called. .PP \fICLEAN_AFTER_BUILD Argument\fR .IX Subsection "CLEAN_AFTER_BUILD Argument" .PP By default, the Preprocess filter deletes all \fIFilters*.c\fR files it creates. If you set the CLEAN_AFTER_BUILD flag to false, then the \f(CW\*(C`Filters*.c\*(C'\fR files will not be deleted; this is necessary when using \f(CW\*(C`gdb\*(C'\fR to debug Inline::C and Inline::CPP programs which utilize the Preprocess filter. .PP 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: .PP .Vb 3 \& use Inline C => <<\*(AqEND\*(Aq => FILTERS => \*(AqPreprocess\*(Aq; \& // your code here \& END .Ve .PP $ 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. .PP If you do set the CLEAN_AFTER_BUILD flag to false, you should see the actual offending C or C++ code in gdb: .PP .Vb 3 \& use Inline C => <<\*(AqEND\*(Aq => CLEAN_AFTER_BUILD => 0 => FILTERS => \*(AqPreprocess\*(Aq; \& // your code here \& END .Ve .PP $ 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 .SH DETAILS .IX Header "DETAILS" .SS "Built-in Filters" .IX Subsection "Built-in Filters" Built-in source code filters are implemented as a blessed reference to a hash containing two elements: 'filter' is the name of the filter, and 'coderef' is a code reference to the appropriate filter. The object has a \fBfilter()\fR method, which should be called with the ILSM object as the first parameter, and source code as the second parameter. The filters always return the filtered code. .SS "User-supplied Filters" .IX Subsection "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: .PP .Vb 2 \& sub my_filter { }; \& use Inline C => DATA => FILTERS => [\e&my_filter]; .Ve .PP The filter sub is passed one argument: the unfiltered code. It must return the filtered code as its only return value. If something goes wrong and you need to pass inform the user, just croak. .PP Note: in some circumstances, you \fImust\fR put your filter subroutine \fIabove\fR the \f(CW\*(C`use Inline\*(C'\fR statement. When possible, Inline compiles your code at compile time, meaning the subroutine must be defined. If you're reading code from the 'DATA' filehandle, you can put the filter anywhere in your script, since Inline delays compilation until runtime. .SS "Applying Filters" .IX Subsection "Applying Filters" \&\f(CW\*(C`Inline\*(C'\fR provides a \fBfilter()\fR method which applies the requested filters one after the other on the source code. All ILSMs should save the result of \&\f(CW$o\fR\->\fBfilter()\fR and consider it the source code. If no filters have been requested, this just returns the unfiltered source code. .SS "filter (object, coderef) METHOD" .IX Subsection "filter (object, coderef) METHOD" .SS "new (filter, coderef) METHOD" .IX Subsection "new (filter, coderef) METHOD" .SS "get_filters (language) FUNCTION" .IX Subsection "get_filters (language) FUNCTION" returns all supported languages .SH "SEE ALSO" .IX Header "SEE ALSO" For more information about specifying Inline source code filters, see Inline::C or Inline::CPP. .PP For more information about using other languages inside Perl, see Inline. For more information about using C from Perl, see Inline::C. .SH "BUGS OR OMISSIONS" .IX Header "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. .PP If you wish to report a bug, please refer to Inline for instructions on how to submit a bug report. .PP .SH AUTHOR .IX Header "AUTHOR" Neil Watkiss (NEILW@cpan.org) Reini Urban (RURBAN@cpan.org) Will Braswell (WBRASWELL@cpan.org) .PP Maintained now by the perl11 team: https://github.com/perl11/Inline\-Filters .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright (C) 2001, Neil Watkiss. Copyright (C) 2014, 2015 Reini Urban & Will Braswell. .PP This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself. .PP See .