Visual Search & Replace 1.0 (c)1995

Please read this document in its entirety before using this product.  The following sections make up this document:

I.	Description of Visual Search & Replace 1.0
II.	Shareware -- What is it?
III.	Registration -- How to register
IV.	Legalese -- Conditions of use of this product
V.	Cautions -- Protect your data
VI.	Installation -- How to install
VII.	Usage -- Detail on how to get the most out of this product
VIII.	Upcoming features -- What to expect in the next version
IX.	Contact -- How to contact the author

I.	Description

Visual Search & Replace performs text searches across multiple text files with the option of replacing all, some, or no occurrences.  It is unique in that the surrounding lines of text are displayed and the search text is highlighted to show the user the context in which it is found.  That way, the user can decide whether or not to proceed with the replacement.  This is especially useful for programmers or others who often work with text files and need to perform mass replacements.  The product was developed entirely in C++ and has been optimized for high performance.  Unlimited file sizes, wildcards, multiple filemasks and subdirectory searches are supported, and the user has control over many configurable options.  Both DOS and Windows versions are available.

II.	Shareware

Visual Search & Replace is NOT public domain software or Freeware.  Rather, it is SHAREWARE, which is a "try before you buy" software distribution concept.  Please feel free to pass around copies of the original, complete, unmodified .ZIP file to other people, upload it to a BBS, or otherwise distribute it to those whom you feel may save time and effort by using it.  You are not authorized to distribute it in any form other than the original .ZIP file.  I would like to reach as large of an audience as possible, so if you think it is a useful product, please pass it along.

You are authorized to use the product on a trial basis for a short period of time to familiarize yourself with its features and evaluate its usefulness.  If you like the product and use it, you are required to register it.

III.	Registration

Registration is simple and straightforward.  DOS and Windows versions must be registered separately, but the registration process for each is basically the same.  For the DOS version, simply type VSR <Enter> at the command prompt (with no command line parameters) and you will be asked if you would like to register.  Choose Yes.  For the Windows version, run VSRW.EXE and click on the Register button.

For either version, the caption "Software Registration" will be displayed (along with the Program Name and Serial #) and you will be presented with the following options:  Print Registration Form, Register, or Cancel.  Choose Print.  After printing out the registration form, fill in the requested information.  Please print legibly.  If you do not have access to a printer, please provide the following information on a piece of paper:

Program:  Visual Search & Replace 1.0
Operating System Version:  DOS or Windows
Serial #:  (This is a number in the following format:  ###-####-#####.  It is unique to your copy of the program, and must be provided.  The DOS and Windows serial #s will be different.  The serial # may be obtained from the Software Registration screen.)
Your Name, Company (if applicable), Address, City, State, Zip Code, Country, Phone, Fax, and eMail address.

Make out a check payable to "Ryan J. Smith" for the amount of $20 U.S. for each version of the program.  (NJ residents add 6% sales tax).  Send the completed registration form(s) and payment to:

Ryan J. Smith
977 Valley Road D3-104
Gillette, NJ 07933

You will be eMailed, faxed, or mailed a registration password.  eMail is the preferred method, so please provide your eMail address (if you have one) on the registration form.  When you receive your password, navigate to the Software Registration screen as described above.  Choose Register.  You will be prompted for your password.  Type it in carefully and press <Enter>.  You will notice that the "Unregistered Copy" heading will no longer appear when you run the program.

Your honesty in registering this product is greatly appreciated.

IV.	Legalese

1.  This product may only be distributed in its original, complete, unmodified form as a single .ZIP file.  Anyone may distribute this product providing that there is no fee charged for distribution.

2.  Unregistered use of this product is only authorized for a reasonable evaluation period.  For continued use, this product must be registered as outlined in the Registration section of this document, with any and all payments made only to the author of the product.

3.  Through proper registration, the user is granted a single user license to use the product indefinitely.  The provisions of this license are as follows.  Distribution may only take place as outlined above.  Copies of the registered product are prohibited except for backup purposes.  Concurrent use of a single registered product is prohibited.  For network use, each user must have his/her own license.

4.  This product may not be bundled with any other commercial product without the express written consent of the author.

5.  THIS PRODUCT IS PROVIDED ON AN "AS-IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OR CONDITIONS AS TO THE FUNCTIONALITY, DATA INTEGRITY OR PROTECTION, MERCHANTABLE QUALITY OR FITNESS OF THIS PRODUCT FOR ANY PARTICULAR PURPOSE OR USE.  IN NO EVENT SHALL THE AUTHOR BE LIABLE TO ANY PARTY WITH RESPECT TO ANY LIABILITY, LOSS OR DAMAGE CAUSED OR ALLEGED TO BE CAUSED DIRECTLY OR INDIRECTLY BY THIS PRODUCT.

V.	Cautions

It is strongly recommended that you make backups of the files you intend to manipulate before running this program.  While temporary files are used as a safety measure and the original file is only overwritten once the operation has completed (via a quick delete and rename sequence), system errors and power failures do occur and it is better to be safe than sorry.

Caution should be used in running this program.  It should only be used on text files.  Usage with application files from word processors, spreadsheets, databases, graphics programs, etc. will very likely cause corruption, because such files typically rely on special binary information and strict file positions for data structures.  There is no undo operation, so be very careful in specifying wildcards, directories, and search and replace strings.

Used carefully, this program should be a valuable addition to the user's arsenal of productivity tools.

VI.	Installation

This product is distributed as a single .ZIP file named VSR10.ZIP.  The fact that your are reading this file means you have already unzipped it.  VSR10.ZIP contains the following files:

VSR.EXE		DOS program
VSR.LIC		DOS program license file (do not tamper with or delete or the program will not run)
VSRW.EXE	Windows program
VSRW.LIC	Windows program license file (do not tamper with or delete or the program will not run)
VSR_HELP.TXT	This help file

You will want the Visual Search & Replace program to be accessible from any drive or directory, so you should copy the files into a directory in your path, or create a new directory, copy the files there and add the new directory to your path statement in AUTOEXEC.BAT.  If you are unfamiliar with what a search path is, simply copy all the files into your DOS directory or into your WINDOWS directory.  Wherever you choose to place the files, be sure to keep them all together in the same directory for proper execution.  You may also wish to create a program group and/or icons for the program in Windows via Program Manager.

VII.	Usage

Don't forget to make backups of your files before running Visual Search & Replace.  You'll be glad you did.  The product is intended to be easy to use and understand, especially with this help file.  If you would like a printout of this help file, open VSR_HELP.TXT in your Word Processor and print it.

DOS:

All parameters are provided to the DOS version of Visual Search & Replace via the command line.  The command line syntax is as follows (To display this info, type VSR (with no parameters) at the DOS command prompt):

vsr [/switch(es)] search_string replace_string filemask(s)

Switches:
	c	allow "C" style escape sequences
	f	show File statistics
	i	Ignore case in search
	p	do not Prompt to confirm changes
	s	search Subdirectories
	t	Touch files that are changed

Help:
	vsr ?

By default, no switches are set, so the default mode of operation is:  literal search and replace strings, do not show statistics for each file, case sensitive search, prompt user to confirm changes, do not search subdirectories, and do not update the timestamp of the files that are changed.

The other switches are self-explanatory, but a more detailed description of the /c switch would be helpful.  When not specified, all characters in the search and replace strings are taken literally.  If specified, the "C" language style escape sequences preceded by a backslash (\) will be interpreted as follows:

Seq.	Value	Name
\a	0x07	Alert (bell)
\b	0x08	Backspace
\f	0x0c	Formfeed
\n	0x0a	Newline
\r	0x0d	Carriage return
\t	0x09	Horizontal tab
\v	0x0b	Vertical tab
\?	0x3f	Literal quotation mark
\'	0x27	Single quotation mark
\"	0x22	Double quotation mark
\\	0x5c	Backslash
\ddd	ANY	ASCII character in octal notation (up to 3 digits (0-7))
\xdd	ANY	ASCII character in hex notation (up to 2 digits (0-9|a-f))

Note:  In this release (1.0) of the program, the ASCII character zero (Octal:  \000, Hex:  \x00) is not allowed in either the search or replace string.  Furthermore, files that contain the zero character will not be processed.

Example.  To replace "word" with "two words" in all .TXT files in the current directory, you would type the following at the command line:

vsr word "two words" *.txt

Notice that a search or replace string with spaces must be enclosed in quotes.  If not, the command line will not be understood correctly.  For example, if quotes were omitted in the above example, Visual Search & Replace would replace the word "word" with the word "two" in the file WORDS (if it exists) and in all .TXT files.  If a particular file does not exist or there are no matches for a filemask, that file or filemask is simply ignored.  However, if the filemask is invalid (for example, a drive or directory is specified which does not exist), a warning message will be displayed.

Example.  To replace all tabs (in files with the extensions .C and .H in the specified drive and directory) with 4 spaces, specify the following on the command line:

vsr /c \t "    " d:\proj1\*.c d:\proj1\*.h

Example.  To delete the word bogus (in any form of capitalization) from the file test.txt in the current directory and all subdirectories, and touch the files that are changed, the command line should be:

vsr /i /s /t "bogus" "" test.txt

Visual Search & Replace searches through all files that match the filemasks specified.  Both full and relative paths are supported.  Filemasks should be separated by a space.  Multiple switches can be specified at once, but only a single search string and a single replace string may be specified.  "C" style escape sequences may be specified in both the search and replace strings.  Multi-line search strings are not supported.  If the search string or replace string include spaces, they should be enclosed in quotes.  Unlimited file sizes are supported, with a maximum line length of 1024 characters.

Example.  Suppose a C++ programmer wanted to change the name of a variable from "length" to "iTextBufferLength" throughout her source code in order to be more descriptive and to follow Hungarian notation.  Rather that tediously opening each file individually and replacing the text with an editor, she could simply run Visual Search & Replace.  Her project consists of 82 source files, with the extensions .CPP, .H, .I, spread out over several directories.  She wants the search to be case sensitive in order to reduce the number of hits, since she knows the variable is always in lowercase letters.  Since the word "length" also appears in comments and displayable text, she wants to be prompted for replacements.  She would like to know the file statistics (# of lines, occurrences, and replacements).  She changes directories to the root of her project on G:\XYZ\WK2.  At the command line she types:

vsr /f length iTextBufferLength code\*.cpp hdr\*.h inline\*.i

Rather than specifying each subdirectory explicitly, she could use the /s switch to search the subdirectories of each filemask.  In this case, all the directories she wishes to search are subdirectories of the current working directory, so she could replace the above command line with the following:

vsr /s /f length iTextBufferLength *.cpp *.h *.i

When an occurrence of the search string is found, and the /p switch is not specified (default), the filename and its contents immediately surrounding the found occurrence are displayed.  For lack of a better word, let's call this portion of the file the neighborhood.  The neighborhood consists of the seven lines preceding the occurrence, the line the occurrence is found on, and the seven lines following the occurrence.  The occurrence is highlighted, and the line number and character position (column) of the occurrence are displayed.  Since long lines are supported but the screen only displays 80 characters, the ability to scroll left or right is provided to see the neighborhood in its entirety.  When displayed, the occurrence is automatically scrolled into view.  The user is prompted with the following, and has the following options, each of which is a single key press:

Replace (<A>ll/<Y>es/<N>o/<C>ancel/<Q>uit/<-Scroll->) ?

A	Replace the current and all subsequent occurrences of the search string with the replace string in this file only without prompting any more until the next file is encountered.  Continue searching in next file.
Y	Replace this occurrence of the search string with the replace string. Continue searching in this file.
N	Do NOT replace this occurrence of the search string with the replace string. Continue searching in this file.
C	Cancel the search and replace operation for this file only.  Discard any replacements made to this file (it remains unmodified).  Continue searching in next file.
Q	Terminate the search and replace operation.  Discard any replacements made to this file (it remains unmodified).
<-Left	Pressing the left arrow cursor key will scroll the neighborhood so you can see further to the left.
Right->	Pressing the right arrow cursor key will scroll the neighborhood so you can see further to the right.

Therefore the user has flexible replacement options for any occurrence of the search string in any file, with the benefit of seeing where in the file the occurrence is found.  In many cases, the user wants to be selective in deciding which replacements to make.

If the /p switch is specified, the program runs in batch mode.  It never displays the neighborhood or prompts the user for input.  It simply searches through all files that match the file mask and replaces all occurrences of the search string with the replace string.  Be very careful when using the /p switch, because it will perform a mass replacement for which there is no undo.  Be sure to make backups of files before running the program, whether or not it is running in batch mode.  Batch mode can be very useful for certain operations.  For example, perhaps you regularly receive a group of files from an on-line service, from your MIS department, or download them from a mainframe.  You may want to perform an uninterrupted manipulation on the files.  You could create a DOS batch file which repeatedly calls Visual Search & Replace with the /p switch and other appropriate parameters specified to perform a fairly sophisticated data manipulation in a high-speed, automated fashion.

Windows:

Both DOS and Windows versions utilize the same high performance search and replacement engine.  The interface is nearly identical as well, but there are some important differences between the two programs, which will now be discussed.  Windows users should read the DOS section above, as it explains the basics and only the differences will now be presented.

The Windows version of the program is VSRW.EXE.  It can receive parameters from the command line just like the DOS version.  The fields and options in the graphical user interface are initialized based on what parameters are passed to the program.  If no parameters are passed, the fields are blank and the options are the default ones.  If all of the required parameters are passed, the program automatically launches the search and replace operation.  Otherwise, you should fill in the remaining fields and then click on the Go button to launch the search and replace operation.

Edit fields are provided for the search string, replace string, and filemasks.  History lists for each of these fields are maintained, and may be accessed by clicking on the down arrow next to the field and selecting an item from the list that appears.  Check boxes are provided to set or clear the options, each of which corresponds to the command line switches.

You do not need to enclose strings with spaces in quotes in the search and replace fields in the graphical user interface as you do on the command line.  Whatever you type in the field will be considered as a single parameter to the program.  So how do you delete text?  Type the search text in the Search field, and leave the Replace field blank.

The default configuration is the same as for the DOS version.  Don't be confused by the check box for Confirm Changes.  This defaults to checked, which means prompt to confirm changes.  If you clear the check box, this means do not prompt to confirm changes, and is the same as if you specified the /p switch in the DOS version.  To exit the program, click on Exit.  To display this help file, click on the Help button.

When an occurrence of the search string is found, the neighborhood around it is displayed in a window and the user has the same replacement options as in the DOS version.  The neighborhood may be scrolled to the left or right by clicking on the scroll bar at the bottom of the display area.  The user may also select the text in the display area (if desired) by clicking with the mouse at the start of the text to be selected, dragging the mouse to the end of the text to be selected, and releasing the mouse button.  The user may then press Ctrl+C or Ctrl+Insert to copy the text to the clipboard and subsequently paste the text into another application by using Ctrl+V or Shift+Insert.  The user may reselect the occurrence by clicking on the Reselect button.

VIII.	Upcoming features

Still hungry?  Want a little more functionality?  A few more features?  Then keep your eyes peeled for the next release (2.0), which should boast support for many of the following features:

	Regular expression search
	Word search
	Increased line length
	Persistent search profiles
	Log file
	Undo
	Binary files
	Hexadecimal viewer

Registered users will be able to upgrade to the next release (2.0) at a substantially reduced cost, whereas.  newcomers will have to pay full price.

IX.	Contact

Please send comments or questions to the following physical or virtual addresses.  eMail is preferred.  There is no help desk or dedicated product support available.  I hope you enjoy using this great product.

Ryan J. Smith
977 Valley Road D3-104
Gillette, NJ 07933

76551.2060@compuserve.com

