Text Filters

This section is up to date for TED Notepad version 6.3.1.0.
Control page Control:feature:Text Filters

This section is up to date for TED Notepad version 6.3.1.0.
Control page Control:menu:Text Filters

How about a plugin architecture? Something simple - just a list of menu names and programs to run and maybe an indication of whether it should prompt for additional parameters. TED will run the program with those parameters and with current selection and then accept the output back into the TED workspace.         (--- anonymous user ---)

Managing filters

Filters can be added thru the Settings dialog. See chapter Filters page of the Settings dialog for details on adding, modifying and managing filters.

Technical details

Upon filter being executed, a new external process or command is started. Current selection is written into the stdin¹ of that process, and its stdout² and stderr³ are read. Depending on what return code the process returns, the selection is either replaced with the output of the process, or an error message is displayed, containing returned error code and contents of the stderr.

¹ standard console input

² standard console output

³ standard console error output

It is also possible to launch the filter with current selection as an argument, instead of pushing text into stdin. One can easily launch a browser and google the selected text for example.

Alternativelly, file name of the current document can be provided to the external filter. An external file viewer can be set this way and launched whenever necessary.

Finally, launch-time variables are available, thus the user can specify additional arguments upon each invocation of a filter. This can be useful for external greps, directory listings, etc.

Filter commands

Each filter must be defined as a runnable command, consisting of an application file to execute and its parameters. System commands can be executed as well, but only through a command interpreter, i.e. cmd.exe, command.com or launch.exe, as described below.

Each filter can use the following user and internal variables:

• %1, %2, ..., %9 variables allow the user to specify launch-time command arguments upon each individual invocation, using the Filter dialog.
• %F variable can be used to insert path and file name of the current document into the command. The document is saved automatically before the execution of such filter.
• %S variable can be used to insert current selection into the command.
• %% can be used to safely insert common % character into the command.

All command variables can be auto-enclosed with "double-quotes" by adding an escaping flag to them. Escaping flag is one of following:

• Tilde (~) — Encloses the variable with double-quotes, and doubles all double-quotes in the variable. This is more common for native Windows commandline applications.
  • E.g. Variable %~1 expands phrase Use "double-quotes" in parameters into "Use ""double-quotes"" in parameters".
• Back-slash (\) — Encloses the variable with double-quotes, and escapes all double-quotes in the variable with back-slashes. This is more common for unix and linux commandline applications.
  • E.g. Variable %\1 expands phrase Use "double-quotes" in parameters into "Use \"double-quotes\" in parameters".

Note: Unescaped variable, e.g. %S, does not add any extra characters to the command. This can be useful and sometimes even necessary, but it can also become unreliable, if spaces and other special characters are expected in such variable. Consider escaping variables, if spaces are expected to be given upon using a filter.

Example:

myapp.exe %1 myapp.exe /a %1 /b /c %2 myviewer.exe %~F grep.exe -e %\S

Filter options

For full list of all options a filter can employ, please see chapter Filters page of the Settings dialog. Following tips describe some of the options a filter can employ.

Tip: If the filter is expected to work with UTF-8 input and output, use the UTF-8 option to get the selection automatically converted upon input and output.

Tip: It is possible to skip the launch dialog altogether upon invoking a filter by using Skip launch dialog option. This can be useful, if no variables and arguments are expected from the user anyway and the dialog just annoys the user.

Tip: Variable %F, along with Push input and Capture output options turned off, can be useful to define an external viewer which does not read the stdin at all, but requires a file name to start on. Also, Ignore return code can be useful if you don't want the external viewer to block the document while viewing. Please note that using the %F automatically saves the document before launching the filter as described below.

Tip: Certain filters might need to use the Mix stdout/stderr option, especially if the filter's stderr is a native part of the overall results.

Tip: It is possible to display the filters' results in a message box instead of replacing the selection, using the Display as message option.

Tip: Some filters might make good use of the Exit when done option. The document is checked for saving before such exit.

Filter requirements

An application defined in filter's command should read the stdin for input text and should output any results to the stdout. If the operation is successful, the application should return zero. Otherwise it should return non-zero value and optionally describe the error thru the stderr.

Note: Some languages (like Pascal) do not support stderr at all. Therefore, if a non-zero return code is received and stderr is not used, stdout is expected to contain the error description message.

If an application file name ends with an .exe extension, it is not necessary to use it in the command, but it may be necessary otherwise. The command can specify the full path and file name of the application to execute as well as only the file name. In the case of a missing path, system uses the current working directory and system directories upon searching for the application.

System commands need to be executed through a command interpreter, as they do not have any file names to be executed. Use standard command interpreters (i.e. cmd.exe on Win NT/2000/XP, command.com on Win 9x/ME) or the launch.exe interpreter, which is included in the installation package and installed with TED Notepad.

Examples:

cmd.exe /c command [parameters] cmd /c dir /b %1 command.com /c command [parameters] command.com /c dir /b %1 launch.exe command [parameters] launch dir /b %1

How to create a filter's application?

Very easy! Any programming language that can be compiled to a console application (i.e. PE files with an .exe extension) may be used, e.g. C/C++, Pascal, Visual Basic, etc. Even scripting languages are supported by using their associated interpreter for execution, e.g. PHP, Python, Perl, etc.

Such application should use its stdin for input, its stdout for output and its stderr in the case of failure/error. It should return zero upon success and non-zero value upon failure. No other requirements are necessary. Applications can execute their own sub-processes, and even show user dialogs if necessary.

Note: Some languages do not define stderr. Therefore, all error messages can also be written to stdout. If a non-zero error code is returned and no stderr is started, stdout is read instead of stderr for any error messages to be displayed to the user.

Example:

#include <stdio.h> #include <stdlib.h> int main (int argc, char* argv[]) { int lines; char buff[1024]; if (argc < 2) { fprintf (stderr, "Enter the number!"); // outputs to stderr return 1; // ...failure! } lines = atoi (argv[1]); // gets 1st parameter and // converts it to integer if (lines < 1) { fprintf (stderr, "Wrong number!"); // outputs to stderr return 2; // ...failure! } while (lines != 0) { if (EOF == scanf ("%s", buff)) // reads from stdin break; // or breaks on end-of-input printf ("%s\n", buff); // writes to stdout lines = lines - 1; } return 0; // ...success }

Example: There is no stderr in Pascal, therefore writing errors to stdout...

var lines, code: integer; buff: string; begin if ParamCount < 1 then begin writeln ('Enter the number!'); { outputs } halt (1); { ...failure! } end; Val(ParamStr(1), lines, code); { gets 1st param and } { converts it to integer } if lines < 1 then begin writeln ('Wrong number!'); { outputs } halt (2); { ...failure! } end; while lines <> 0 do begin readln (buff); { reads a line from stdin } if eof then break; writeln (buff); { writes to stdout } lines:= lines - 1; end; end. { ...autosuccess }

Further details

Note: Since version 6.3, any binary characters (i.e. the null character) are replaced with spaces before being sent to a filter.

Note: Since version 6.3, all newlines are converted to Windows type (i.e. CR/NL, i.e. 13 10 in ASCII, i.e. 0D 0A in hex) before being sent to a filter.