 ______________________________________________________________________________
|                                                                              |
|   Filters v0.04+                      (c) 2018+ Pepak, http://www.pepak.net  |
|______________________________________________________________________________|

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.



A. 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

In the current version, the following filters are available:

  * 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 at
https://bugs.farmanager.com/view.php?id=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.

  * Edit before use - If enabled, you will be presented with the configuration
    dialog immediately before the filter gets executed. This can be useful
    for filters which allow configuration - rather than having to prepare
    multiple filter configs in advance, you can select the necessary options
    just before the filter is used.

  * Save the new settings - This option, displayed only just before use when
    "Edit before use" is active, lets you save the modified settings into
    the filter configuration.

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:

      %i ... Will get replaced with the filename of the input file if input
             is expected from a file rather than STDIN.
      %o ... Will get replaced with the filename of the output file if output
             is expected to a file rather than STDOUT or STDERR.
      %w ... Will get replaced with FAR's screen width, to e.g. properly line-
             wrap the output.
      %% ... Will get replaced with the percentage sign ("%").

  * 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.

For example, if you want to use jq (https://stedolan.github.io/jq/) to
pretty-print a JSON input, you could use the following setttings:

  * Description - anything
  * File mask - "*.json", or perhaps empty
  * Command template - "jq ."
  * Pass input as - STDIN
  * Input encoding - UTF8, with Byte Order Mark
  * Get output from - STDOUT
  * Output encoding - UTF8


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.

The Filters.ExecuteByName function allows you to execute a specific
filter configuration, just enter the filter's description (from the config)
as the first argument. This way you can execute even the external filters.



B. LICENSE
----------

The plugin is released under the Modified (3-clause) BSD License. See
license.txt for details.



C. BUILDING THE PLUGIN
----------------------

You will need Delphi version at least XE2. Older versions are not supported.
Newer versions should work fine, I tested the build with Delphi 10 Seattle
as well.

Make sure the chosen Delphi's BIN directory is in the PATH, go into the
SOURCE directory and run BUILD. You should get a new Filters.dll in the BIN
directory.

You can use several command-line options with BUILD. The most important are:

    FAR2 ........ Build the FAR2 version of the plugin.
    FAR3 ........ Build the FAR3 version of the plugin (default).
    X86 ......... Build the 32-bit version of the plugin (default).
    X64 ......... Build the 64-bit version of the plugin.



D. CONTACT
----------

If you have any questions or want to suggest a new feature, you can do so
either in the english section of FAR Manager's forums ( https://forum.farmanager.com/viewtopic.php?f=39&t=11116 ),
or my own forums ( http://forum.pepak.net ).
