Text Filters

This section is up to date for TED Notepad version 6.3.1.0.
Control page Control:feature: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.

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 be supplemented with upto 9 user variables within its command, using batch variable syntax, i.e. %1, %2, ..., %9. Upon invoking such filter, Filter dialog appears, asking for values for required variables.

Besides user variables, internal variables are available:

• %F variable can be used to insert path and file name of the current document.
• %S variable can be used to insert current selection into the command.

This section is incomplete and wants to be finished later.

TODO: more internal variables?

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 to "Use ""double-quotes"" in parameters", if %1 contains phrase 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 to "Use \"double-quotes\" in parameters", if %1 contains phrase 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

This section is incomplete and wants to be finished later.

TODO: Options

Nothing is written into the filter's stdin.

No output is gathered from filter's stdout.

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.

Technical details

Upon filter being executed, a new process is started using the filter's command, after replacing all variables with given user values from the Filter dialog. Current selection is written into the stdin¹ of the started process, and its stdout² and stderr³ are read. Depending on what value the process returns, current selection is replaced with the output of the process, or an error message is displayed, containing returned error code and contents of the stderr³.

If the %F variable is used, the document is saved automatically before the execution of the filter and the %F is then replaced by the actual path and file name of the current document.

¹ standard console input

² standard console output

³ standard console error output

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 to the stderr.

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

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/restrictions 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.

Note: Actually, both stdout and stderr are displayed to the user upon a non-zero error code. This behaviour may change in the future, according to the suggestions of the end users. The stderr is and will be preffered.

This section is incomplete and wants to be finished later.

TODO: really?

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 writting 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 }