view release on metacpan or  search on metacpan

lib/App/Framework/Extension/Filter.pm  view on Meta::CPAN

=item I<$app> - The application object

=item I<$opts_href> - HASH ref to the command line options (see L<App::Framework::Feature::Options> and L</Filter Options>)

=item I<$state_href> - HASH ref to state

=back

=back 


=head2 Output

By default, each time the extension calls the 'app' subroutine it sets the B<output> field of the state HASH to undef. The 'app'
subroutine must set this field to some value for the extension to write anything to the output file.

For examples, the following simple 'app' subroutine causes all input files to be output uppercased:

	sub app
	{
		my ($app, $opts_href, $state_href, $line) = @_ ;
		
		# uppercase
		$state_href->{output} = uc $line ;	
	}

If no L</outfile> option is specified, then all output will be written to STDOUT. Also, normally the output is written line-by-line after each line has been processed. If the L</buffer>
option has been specified, then all output lines are buffered (into the state variable L</output_lines>) then written out at the end of processing all input. Similarly, if the L</inplace>
option is specified, then buffering is used to process the complete input file then overwrite it with the output.

=head2 Outfile option

The L</outfile> option may be used to set the output filename. This may include variables that are specific to the Filter extension, where the variables value is updated for each
input file being processed. The following Filter-sepcific variables may be used:

		$filter{'filter_file'} = $state_href->{file} ;
		$filter{'filter_filenum'} = $state_href->{file_number} ;
		my ($base, $path, $ext) = fileparse($file, '\..*') ;
		$filter{'filter_name'} = $base ;
		$filter{'filter_base'} = $base ;
		$filter{'filter_path'} = $path ;
		$filter{'filter_ext'} = $ext ;

=over 4

=item I<filter_file> - Input full file path

=item I<filter_base> - Basename of input file (excluding extension)

=item I<filter_name> - Alias for L</filter_base>

=item I<filter_path> - Directory path of input file

=item I<filter_ext> - Extension of input file

=item I<filter_filenum> - Input file number (starting from 1)

=back


NOTE: Specifying these variables for options at the command line will require you to escape the variables per the operating system you are using (e.g. use single quotes ' ' around
the value in Linux).

For example, with the command line arguments:

    -outfile '/tmp/$filter_name-$filter_filenum.txt' afile.doc /doc/bfile.text

Processes './afile.doc' into '/tmp/afile-1.txt', and '/doc/bfile.text' into '/tmp/bfile-2.txt'


=head2 Example

As an example, here is a script that filters one or more HTML files to strip out unwanted sections (they are actually Doxygen HTML files
that I wanted to convert into a pdf book):

    #!/usr/bin/perl
    #
    use strict ;
    use App::Framework '::Filter' ;
    
    # VERSION
    our $VERSION = '1.00' ;
    
        ## Create app
        go() ;
    
    #----------------------------------------------------------------------
    sub app_begin
    {
        my ($app, $opts_href, $state_href, $line) = @_ ;
    
        # force in-place editing
        $app->set(inplace => 1) ;
    
        # set to start state
        $state_href->{vars} = {
            'state'        => 'start',
        } ;
    }
    
    #----------------------------------------------------------------------
    # Main execution
    #
    sub app
    {
        my ($app, $opts_href, $state_href, $line) = @_ ;
    
        my $ok = 1 ;
        if ($state_href->{'vars'}{'state'} eq 'start')
        {
            if ($line =~ m/<!-- Generated by Doxygen/i)
            {
                $ok = 0 ;
                $state_href->{'vars'}{'state'} = 'doxy-head' ;
            }
        }
        elsif ($state_href->{'vars'}{'state'} eq 'doxy-head')
        {
            $ok = 0 ;
            if ($line =~ m/<div class="contents">/i)
            {