The plugin can be discussed in the discussion thread.
Download - current version: 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.
- BASE64 Decoder: The BASE64 decoder will take a BASE64-encoded text and decode it to the original binary value. Note that the editor's encoding should be set to an 8-bit encoding (e.g. ANSI or OEM) for the best results.
- URL Decoder: The URL decoder will take a URL-encoded text and decode it to the original binary value. Note that the editor's encoding should be set to an 8-bit encoding (e.g. ANSI or OEM) for the best results.
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.
- 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.
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.
- "base64" ... Activates the BASE64 Decoder filter.
- "urldec" ... Activates the URL Decoder filter.