The Rondeau Methodology for Mass Search and Replace
SEARCH, INTERVENE, and REPLACE

First Draft by Bill Buckels June 1994, Revised and Simplified January 2000

Overview:

On many projects there is a need to search all system files for
occurrences of strings and replace or substitute these selectively.

A single-pass "robot" application such as a "Search and Replace" does
not offer the capability for the programmer to "Intervene" and avoid
unwanted substitutions. Consequently, "surprises" occur, and a fairly
extensive review of the changed files is required to ensure that the
replacement has been done in a way that makes sense.

Therefore, it is clear that an intelligent (human) intervention and
review between the Search and the Replace levels of this type of process
will largely prevent errors that may not be found easily. To address
this problem, we have developed a 2-pass method of Search and Replace
that works quickly is simple to understand and maintain, and allows for
programmer intervention.

The Process: Search, Substitute, and Replace

The process is broken-down into 4 Parts:

1.  SGREP - Search and Review and Create a Search List - Use the List
with SGREP to Search All Suspected Source to be Changed and Review Those
Changes.  Redirect output from the SGREP search to a text file to be
used in Step 2.

2.  TEXT EDITOR - Replace, and Review, and create a Finished Script by
editing the output from SGREP. This is the Interpretive or the Main
Intervention process.

3. SIR - Sequential Substitution - The Edited output from step 2 is
processed against the source files from the Search. When the target line
in the target file is reached, it is overwritten with the processed line
from the script.

4. Audit - Use the log file created by SIR to review the changes.
The Tools and The Techniques:

SGREP(C) CopyLeft Bill Buckels 1994-2000. All Rights Reversed.
Usage is "SGREP ["search spec"] [filename(s)] -icq!s"
A List of Multiple Search Specs can also be Used :
Usage is "SGREP @[listname] [filename(s)] -i!s"
Switches are : i (ignore case)
             : c (ignore c comments)
             : q (no banner)
             : ! (ignore clarion comments)
             : s (match only lines with clarion strings)	

SIR(C) CopyLeft Bill Buckels 1994-2000. All Rights Reversed.
Usage is "SIR [sgrep.grp]

Details:

The process is done using 2 very efficient command line utilities that
were specifically written for this purpose using the C language. The
programmer also uses an editor. The processing speed of these utilities
is quite good. A brief description of the tools and their use follows:

1. SGREP - Intelligent "Multi-Find" style of Grep that is written with
awareness of Clarion and C Language Source Files. All the source files
to be processed are moved into a single directory, and SGREPped using a
list of "search strings". The output from SGREP is redirected to a disk
file. SGREP is very quick, and the source for the entire system can be
processed in a few minutes.

2. EDITOR - The Intervention and Review of SGREP output and removal of
unwanted "Search" lines is done in a programmer's editor. Care is taken
to not change the format of the SGREP output. (The SGREP output is the
only GREP that can be used for this process). At this time, the
programmer uses the text editor to perform any search and replace that
needs to be done. It is generally easier to do the search and replace in
one file as opposed to a large number of files.

3. SIR - The Intervened Search Replace utility runs very quickly using
the SGREP output (the .GRP file), and within a matter of minutes can
process several hundred source files. The LogFile created by SIR can
later be reviewed to make sure the results are as expected.

Additional:

Because this is a relatively low level process, and because this process
requires that the programmer know the system and understand the
implications of the task, this method should be done with a clear
understanding of the tools and their use, and also of the programs to be
modified. A high degree of productivity can then be achieved.

A fair amount of preparation is required (i.e. this is a "batch" style
process and it is most effective on a system basis rather than on a
program by program basis.) The editing is best done using a multiple
window editor like QEDIT, in the source directory, and source files and
substitution lists can be referenced in the editor to ensure integrity.

Under no circumstances should different source be used between steps in
this process. Since this process is incremental there is a possibility
of this happening.

And finally, all sources to be modified, together with scripts etc.,
should be in Read/Write format in a single working directory.

End of Document
