Filters

Анонсы новых плагинов. Обсуждение плагинов ведется ниже.
Post Reply
pepak
Posts: 604
Joined: Sun 13 Jul, 2008 11:18
Has thanked: 17 times
Been thanked: 54 times

Filters

Post by pepak »

This plugin is intended to process the editor's content through a filter and put the results back into the editor. For example, a XML filter would parse the XML tags and format them for better readability, a HTML filter would convert the HTML document to a readable text, etc.

The plugin can be discussed in the discussion thread.

Download - version 0.04 (2018-04-15): Usage

The plugin operates on the data in FAR's internal editor. Open a file in the editor and activate the plugin. A menu with a list of suitable filters will be displayed, according to the details of the edited file. Choose a filter and the editor's text will be replaced with the output of the filter.

1) Available filters
  • Autoselect: This filter does not perform any formatting itself. Instead, it selects the first applicable filter (according to filter priorities, see Configuration) and uses that. Generally, this filter should have the highest priority of all filters, as it allows for an intuitive use of keyboard macros - you can easily execute this filter, which provides you with the functionality of "format the current file with the most suitable filter".
  • External filter: When you execute an external filter, an external executable gets called with the edited file as an argument (see Configuration). The executable would process the text and produce a new text, which is grabbed by the filter and injected into the editor. This can be used to support any custom filter you may have.
  • HTML View: This filter makes use of elinks (http://elinks.or.cz) to convert a HTML file into plain text. You must provide your own elinks executable and store it either in a directory in PATH, or in the "elinks" subdirectory of the plugin.
  • JSON Format: The JSON Format filter will try to pretty-print a JSON source, providing indentation and newlines where useful. It is an internal filter with no external dependencies which makes it fast, but if you find it insufficient for your needs, you can use the External Filter to provide an alternate solution.
  • XML Format: The XML Format filter will try to pretty-print a XML source, providing indentation and newlines where useful. It is an internal filter with no external dependencies which makes it fast, but if you find it insufficient for your needs, you can use the External Filter to provide an alternate solution.
2) Blocks

By default, the full edited file will be processed. However, if you select a block, only the text within the block will be passed to the filter. That may be useful e.g. when you are editing a HTML file and want to format a JSON object stored within it.

Note that column blocks are not supported in the current version of Filters.

3) Configuration

When you enter the plugin's configuration, a list of filters will be displayed. The filters are sorted by their priorities, which applies to the selection menu when activating filters and to the operation of the Autoselect filter. You can change the priorities by pressing CTRL+UP or CTRL+DOWN.

If you want to create a new filter, press INSERT, CTRL+N or SHIFT+F4, or press the "New" button at the bottom of the dialog (note that the "N" hotkey for the button doesn't work due to a bug in FAR Manager - see bug #3586). Choose a filter type and then provide the configuration of the filter.

If you want to edit an existing filter, press F4 or CTRL+E or press the "Edit" button. A dialog will appear where you can modify the filter's settings.

If you want to delete an existing filter, press DELETE, BACKSPACE or F8.

To save the modified configuration, press ENTER or use the OK button. If you press ESCAPE (or the Cancel button) instead, your changes will be discarded.

All filters allow you to modify several key properties:
  • Description: The text which will appear in the configuration dialog and the selection menu. You can write anything you like here.
  • File mask: This option can be used to limit the filter's availability only to certain file types by providing a file mask (e.g. "*.xml"). You may use multiple masks separated with a comma; you can also add a filter multiple times, each time with a different mask. If no mask is entered, the filter will be applicable to all files.
The external filter supports (and requires) additional options:
  • Command template: Here you need to put the command line to execute when the filter is activated. It must consist of the filename (including the directory if it is outside of PATH) of the external filter and may contain arguments. Escape sequences are available for variables.
  • Pass input as: Select what the executable's source will be. Most filters support reading data from the standard input (STDIN), but in some cases an input file may be required. In such a case, the Command Template must contain the %i symbol; the filename will be chosen automatically and a temporary file will be created with the editor's content.
  • Input encoding: Select the encoding expected by the filter. In case of Unicode encodings, a byte-order-mark may optionally be inserted at the beginning of the file.
  • Get output from: Select where the executable writes its output. Most filters will send the output to standard output (STDOUT), but some may require writing it to a file; in such a case, you must use the %o symbol in the Command template. In specific cases, you may want to read the error output of the executable, available under STDERR.
  • Output encoding: Select the encoding generated by the filter. This will generally be the same value as the input encoding, but some filters may require a different setting for each.
4) Plugin-call support

In FAR3, plugin-calls are supported. A sample script with all available functions is provided in the "Filters.lua" file. You can copy this file to your "%FARPROFILE%\Macros\Scripts" directory to activate it, possibly after modifying it to your needs.

Available values for the Filters.Execute's ID argument:
  • "auto" ... Activates the Autoselect filter.
  • "html" ... Activates the HTML View filter.
  • "json" ... Activates the JSON Format filter.
  • "xml" ... Activates the XML Format filter.
Running external filters from the plugin-call is not supported at the moment.
Last edited by pepak on Sun 15 Apr, 2018 07:26, edited 4 times in total.
pepak
Posts: 604
Joined: Sun 13 Jul, 2008 11:18
Has thanked: 17 times
Been thanked: 54 times

Filters

Post by pepak »

Released version 0.03
  • Added support for plugin-call to a named filter. This allows calling of external filters which weren't available to plugin-calls in previous versions. Use the Filters.ExecuteByName script function; as an argument, provide the description of your filter, as entered into the filter's configuration.
  • Added support for a filter reconfiguration just before use. The purpose of this feature is to allow a modification of arguments of an external filter as per immediate requirements without having to create multiple filter configurations in advance. Just mark the filter as "Edit before use" and you will be asked to modify the filter settings before use.
  • Added support for combined STDOUT and STDERR output to the external filters.
  • Added history support to edit fields in the dialogs.
  • Fixed: After editing a filter's configuration, the selection of the filter list moved to the first item. Now it will stay at the edited item.
  • Fixed: If the filter was run against a selection and the filtered output ended with a newline, that newline got discarded and the first line after the selection got appended to the last line of the output.
  • Fixed: With persistent blocks enabled, if the cursor was outside of the selection at the time the plugin was executed, the filtered output would get written at the cursor position (i.e. inside some completely unrelated section of the file).
  • Moved the definition of the start of the undo block before any other operation on the editor's content in the hope that it would include the cursor movement into an Undo, if the user decided to use it. Unfortunately, it seems that FAR does not consider cursor movements a part of the Undo block (FAR3 build 5134).
  • Fixed an EConvertError exception when entering incorrect % modifiers into the external filter's command template.
Source codes can't be uploaded to PlugRing due to 413 Request Entity Too Large.
pepak
Posts: 604
Joined: Sun 13 Jul, 2008 11:18
Has thanked: 17 times
Been thanked: 54 times

Filters

Post by pepak »

Released version 0.04
  • In the filter configuration dialog, you can press the Copy button or keys F5 or CTRL+C to make a copy of the selected filter.
  • If a filter is set to "edit before use", its configuration dialog contains a new checkbox to let you save the modified settings to the configuration to make them permanent.
  • Filter list is always loaded just before use. As a result, if multiple instances of FAR are running and you change the plugin's configuration in one of them, it will immediately apply to all of them.
  • If a filter set to "edit before use" was called from a script, it would execute immediately without displaying the configuration dialog.
Post Reply

Return to “Анонсы новых плагинов”