Example 1: Simple Use of procedure global_replace
The following example assumes that the disks are named UDISK<n>
where <n> is a number, for example UDISK1, UDISK13. This filter
replaces such disk names with the string "DISK_NAME":
global_replace ( 'UDISK' + number, 'DISK_NAME')
The pattern to replace is built from a string literal ('UDISK'), the
concatenation operator (+) and the pattern "number" included in the
supplied definitions file. The pattern "number" matches a sequence of
digits.
The replacement string is the string literal 'DISK_NAME'.
Example 2: Using the Null Pattern
This example uses the supplied "null" pattern with the DECTPU
alternation operator to include an optional element in a pattern.
Supposing that, in the previous example, some of the disk names do
not include the leading "U", for example DISK7. The following filter
replaces disk names with or without the leading "U":
global_replace ( ("U"|null) + "DISK" + number, "DISK_NAME")
Example 3: Using Pattern Variables
The following example filters dates in the form DD-MMM-YYYY, for
example 11-OCT-1999. Because it only filters this one form of date,
it is quicker than the built-in date filter which filters many
different date formats. It is also not the exact equivalent of the
built-in date filter in other respects, for example it treats
37-NOV-0999 as a date, but should be sufficient for most purposes.
day := any(" 123") + digit;
month := "JAN" | "FEB" | "MAR" | "APR" |
"MAY" | "JUN" | "JUL" | "AUG" |
"SEP" | "OCT" | "NOV" | "DEC";
year := any(digits,4);
date := day + "-" + month + "-" + year;
global_replace( date, "dd-mmm-yyyy");
This filter defines the pattern variables "day", "month" and "year"
which are then used to define the pattern variable "date" used in
the call to global_replace.
The "day" pattern uses the DECTPU function "any" to match either a
space or one of the characters "1", "2" or "3", followed by a digit.
The "month" pattern uses the DECTPU pattern alternation operator "|"
to specify a list of alternative string literals.
The "year" pattern uses the DECTPU function "any" with the supplied
pattern "digits". The "4" parameter indicates that exactly 4 digits
are to be matched.
The "date" pattern concatenates these patterns and linking
punctuation.
Example 4: Removing Blank Lines
This filter removes blank lines using
the DECTPU keywords LINE_BEGIN and LINE_END.
global_replace( LINE_BEGIN + LINE_END, '');
The LINE_END keyword absorbs the new line.
The above filter only replaces lines containing no characters. The
following filter also replaces lines containing only spaces and tab
characters:
global_replace( LINE_BEGIN + (white_space|null) + LINE_END, '');
Example 5: Using Partial Pattern Variables to Retain Context
This example demonstrates how to use surrounding text to
identify a string to be replaced without also replacing
the surrounding text.
The following filter replaces the month part of a
date with the string "mmm". For example, the string
"14-OCT-1999" will be replaced by the string "14-mmm-1999":
day := any(" 123") + digit;
month := "JAN" | "FEB" | "MAR" | "APR" |
"MAY" | "JUN" | "JUL" | "AUG" |
"SEP" | "OCT" | "NOV" | "DEC";
year := any(digits,4);
date := (day + "-"@day_part) + month + ("-" + year@year_part);
global_replace( date, 'str(day_part) + "mmm" + str(year_part)',,ON);
The day part of the date and the "-" character are
assigned to the partial pattern variable day_part and
the year part of the date and preceding "-" assigned
to year_part. These partial pattern variables are then
included in the replacement string.
When partial pattern variable are used in the replacement
string they must be evaluated for each replacement. To
do this, set the parameter evaluate_replacement to ON, as
shown above.
When the replacement string is to be evaluated, string
literals must be nested inside further quotes. This is
most easily done by using single quotes for the outer
string and double quotes for any nested string literals,
or vice-versa. Also, any partial pattern variables must be
converted to strings using the DECTPU procedure STR.
Note that including LINE_END in the definition of a
partial pattern variable does not have the effect of
retaining the line break. See example 6 for a
resolution of this problem.
Example 6: Using LINE_END for Context
If the search pattern contains LINE_END, the matched
line break will be removed, causing the next line to
be appended to the current line. To use LINE_END to
only provide context for the search, the line break
must be reinserted. This is done using the parameter
convert_linefeeds.
If the convert_linefeeds parameter is specified as ON, any
linefeed characters appearing in the replacement string
are removed and the built-in DECTPU procedure SPLIT_LINE
is called at the point of the linefeed character.
The following filter replaces any numbers that are the
last characters on a line with the string "x":
global_replace (number+LINE_END, "x"+lf,,,ON)
The "lf" pattern is defined as a linefeed character in the
supplied definitions file.
If a LINE_END is included in a partial pattern variable,
the line break can be retained by specifying the second
optional parameter to the DECTPU STR procedure as a
linefeed character, for example:
global_replace (number+(LINE_END@sep), '"x"+STR(sep,lf)',,ON,ON)
The second parameter to STR specifies the string that
line breaks occurring in the first parameter should be
converted to. Line breaks are retained by specifying
the linefeed character and setting the parameter
convert_linefeeds to ON.
Example 7: Using UNANCHOR to Replace Sections
The DECTPU keyword UNANCHOR can be used to replace sections of
text delimited by specified strings. The following replaces
all text between the strings "/*" and "*/" with the string
"/* Text deleted */". The text may run across line boundaries:
global_replace ( "/*" + UNANCHOR + "*/", "/* Text deleted */")
Note that while a similar effect is possible using the
COMPARE/SENTINEL command, the filter can be applied to individual
tests, whereas the /SENTINEL qualifier applies only to collections.
Example 8: Using Other DECTPU Commands
The global_replace procedure can be used for many filtering tasks.
However any DECTPU commands can be used to build filters. The file
being filtered is read into the buffer "filter_buffer" before the
user filters are applied and written out afterwards.
The following filter uses the DECTPU EDIT procedure to convert all
characters to upper case:
EDIT( filter_buffer, UPPER, OFF)
Note that while a similar effect is possible using the
COMPARE/IGNORE=CASE command, the filter can be applied to individual
tests, whereas the IGNORE qualifier applies only to collections.
The following filter searches for numbers and replaces them only if
they are in a specified range:
POSITION (BEGINNING_OF (filter_buffer));
LOOP
found_range := SEARCH_QUIETLY (number, FORWARD);
EXITIF found_range = 0;
POSITION (END_OF(found_range));
MOVE_HORIZONTAL(1);
value := INT(STR(found_range));
IF (value>350) AND (value<570)
THEN
COPY_TEXT ("XXX");
ERASE (found_range);
ENDIF;
ENDLOOP;
The initial POSITION is required to ensure that the whole of the
filter_buffer is processed, because the editing point is undefined
at the start of each filter. Then, as each number is processed, the
editing point is moved to the end of the number. The MOVE_HORIZONTAL
procedure call is necessary because the previous POSITION leaves the
editing point at the last character of the number, which would
result in an immediate match on the next call to SEARCH_QUIETLY.