home *** CD-ROM | disk | FTP | other *** search
-
-
-
-
- CHANGE User Manual
-
- Utility: CHANGE v1.04
- Date: 21-Oct-1990
- Last Update: 10-Dec-1990
-
- This work is (c) Copyright 1990 by John W. Clinton.
- 23 Goff Street
- Hyde Park, MA 02136
-
- All rights reserved.
- Please pass this software around to your friends and associates. Feel
- free to use this software for a month. If you find CHANGE as useful as
- I do, please Register!. Full registration is $15.00 in U.S. currency.
-
- Registered Users receive the latest version of the software by return
- mail and any updates made to this software for 1 year from the date of
- registration. Registered versions of the software do not have any of
- the advertising in the banner, and all of the output may be redirected
- using the DOS redirection operators. Any special modifications that may
- be required are available by special arrangements.
-
- Help support the Shareware Concept!
-
-
- Disclaimer:
-
- This software is provided 'as is' and is without any warranty of any
- kind, whether express or implied, including, but not limited to the
- implied warranties of fitness for a particular purpose. I will not be
- liable for any special, indirect, incidental, consequential or similar
- damages due to any loss of any kind related to the use of this software
- or for any other reason, even if I or an agent of mine has been advised
- of the possibility of such damages. In no event shall my liability for
- any damages ever exceed the price paid for the license to use software,
- regardless of the form of the claim. The person choosing to use the
- software assumes any and all risks as to the quality and performance of
- the software.
-
- Acknowlegements:
-
- Special thanks to my wife Loretta for putting up with all of the time I
- put in on these little projects.
-
- Thanks to Roedy Green for his constructive feedback on the program and
- documentation.
-
- Description
-
- CHANGE allows you to make global changes to the contents of files. It
- works in much the same way as your favorite word processors global
- change feature. There are two major differences.
-
- 1
-
- CHANGE v1.04
-
-
- o The change(s) can be propagated through all of the files
- specified in a wildcard filespec on the command line;
- o You may specify several changes to be made with one pass
- through the file(s).
-
- This utility is indispensable when:
- o Working with a large number of source files and someone decides
- that variable names need to change.
- o Working on old code and you want to retrofit some naming
- standards.
- o Anytime there are a large number of files and a large number of
- changes that need to be made quickly.
-
- Usage
-
- If no parameters are passed in to CHANGE a usage summary will be
- printed. Additional help is available in all of my programs by using
- the /HELP switch.
-
- In general:
-
- Usage:
- CHANGE <FILESPEC> <matchString> <replacementString> [...] [/switches]
-
- CHANGE - locates all occurances of the specified file( s ) and replaces
- the search string(s) with the specified replacement string(s).
-
- <filespec> may contain a drive, path and filename. The drive is the volume
- that will be searched. all files matching the <filespec> will be modified.
- any path entered within the <filespec> is ignored.
-
- Search and Replace strings are single words and uppercased by default.
- Valid delimiters are ('") and search,replace pairs may be separated by spaces
- or commas. If either string contains DOS redirection characters be sure to
- surround the strings with DOUBLE QUOTES '"'.
- That is the ONLY way to prevent DOS from usurping them.
-
- Currently supported switches: (Upper case is all that is required.)
- /Help - Displays this message.
- /ALl - Causes all fixed drives to be searched.
- /SHow_context - Causes the line that matched to be displayed prior
- to the change and prompts the user to confirm it.
- /Whole_words - Before a change is made check to be sure the string
- that was found is surrounded by non-alphanumerics.
- /[NO]SUbdirectories - Causes all subdirectories of the current one to be
- searched.
- The default is /NOSUBDIRECTORIES
- /[NO]CAse_sensitive - Allows the searching to be performed respecting
- the case of the match and replacement strings.
- The default is /NOCASE_SENSITIVE
-
-
-
- 2
-
- CHANGE v1.04
-
-
- /[NO]Unique_bak - Guarantees that backup files created will be unique.
- This will prevent CHANGE from deleting a backup file that already
- exists. CHANGE automatically enables this option when wildcard
- filespecs (like TEST.*) are specified that can overwrite backup files
- that CHANGE just created.
- The default is /NOUNIQUE_BAK
- /Text_file - This option is the default, and is about 3 times
- faster than BINARY_FILE mode. Note the restrictions listed below.
- /Binary_file - This option allows files containing <EOF> characters
- or search strings that span <CR><LF> sequences to be processed.
- /TEXT_FILE and /BINARY_FILE are mutually exclusive, /BINARY_FILE takes
- precedence if both are found on the command line.
- /[NO]Floppysize=n - Defines the size in KB of the largest floppy on
- your system you want searched. By default drives a: and B: are not
- checked at all. EX: /ALL/FLOPPYSIZE=1200 would check the size of each
- drive before searching. Only those 1.2MB and up would be searched.
- /[NO]COnfirm_change - Prompts for permission to make changes to each
- FILESPEC matched that actually contains a match. This allows the user
- to selectively modify files.
- /ANy_attribute - Change all files matching the FILESPEC, regardless
- of special file attributes. /CONFIRM_CHANGE option is set by default,
- but may be overridden.
- /[NO]Log - Do [NOT] write progress messages to the console.
-
- General command line handling:
-
- Switches may be placed anywhere on the command line except within quoted
- strings. Switches may be abbreviated to the smallest unique string
- among the switches the program supports.
-
- /A is allowed, and would mean to the program /ALL and /ANYATTRIBUTE.
- /AL/AN would be a better, more specific way to say the same thing.
-
- Everything on the command line is converted to uppercase unless
- surrounded by quotes. Both double (") and single (') quotes are
- supported. If your string need to contain the DOS re-direction
- operators < > | then you MUST enclose the string in DOUBLE QUOTES! They
- will prevent DOS from using them for redirection of the standard
- input/output files.
-
- Non printable characters may be placed into the quoted strings on the
- command line or in indirect files (discussed below) using the following
- syntax: #nnn where nnn is the ASCII code for the desired character. If
- the end of line characters of a text file (CR and/or LF) are being
- modified the file MUST be converted in /BINARY_MODE.
- Ex. #007 - would be converted to the ASCII BEL character.
-
- Normally the DOS command line supports parameters up to 128 bytes.
- Under 4DOS this restriction is increased to 255 characters. CHANGE
- supports the additional characters it can get from 4DOS. In addition
- indirect parameter files can be used for changes that may be repeated.
- The total size of the resulting parameter string is still restricted to
-
- 3
-
- CHANGE v1.04
-
-
- 255 bytes at present.
-
-
- Indirect Parameter Files:
-
- To use an indirect file place an '@' at the beginning of the name of the
- indirect file on the command line. The indirect file itself may contain
- anything that is normally allowed on the command line for CHANGE.
- Switches specified in the indirect file may be overridden or added to by
- specifying the new switches on the command line following the indirect
- file's name.
-
- CHANGE TEST.PAS @varchang.lis /SUBDIR
-
- This would include the list of change strings found in the file
- VARCHANG.LIS in the current directory. The lines in the file are
- concatenated together with a space appended to the end of each line up
- to the 255 byte max length. If the resulting command line has an uneven
- number of CHANGE strings specified an error will be reported.
-
- Examples:
-
-
- 1. To rename the ever popular 'foobar' variable to something a
- little more meaningful like 'MyVar' in the program 'test.pas'
- you would use the following CHANGE command:
- CHANGE test.pas 'foobar' 'MyVar'
-
- 2. To do the same in all of your Pascal files in a given directory
- you would use:
- CHANGE *.pas 'foobar' 'MyVar'
-
- 3. To do the same in all of your Pascal files on a given drive you
- would use:
- CHANGE *.pas 'foobar' 'MyVar' /all
-
- 4. To change strings that contain special characters you need to
- represent the special characters in some fashion and 'allow'
- change to see them. Any character in the ASCII set may be
- specified in a QUOTED STRING by using a # followed by the
- character's three digit decimal ASCII code, for instance #007
- is the BEL character.
-
- To reformat a LF delimited text file into a more standard CRLF
- delimited file use the following:
- CHANGE STRANGE.C '#010' '#013#010'
-
- To change instances of a string only at the start or end of a
- line use:
- CHANGE text.fil 'EndString#013' 'NewEndString#013'
- CHANGE text.fil '#010StartString' '#010NewStartString'
-
-
- 4
-
- CHANGE v1.04
-
-
- 5. Many things may be combined, the above change plus changing
- variables called 'var1' to 'MyOtherVar' and reformatting a LF
- delimited text file to a CRLF delimited text file.
- CHANGE *.pas 'foobar' 'MyVar' 'var1' 'MyOtherVar' '#010' '#013#010' -
- '#013StartString' '#013NewStartString'
-
- 6. If you have a large or complex change like the one above it is
- often better to use an indirect file. The indirect file,
- 'BIGCHG.IND', for that change would look like this:
-
- 'foobar' 'MyVar'
- 'var1' 'MyOtherVar'
- '#010' '#013#010'
- '#010StartString' '#010NewStartString'
-
- And the invocation of CHANGE would be:
- CHANGE *.PAS @BIGCHG.IND
-
- Change History
-
- The following changes have been made to the software listed above:
-
- 1. v1.00 - initial release.
- 2. V1.01 - New features and minor bugfixes:
- o Added /BINARY_MODE.
- o Speeded up the /TEXT_MODE operation.
- o Added multiple match,replace string capability.
- o made a bugfix the error recovery.
- 3. V1.02 - New features:
- o Add /ANY_ATTRIBUTE.
- o Add /CONFIRM_CHANGE.
- o Released as Shareware.
- 4. V1.03 - New features:
- o Fixed display of files as each is completed the name is
- left on a line of it's own.
- o Now when a file is scanned, but has no matches it is NOT
- updated. Previously ALL files that were looked at were
- marked as updated.
- 5. V1.04 - New features:
- o /SUB now causes matching files in the current or specified
- directory and it's sub-directories to be processed.
- o A new /SHOW_CONTEXT switch to:
- - display the LINE that is about to be changed.
- - allow the user to confirm changes on an item by item
- basis.
- o A new /WHOLE_WORDS switch to only match when the string is
- surrounded by non-alphanumerics.
- o a new /[NO]LOG switch has been added to allow the user to
- specify that progress messages should [NOT] be written to
- the console. The default is /LOG.
-
-
-
- 5
-
- CHANGE v1.04
-
-
- o a new /[NO]UNIQUE_BAK switch has been added to allow the
- user to specify that CHANGE should not overwrite any
- existing .BAK files. Now if there is a conflict CHANGE
- attempts to use .BAL then .BAM etc...
- o bug fixes:
- o In previous versions if you attempted to CHANGE a text file
- that was not CRLF delimited without using /BINARY_MODE the
- output file would be truncated to 257 bytes. This has been
- trapped for and a warning is issued allowing you to
- allow/disallow saving the changes made.
-
- A backup file has always been made to presere the original
- file.
- o In previous versions if you made a change with a wildcard
- t
- filespec that like TEST. to process TEST.001, TEST.002,
- etc. the backup files would be created on top of one
- another. CHANGE would only leave the backup file for the
- f
- last TEST. file processed intact. Now the /UNIQUE_BAK
- option is enabled when this situation is detected.
- o In previous versions if you made a change with a wildcard
- filespec that included backup files (ex. TEST., TEST.B??)
- CHANGE would loop back around and process the backup files
- as well. This situation is now detected and informs you of
- the problem and warns you that if you decide to proceed
- CHANGE will NOT CREATE BACKUP FILES for the files changed.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 6
-
- CHANGE v1.04
-
-
- Known Problems
-
- The following problems are known to exist in this version:
-
-
- 1. When CHANGE is used on a file that had DOS file protection bits
- set, the protection bits are LOST! When CHANGE finds one of
- these files and it is told it is Ok to change it, CHANGE sets
- the file's protection to ARCHIVE only. When the original file
- is renamed to the .BAK version it is left with just the ARCHIVE
- bit set. The new version of the file is set to ARCHIVE only.
- It is left up to the User to reset the file protection
- appropriately.
-
- I don't view this as a problem, but you should be aware of it.
-
- If wish to report a problem with this software I can be reached at the
- above address, or send BixMail to JClinton detailing the nature of the
- problem encountered.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 7
-