Padre::Plugin::Shell::Filter - Unix-like external filters in Padre.

This plug-in enables the use of Unix-like external filtering commands/scripts to transform part or all of the current document.

The output of the filter can either replace the input, be appended to the input, or be inserted into a new document.

Unlike Unix filters, the filter mechanism in this plug-in is designed to use input and output files rather than STDIN and STDOUT.

Filter definitions are stored in a YAML formatted configuration file in the user's Padre configuration directory (~/.padre). Each filter is labeled with the name that is to be displayed in the filter menu. In addition to the name there are four attributes for each filter definition:

command -- The command to run to perform the filtering. There are two placeholders in the command string [% IN %] and [% OUT %] for the input and output filenames used in running the filter.

description A description of what the filter does (optional).

input The source of the text to filter. Valid values are selection, document, line, and none. Selection may be combined with either document, line, or none. The default value is selection,document.

selection -- There needs to be a text selection for the filter to run, and the filter is run using the selected text as input.

document -- The filter uses the entire document as input whether there is selected text or not.

line -- The filter uses the current line as input whether there is selected text or not.

none -- Do not use any text as the input to the filter.

selection,(document|line|none) -- If there is a text selection then the filter uses the selected text as input. If there is no selected text then the filter falls back to using the other specified source (document, line, or none) as input.

output The action to take with the output. Valid values are replace, append, and new. The default value is append.

append -- Appends the filter results after the input.

replace -- Replaces the input with the filter results.

new -- Creates a new document with the filter results.

To provide additional information for the filters, various environment variables are set prior to running the filter. These environment variables are covered in the Padre::Plugin::Shell::Base documentation.

Generates and returns a menu of the defined filters.

Returns an example configuration. This is the initial configuration that gets created the first time that this plugin is used.

Searches the filter configuration for a filter definition that matches the supplied $filter_name. If a matching filter is found then that filter is run.

When adding entries to the configuration file it appears to be necessary to have an empty line at the end of the file in order for the configuration to properly load. No properly loaded configuration results in no menu for the plug-in.

Gregory Siems <gsiems@gmail.com>

Copyright (C) 2009 by Gregory Siems

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.