Text Filters

You see work in progress here; this section already reflects future TED Notepad version 5.0.0.10.
This section may contain incomplete, premature, or mistaken information, prone to change without notice.

Inspiration

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 the actual selection and then accept the output back into the TED workspace.         (--- anonymous user ---)

Architecture

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

Each filter can define up to 9 variables in the command. Use batch variables syntax (%1, %2, ..., %9) to define those variables. When the filter is to be used, Filter dialog will appear to ask for those variables' values. Furthermore, variable %F can be used to refer to an actual path and file name of the current document. This can be used to define an external viewer (e.g. Internet Explorer or Firefox).

Example:

myapp.exe %1 myapp.exe /a %1 /b /c"%2" myapp.exe /a %1 /b /c"%1" myviewer.exe /a %1 /b "%F"

When a filter}} is to be executed, a new process is started using the filter's command (filled with variables' values) and the selection is given to its stdin¹. After the process returns, its stdout² or stderr³ is read, depending on what value the process returned. The selection is then replaced with the output of the process or an error is displayed, containing the returned error code and the content of the stderr³. All inputs/outputs are Non-UNICODE.

If the %F variable is used, the document is automatically saved before the execution of the filter and %F is replaced by the actual path and file name of the current document. The selection is ignored (neglected), which means, that nothing is written to filter's stdin and no output is awaited from filter's stdout. Therefore, %F variable can be useful probably only to define an external viewer.

¹ standard console input

² standard console output

³ standard console error output

Requirements

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

If an application file name ends with .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 when searching for the application.

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

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 16-bit/32-bit console application (ie. PE files with .exe extension) may be used (like c/c++, pascal, qbasic, ...). Such application should use its stdin for input, its stdout for output and its stderr in the case of failure/error (which are used by default in these languages). It should return zero upon success or non-zero value upon failure (which are used to be used by default in these languages too). No other requirements/restrictions are demanded.

Note: Some languages (like Pascal) do not define any stderr, therefore all error messages must be written to the stdout. Therefore, in such cases (when a non-zero error code is returned and stderr is not started), the stdout is used instead of the stderr for any error messages. Furthermore, in some cases, both stdout and stderr are displayed upon non-zero error code. This behaviour may change in the future, according to suggestions of the end users, but stderr is and will be preffered.

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 param 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 a word 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 too...)

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 }