ReadMe File for

Sgrep and Sir (C) CopyLeft Bill Buckels 1994-2000
All Rights Reversed.
Mass Search and Search and Replace Utilities for Windows 95/98/NT
Version 2.0

Program Description
-------------------

Sgrep and Sir(C) are two command line utility programs for Windows
95/98/NT that allow a programmer to search for strings in text files,
and/or make mass changes (search and replace) to groups of source code
files using an intelligent intervention step. Sgrep can also be used
simply as a text search utility. It has nicely formatted output which is
processed by SIR (as a script) to perform replace operations.

Usage
-----

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]

Please see Appendix A - The Rondeau Methodology for Mass Search and
Replace, for detailed usage.

Reporting Bugs
--------------

Even though Sgrep and Sir(C) are FreeWare, we do not want bugs to make
your life miserable. To report Bugs, I have an online form on my WebSite
at:

http://www.escape.ca/~bbuckels

Please note: Sgrep and Sir(C) were written for fun, and as a public
service, but mostly to make my working life easier. Enhancement requests
will probably not be accepted, since the goal is not to be perpetually
developing these products.

Open Source
-----------

Sgrep and Sir(C) are distributed as FreeWare with Open C Language Source
Code. They are written in hard-wired 100% Pure Industrial Strength
Microsoft 32 Bit C, and compiled under MSC Version 12 (Visual Studio 6).
The code in this program is pretty simple and you shouldn't have much
trouble reading it.

Installing and Running Sgrep and Sir(C)
---------------------------------------

Install Sgrep and Sir(C) by "UNZIPPING" Sir20.ZIP complete with
pathnames to the drive of your choice. If you decide to install Sgrep
and Sir(C) to Drive C:, Sgrep and Sir(C) will be installed into the
directory C:\Sir.

Start Sgrep or Sir from the Command Line.

Licence Agreement
-----------------
Sgrep and Sir(C) CopyLeft Bill Buckels 1994-2000.
All Rights Reversed.

Sgrep and Sir(C) is distributed as FreeWare with Open Source.

You have a royalty-free right to use, modify, reproduce and distribute
this program and its source code and associated files in any
non-competitive way you find useful, provided that you agree that Bill
Buckels has no warranty obligations or liability resulting from said use
or distribution in any way whatsoever. If you don't agree, remove
Sgrep.Exe and Sir.Exe and all associated files from your computer now.

Bill Buckels
589 Oxford Street
Winnipeg, Manitoba, Canada R3M 3J2

Email: bbuckels@escape.ca
WebSite: http://www.escape.ca/~bbuckels

Sgrep and Sir(C) are not a derivative work of any other authors and are
the exclusive property of Bill Buckels and Grant Rondeau (the authors).
All methods are the product of work and study by the authors.

Sgrep and Sir(C) was not produced in anticipation of profit.

Appendix A
----------

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 Appendix A
End of ReadMe
