Text Filters

You see work in progress here; this section already reflects future TED Notepad version 5.2.0.2.
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 variable syntax (i.e. %1, %2, ..., %9) to define those variables in the command. When the filter is to be used, a dialog will appear to ask for values of the variables. Furthermore, special %F variable can be used to refer to an actual path and file name of the current document. This can be used to run 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"

Technology

When a filter is to be executed, a new process is started using the command of that filter. All defined variables are replaced with values. The selection is then given to the stdin¹ of the started process. After the process returns, its stdout² or stderr³ is read, depending on what value the process returned. Finally, the selection is 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 the %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. %F variable can be useful to define an external viewer which does not read the stdin at all but requires a file name to start on.

¹ 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 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 when 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 16-bit/32-bit console application (i.e. PE files with an .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. No other requirements/restrictions are specified.

Note: Some languages (like Pascal) do not define any stderr. Therefore, all error messages could also be written to the stdout. When a non-zero error code is returned and no stderr is started, the stdout is supposed to be used instead of the 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.

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