Stream editing

A stream editor is an editor that processes a file taking its instructions from another file. This can be very useful when a fixed editing task has to be used regularly, like the conversion of one dialect of a language to another. Stedi provides this facility in three ways. The first way involves the macro facility. This can be looked up in the chapter on macro's. It is by far the most useful facility of the ones mentioned here. The second way is given by the I command in which the I stands for `input'. When the I# command is issued from the command line (# should be a digit in the range of 1-8) stedi treats the lines in the corresponding buffer as input for the command line. It starts at the `current line' in this buffer (the line in which the cursor is when the user switches to this buffer) and proceeds executing statements either till there are no more lines, till a search with the . option is not successful or till a command results in a fatal error condition. There are several restrictions that should be taken into account:

• Any line that starts with either a $*$ or a # is skipped. It is seen as commentary.
• Neither a fold line nor the lines within a closed fold are executed.
• Only the first 255 characters of a command can be copied to the command line.
• If a line ends with an <escape> character or a backslash (only on systems for which the backslash has no special function in the file system) it is assumed that the carriage return that followed it has been interpreted wrong, with the result that the command is now spread over more than one line. Therefore a <return> character is added and the contents of the next line are considered to be part of the same command.
• Commands that are executed from a stream are not entered in the command history. The last command in the command history will be the input command itself.

It can happen occasionally that the user may want to abort a stream command when he sees that things are not proceeding as planned. This can be done by pressing both shift keys simultaneously. Stedi will then halt the execution of the input command. The cursor in the stream file is left in the line with the next statement that would be executed if the error condition had not occurred. This is different from the abort after a `fatal' error condition. In that case the cursor is left in the line that caused the error. In either case it is rather easy to proceed execution as a new input command will start execution at the line of the cursor. A good example of such a condition would be a lengthy set of actions that is interrupted due to lack of memory. During a stream action stedi doesn't execute garbage collections, unless forced to do so with the `garbage' command, so one second pause after such an interrupt may be sufficient to clean up the memory, after which one can continue by using the Ctrl-R command.

The example below is a stream program that removes all lines that contain the string 'Remove me' from a file. The file is supposed to reside in buffer 1 and the stream file should be in buffer two:

      u-
     *    This turns off the screen updates
      alt-1
     *    Go to buffer 1.
      /Remove me/>.
     *    Search forward for the string.
     *    The period option makes the stream stop
     *    when the string is not found any more.
      deleteline
     *    delete this line.
      alt-2
     *    Go to buffer 2 (the buffer with the stream!)
      home
     *    Go to line 1. This means that the next line
     *    to be executed is line 2.

Of course the above could be obtained easier with a macro. The I command allows however a few possibilities that the macro's cannot offer. One is that a stream script can modify itself. In rare occasions this can be handy (but don't complain when you get in trouble). The other more useful feature is that because a stream script isn't a macro the variables that are defined in it will not be removed after the script has terminated. This means that it offers the opportunity to set a number of variables that the user would like to have around. Note however that if the stream script is called from a macro all its variables will disappear again when the macro is finished.

If stream files invoke themselves or other stream files in a recursive fashion a crash may result if the algorithm that was used doesn't terminate in time. There should however be enough space for at least 16 recursions. This may depend somewhat on the instructions that are used at the deepest levels.

No attempts have been made to forbid certain actions as this could restrict the user needlessly. If during a particularly complicated operation stedi starts malfunctioning it is left to the good taste of the user to determine whether he was asking for trouble or whether a serious shortcoming of stedi has been found. Anyway the author would like to know about it.

The third stream facility in stedi is something that is usually interpreted as stream editing. At the startup of the editor the user indicates that a special file contains edit instructions and should be used to act upon at least one of the other files. With stedi this is done with the -i or -x parameter in the command tail at startup. The file after this parameter is interpreted as a macro. The macro is loaded and all other arguments after the name of the macro are passed as arguments to the macro. The editor starts up, the macro is executed and the file in buffer 1 is saved. After this the editor terminates execution and returns to the command processor. Whether there will be an enormous visual display during the execution of the macro depends on whether the screen updates are switched off in the macro.