Replaces a subtext within a text structure.
Options
NTIMES = scalar |
Number of times to search for the OLDSUBTEXT and replace it; default 1 |
|---|---|
CASE = string token |
Whether to treat the case of letters (small or capital) as significant when searching for the OLDSUBTEXT within the OLDTEXT (significant, ignored); default sign |
MULTISPACES = string token |
Whether to treat differences between multiple spaces and single spaces as significant when locating the OLDSUBTEXT within the OLDTEXT, or to treat them all like a single space (significant, ignored); default sign |
DISTINCT = string tokens |
Whether to require the OLDSUBTEXT to have one or more separators to its left or right within the OLDTEXT (left, right); default * |
SEPARATOR = string |
Characters to use as separators; default ' ,;:.' |
SAMELINE = string token |
Whether to ignore matches in the OLDTEXT where the OLDSUBTEXT is not all on the same line (yes, no); default no |
Parameters
OLDTEXT = texts |
Texts to be edited |
|---|---|
NEWTEXT = texts |
Texts with OLDSUBTEXT replaced by NEWSUBTEXT; if no NEWTEXT is supplied, the new values replace those in the corresponding OLDTEXT |
OLDSUBTEXT = texts |
Text to look for in each OLDTEXT |
NEWSUBTEXT = texts |
Text to replace OLDSUBTEXT |
COLUMN = scalars |
Position of the column within OLDTEXT where the first character of NEWSUBTEXT has been placed |
LINE = scalars |
Number of the line within OLDTEXT where the first character of NEWSUBTEXT has been placed |
ICOLUMN = scalars |
Column within OLDTEXT at which to start the search |
ILINE = scalars |
Line within OLDTEXT at which to start the search |
ENDCOLUMN = scalars |
Position of the column within OLDTEXT where the last character of NEWSUBTEXT has been placed |
ENDLINE = scalars |
Number of the line within OLDTEXT where the last character of NEWSUBTEXT has been placed |
NREPLACED = scalars |
Number of subtexts replaced |
Description
The TXREPLACE directive replaces a subtext within a Genstat text structure. The text containing the subtext is specified by the OLDTEXT parameter. The OLDSUBTEXT parameter specifies the subtext to be replaced, and the NEWSUBTEXT parameter specifies the subtext to replace it. By default a single occurrence of the subtext is replaced, but you can use the NTIMES option to replace several. It you set NTIMES to a negative value, all occurrences are replaced. The NREPLACED parameter can save the number of replacements that were actually made (which may be less than NTIMES if fewer were found in the OLDTEXT). The new text (after the replacements) can be saved using the NEWTEXT parameter; if this is not set, the values of the OLDTEXT are replaced by the new text.
By default, the search treats the OLDTEXT and OLDSUBTEXT as if they were paragraphs of characters: that is, it takes no account of the line breaks within the two text structures, regarding each one as equivalent to a space. However, you can set option SAMELINE=yes to treat line breaks differently from spaces. Matches are then recognised only if they are all on a single line.
TXREPLACE usually takes account of the case of letters (small or capital) when looking for the OLDSUBTEXT within the OLDTEXT. So for example 'GenStat' would not match with 'Genstat'. However, you can set option CASE=ignored to ignore differences in case. It will usually also treat multiple spaces as significant, but you can set option MULTISPACE=ignored to treat them all like a single space.
Option DISTINCT is useful if you are looking for distinct words or phrases. The left setting requires the OLDSUBTEXT to begin either at the start of the OLDTEXT, or to be preceded in the OLDTEXT by a separator (such as a space or comma). Similarly, the right setting requires the OLDSUBTEXT to end within the OLDTEXT with a separator (or to be at the end of the OLDTEXT). The separators are specified by the SEPARATOR option.
The ICOLUMN and ILINE parameters can specify a starting column and line for the search. So you can leave an initial section of the OLDTEXT unchanged.
You can use the COLUMN parameter to save the column within the OLDTEXT where the first character of the NEWSUBTEXT has been inserted, and the LINE parameter to save its line within the OLDTEXT. These are both set to zero if the OLDSUBTEXT was not found. If NTIMES is greater than one, they save the location of the final replacement. Similarly the ENDCOLUMN and ENDLINE parameters can save the position of the last character of the NEWSUBTEXT within the OLDTEXT.
Options: NTIMES, CASE, MULTISPACES, DISTINCT, SEPARATOR, SAMELINE.
Parameters: OLDTEXT, NEWTEXT, OLDSUBTEXT, NEWSUBTEXT, COLUMN, LINE, ICOLUMN, ILINE, ENDCOLUMN, ENDLINE, NREPLACED.
Action with RESTRICT
Any restrictions are ignored.
See also
Directives: TEXT, CONCATENATE, EDIT, EQUATE, TXBREAK, TXCONSTRUCT, TXFIND, TXPOSITION.
Procedure: VREPLACE.
Functions: CHARACTERS, GETFIRST, GETLAST, GETPOSITION, POSITION.
Commands for: Calculations and manipulation.
Example
" Example 1:4.7.5 "
TEXT Lunch; VALUES=!t(\
'For lunch we will have fish fried in batter, with chips and baked',\
'beans, followed by apple pie with ice cream.')
TXREPLACE Lunch; NEWTEXT=Healthierlunch;\
OLDSUBTEXT=' fried in batter'; NEWSUBTEXT=''
& Healthierlunch; NEWTEXT=Healthierlunch;\
OLDSUBTEXT='chips'; NEWSUBTEXT='new potatoes'
& Healthierlunch; NEWTEXT=Healthierlunch;\
OLDSUBTEXT='baked beans'; NEWSUBTEXT='salad'
& Healthierlunch; NEWTEXT=Healthierlunch;\
OLDSUBTEXT=' with ice cream'; NEWSUBTEXT=''
PRINT Lunch; JUSTIFICATION=left
& Healthierlunch; JUSTIFICATION=left