EDIT directive

Edits text vectors.

Options

CHANNEL = scalar or text	Text structure containing editor commands or a scalar giving the number of a channel from which they are to be read; default is the current input channel
END = text	Character(s) to indicate the end of the commands read from an input channel; default is the character colon (:)
WIDTH = scalar	Limit on the line width of the text; default *
SAVE = text	Text to save the editor commands for future use; default *

Parameters

OLDTEXT = texts	Texts to be edited
NEWTEXT = texts	Text to store each edited text; if any of these is omitted, the corresponding OLDTEXT is used

Description

The EDIT directive edits each text in the OLDTEXT list, storing the results in the corresponding structure in the NEWTEXT list. It both edits and stores each text before moving on to the next. If you have not already declared any of the texts in the NEWTEXT list, it will be declared implicitly. If you give a missing identifier (*) in the NEWTEXT list, the edited version simply replaces the values of the original: thus the old text will be overwritten by the new text. You can also omit a text from the OLDTEXT list; you might do this if you wanted to form the values of the new text entirely from within the editor.

The CHANNEL option tells Genstat where to find the editing commands. A scalar specifies the number of an input channel from which the commands are to be read. Alternatively, you can specify a text structure containing the commands. In either case the commands should be terminated by the string specified by the END option. The end string can be more that one character; the default is the single character colon (:). Genstat gives a warning if you have forgotten to specify the end string in a text of commands. The default for the CHANNEL option is to take input from the current input channel.

The WIDTH option specifies the maximum line length for vectors of commands and of text, the default being 80 and the maximum being 255.

The SAVE option allows you to specify a text structure to store the edit commands, so that you can save them for future EDIT statements.

Commands for the editor can be given in either upper or lower case. You can put as many commands as you like on a line, subject only to the width restriction set by the WIDTH option. Commands must be separated by at least one space. You cannot put spaces into the middle of a command, unless they are part of a character string (or part of a sequence of commands).

The character that separates the parts of a command is written here as /, but you can use any character for this other than a space or a digit.

Genstat puts the lines from the old text into an internal buffer, where they are modified according to the commands that you specify. While you are editing, Genstat moves a notional marker around the buffer. The marker can be moved backwards or forwards along a line or between lines. So you can move around the text and modify the lines in any order. Some commands move the marker automatically, as explained in the definitions below. If the marker is before the first line of text it is at the [start] position; if it is after the last line of text it is at the [end] position. The line that currently contains the marker is called the current line. Genstat does not write anything to the new text until the edit has been completed (so if you use the Q command, the new text is left unaltered).

Some commands allow you to specify a number: for example Dn deletes the next n lines. Genstat gives a warning message if this number is zero or is not an integer.

The commands are as follows.

A       Insert the next line of text from the buffer, immediately after the marker within the current line.

B       Break the current line at the marker position. Text before the marker is written as a new line to the internal buffer and text after the marker becomes the new current line with the marker at character position 1.

C       Cancel edits performed on the current line by restoring it to the form in which it was most recently read from the buffer. Note that if you have previously edited the line and then moved to some other line, it is the previously edited form that will be given, not the form as originally in the old text; also, if you have given any A or B commands during your modification of the current line, their effects are not negated, so for example any lines that have been inserted into the current line by A will be lost.

D       Delete the current line, and make the next line the current line with the marker at character position 1.

Dn     Delete the next n lines (including the current line), making the next line after that the current line with the marker at position 1.

D+n   Synonymous with Dn.

D+     is a synonym for D or D+1.

D+*    Delete from the current line to end of text. The current line is then [end].

D*      Synonymous with D+*.

D-    Delete the current line, making the previous line the current line with the marker at character position 1.

D-n  Delete the current and previous n lines, making the line before that the current line with the marker at character position 1.

D-    is a synonym for D-1.

D-*   Delete the current line and all previous lines, the current line is then [start].

D/s/   Delete from the current line to the line with the next occurrence of the character string s. The marker is placed immediately before the character string s in the located line. If s occurs after the marker on the current line, the marker is moved up to s and no lines are deleted.

D-/s/ The same as D/s/, except that it moves backwards through the text, deleting all lines from and including the current one until the first occurrence of a line containing the character string s. The marker is placed immediately before the located character string s. If s occurs before the marker on the current line, the marker placed before s and no lines are deleted.

F/i/     Inserts the contents of the text structure with identifier i immediately before the current line. The marker is not moved.

G+/s/t/ substitutes string t for all occurrences of string s found after the marker on the current and subsequent lines, and moves the marker to the end of the text.

G/s/t/ is a synonym for G+/s/t/.

G-/s/t/ substitutes string t for all occurrences of string s found before the marker on the current and previous lines, and moves the marker to the start of the text.

I/s/     Inserts the string s as a new line immediately before the current line. The marker is not moved.

L        Moves the marker to the start of the next line, which can be [end].

Ln      Moves the marker to the start of the nth line after the current line. So L1 gives the next line.

L+n    Is synonymous with Ln.

L+      Is synonymous with L or L+1.

L+*    Moves the marker to [end].

L*      is a synonym for L+*.

L-n   Moves the marker to the start of the nth line before the current line, which can be [start]. L-1 gives the line immediately before the current line.

L-     Is synonymous with L-1.

L-*    Moves the marker to [start].

L+/s/ Moves the marker to the position immediately before the next occurrence of the character string s after the current marker position; this occurrence need not be on the current line. If the string s is not found, the marker will be located at [end].

L-/s/ Moves the marker to the position immediately before the first occurrence of the string s before the current marker position; this occurrence need not be on the current line. If the string s is not found, the marker will be located at [start].

P       moves the marker one character to the right along the current line.

P+n   Moves the marker n characters to the right of the current position within the current line. You cannot move the marker beyond the maximum line length (which will vary between computers, but is normally the same as the width of your local line-printer).

P+     is a synonym for P or P+1.

P+*    Moves the marker to the position immediately after the last non-blank character in the current line. This can be to the left of the current marker position.

P-n   Moves the marker n characters to the left of the current position within the current line. The marker cannot be moved to the left of character position 1.

P-     is a synonym for P-1.

P-*   Moves the marker to the position immediately before the first non-blank character after character position 1. This can be to the right of the current marker position.

Pn     Moves the marker to the character position n within the current line, counting from the left and starting at 1. The maximum value of n varies between computers but is normally the same as the width of your local line-printer.

Q       Abandons the current edit, leaving the original text unaltered.

R+/s/t/ substitutes character string t for the next occurrence of character string s after the marker on the current or subsequent lines, and moves the marker to the position immediately after t.

R/s/t/ is a synonym for R+/s/t/.

R-/s/t/ substitutes string t for the nearest occurrence of string s before the marker on the current or previous lines; the marker moves to be immediately before string t.

S/s/t/ Substitutes the string t for the next occurrence of string s after the marker within the current line. The marker is moved to the character position immediately after the last character in t. If s is null (when the command is S//t/) then t is inserted immediately after the marker. If t is null (when the command is S/s//), then s is deleted from the line.

V       Turns on the verification mode. Then, if you are working interactively, the current line will be displayed each time that Genstat prompts you for commands. By default the marker is indicated by the character > but you can change this by the command Vc or V+c.

Vc      Turns on the verification mode (see V), and changes the marker character to c.

V+c    Is synonymous with Vc.

V-     Turns verification mode off (see V).

(cseq)n Repeats the command sequence, cseq, n times. The command sequence cseq can be any valid combination of editing commands, each separated by at least one space. The complete sequence, including brackets and repeat count, must all be on a single line. You can nest sequences up to a depth of 10.

(cseq)* Repeats the command sequence cseq until [end] or [start] is encountered. In all other respects (cseq)* behaves exactly as (cseq)n; so it would be equivalent to putting n equal to some very large number.

Options: CHANNEL, END, WIDTH, SAVE.

Parameters: OLDTEXT, NEWTEXT.

Action with RESTRICT

If any of the old texts are restricted, they must all be restricted to exactly the same set of units. Then only those units will be involved in the edit. When a restriction is in force, you cannot add or delete any units (or lines).

See also

Directives: TEXT, CONCATENATE, EQUATE, TXBREAK, TXCONSTRUCT, TXFIND, TXPOSITION, TXREPLACE.
Procedures: APPEND, SUBSET, STACK, UNSTACK, VREPLACE.
Functions: CHARACTERS, GETFIRST, GETLAST, GETPOSITION, POSITION.
Commands for: Calculations and manipulation.

Example

" Example EDIT-1: Use of the Genstat editor"

TEXT [VALUES='B.J. Adams','J.S. Baker','K.R. Clarke',\ 
   'A.T. Day','R.S. Edwards','T.W. Field','S.I. Good',\ 
   'D.M. Hall','H.M. Irving','C.C. Jones'] Name
& [VALUES='S//Mr. /','L','(S//Dr. / L)4','L-2','S/D/M/','L+2',\ 
   'S//Ms. /','L','S//Mr. /','L S//Miss. /','(L S//Dr. /)2',':'] Eds
EDIT [CHANNEL=Eds] Name
PRINT Eds; JUSTIFICATION=left
& Name; JUSTIFICATION=left