Examples

  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.