Replacetextblock
A Kermit script to replace blocks of text within files
[download] ← This
link fixed 28 April 2022
Author: Frank da Cruz
Script version: 1.01
Dated: 2014-02-28
|
|
Platform: Any version of
Unix where C-Kermit is available.
Requires:
C-Kermit 9.0
or later
This page last updated:
Thu Apr 28 20:18:13 2022
|
Replacetextblock is a program written in the Kermit script language that answers the frequently
asked question, “How do I replace a block of text in a group of files
with a different block of text without having to manually edit each
file?”. A Google search doesn't turn up any good answers,
so here is a Kermit script that probably does just what you want.
Installation
First, visit the
getkermitscript
page to download and install the new Kermit script installer, an April 2022
"upgrade" in response the erasure of FTP service from the Internet. Then
use the new getkermitscript 2.0 to download and install Replacetextblock:
cd (to desired directory that is in your PATH)
getkermitscript replacetextblock
Using Replacetextblock
The script is called
Replacetextblock because it replaces a
block of text, not just one line. A text block is defined as a
contiguous series of zero or more complete lines (not pieces of lines).
C-Kermit 9.0.304 already has a CHANGE command that can be used to replace
text within a line or whole text lines in a group of files,
but the CHANGE command does not operate on a blocks of text, such as:
- Copyright notices, such as you might find in source-code modules.
- Addresses or other contact information, e.g. in Web pages.
- Standard headers or footers for web pages.
- Standard disclaimers.
When you have large numbers of files that contain identical blocks of text
like this, and then you need to change them for some reason, you have the
perfect application for Replacetextblock.
In fact, Replacetextblock is even a bit more flexible that that.
Suppose, for example, you have software source code broken up into 200
modules. Each module contains a copyright notice, but the year might be
different:
/*
* Copyright (c) 1986, 1990, XYZ Corporation. All rights reserved.
* See the COPYING file for copyright and license information.
*/
Other source files might say "
Copyright (c) 1986, 2007", or other
years. Suppose that for some reason (for example, the copyright was sold to
another company) you want to change the text of all these notices, and
also to update the copyright year. You can create an "oldtext" file
containing a lines that contain patterns that match these notices:
\* Copyright (c) 1986, {19,20}[0-9][0-9], XYZ Corporation. All rights reserved.
\* See the COPYING file for copyright and license information.
“{19,20}[0-9][0-9]” is a pattern that matches
all four-digit numbers starting with 19 or 20, i.e. all years in the 20th
and 21st Centuries. Backslash (\) has been placed in front of the
asterisks because '*' is a pattern-matching character but in this case we
want to take it literally. You can read about Kermit's pattern matching HERE.
Replacetextblock uses the oldtext file to search through the files
you've specified. Then a second file, the newtext file, which
contains the new replacement text is substituted into each file in place of
the lines that match the first file. The newtext file might look like this:
* Copyright (c) 1986, 2014, ABC Corporation. All rights reserved.
* This package has new licensing terms.
* See the LICENSE file for copyright and license information.
Then to update all the files (let's suppose they are C-language source
files), you would do something like this:
replacetextblock oldtext newtext *.[ch] makefile
If you want to remove the oldtext without replacing it with anything,
you can give the name of an empty file or simply use Unix's built-in
empty file, /dev/null for newtext:
replacetextblock oldtext /dev/null *.html
Normally, as the script runs, it prints the name of each file it is
processing, and whether it it found and replaced the desired text:
[~/mm] replacetextblock oldtext newtext [ab]*.[ch]
action.c...OK (text was replaced)
alias.c...OK (text was replaced)
args.h...(replacement text not found - no change was made)
argsort.c...OK (text was replaced)
babyl.h...OK (text was replaced)
If the text was not found in a particular file, that file is not touched.
If a file was changed, the script makes a backup of the original file having
the same name but with
.backup appended to it (you can defeat this
behavior with a command-line option, next section). The updated file has
the same permissions as the original, but its modification time is updated.
The size and number of the lines in the oldtext and newtext files don't have
to be the same; you can (for example) replace a short text with a long one
or vice versa.
The Replacetextblock command line
Replacetextblock is controlled by its command-line arguments. The
format is:
replacetextblock [ option [ option [ ... ] ] ] oldtext newtext
file [ file [ ... ] ] ]
That is, zero or more optional parameters followed by:
- The name of the file that contains the old text to look for;
- The name of the file that contains the the new text to replace it with;
- The name(s) of one or more files where the text should be replaced.
The third parameter (and any that follow it) can be regular filenames, or
“wildcards” such as
*.c, meaning “all files whose
names end in “
.c” If the wildcard matches names of
files that are not text files, Replacetextblock automatically skips them.
Be very careful not to omit the oldtext or newtext arguments. If you
start the script with something like "replacetext *.txt" it will treate the
first file that matches the wildcard as the oldtext file and the second as
the newtext file, which is probably not what you intended. There's no way
the script could prevent this. (Well, I suppose it would be possible to
have -oldtext:xxx and -newtext:yyy options
but let's leave that for version 2).
Options start with a hyphen ('-'). The options are:
- -help
- Tells the script to print a help ("usage") message.
- -quiet
- This tells the script to run without printing any progress messages.
If there are any serious errors, however, appropriate messages will still
show up.
- -debug
- This says to print additional progress messages that are not normally
seen, which might be helpful.
- -changeall
- Normally Replacetextblock replaces only the first occurrence of the
"oldtext" in each file. This option tells it to replace all
occurrences.
- -nobackup
- Tells Replacetextblock not to make backups of the files that were
changed.
- -nopatterns
- This tells the script to treat the "oldtext" as literal text and compare
it literally with the contents of each file, rather than doing any pattern
matching as described above. This is appropriate when the target files
don't have any variations in the searched-for text, and it means you don't
have to apply any quoting in the "oldtext" file.
- -except:xxx
- This tells the script not to process the file named xxx
or, if xxx is a wildcard, not to process any file whose name matches
it. If xxx is a wildcard, its wildcard characters must be quoted
to suppress expansion by the Unix shell where you are giving the command.
Example:
replacetextblock -except:\*-old.\* oldtext newtext *.[ch]
Filenames should not start with hyphen; otherwise the script will think they
are options. If you need to process a group of files where one or more of
the names might start with a hyphen, use this notation:
replacetextblock -except:\*-old.\* oldtext newtext ./*.[ch]
that is, prefix the filename or wildcard with “
./”.
Suggested use
The Replacetextblock script is conservative, in that it doesn't destroy
anything unless you go out of your way to tell it to. Suppose you have a
directory full of important files you need to change. Obviously, you should
back them up first. But even if you don't, if you follow these steps, you
should be able to avoid disaster:
- Do your first Replacetextblock run with -debug. This shows you
what the results would be, but does not actually update the files. Instead,
for every file that would be updated, xxx, it creates an
xxx.new file that you can look at to make sure it's what you
wanted. Then you can delete the *.new files.
- Do your next run without -debug. The files are replaced, but
for each file xxx that was changed, the original is copied to xxx.backup.
If the files are source code, you should try compiling them; if they are
web-page sources, try looking at them in a Web browser (etc).
- Once you are certain that the changes were correct, you can move the
.backup files somewhere else or just delete them.
