Documentation for Program: FILTER.EXE

DESCRIPTION:

This program will accept a byte pattern to look for, a second byte pattern
to replace the first one with, and a series of file names upon which to
perform the search and replace operations. Invoking the program with no
parameters, or with an invalid parameter, will give a screen showing the
proper calling syntax and the error.

The program is NOT user interactive, all its parameters are passed to it
in the command line tail. The program may be invoked from .bat files and
it returns the following values in ERRORLEVEL for use in IF tests after
return (command-line syntax is described under USE):

ERRORLEVEL = 0 -> no error, normal program termination
ERRORLEVEL = 1 -> program halted by user with ^X
ERRORLEVEL = 2 -> improper command-line syntax
ERRORLEVEL = 3 -> invalid/missing input pattern
ERRORLEVEL = 4 -> invalid/missing output pattern
ERRORLEVEL = 5 -> input file open/read/close error(s)
ERRORLEVEL = 6 -> output file creation/write/close error(s)
ERRORLEVEL = 7 -> both input and output file error(s)

The screen output of the program IS redirectable with the DOS redirection
operators, i.e., > and >>. Thus, if you want no visible output you can
redirect it to nul, e.g., filter (parameters) > nul will do its work
with no screen output and you could then check the ERRORLEVEL returned
by the program to generate your own error messages. The screen output
could also be redirected to a file, e.g., filter (parameters) test > tmp,
or to a device, e.g., filter (parameters) test > PRN:

Example .bat file

echo off
filter (parameters) %1 > nul
if not errorlevel 7 goto :6
echo Input and output file error(s)
goto :quit
:6
if not errorlevel 6 goto :5
echo Output file error(s)
goto :quit
:5
if not errorlevel 5 goto :4
echo Input file error(s)
goto :quit
:4
if not errorlevel 4 goto :3
echo Bad output pattern
goto :quit
:3
if not errorlevel 3 goto :2
echo Bad input pattern
goto :quit
:2
if not errorlevel 2 goto :1
echo Bad syntax
goto :quit
:1
if not errorlevel 1 goto :0
echo Program aborted by user
goto :quit
:0
echo No error
:quit


The program employs the Boyer-Moore pattern matching algorithm. For more
details on this and other useful algorithms see: "Algorithms",
R. Sedgewick, 1984, Addison-Wesley Publishing Company, Inc., Reading, MA.
See also: "Algorithms & Data Structures", N. Wirth, 1986, Prentice-Hall,
Inc., Englewood Cliffs, NJ. I highly recommend both of these texts, and
the Wirth text in particular for all you Modula-2 programmers.

USE:

Proper calling syntax is:

filter

[ ...]

Where: is a series of bytes to be replaced with pattern>. Each pattern may be specified either as a series of characters
enclosed by ~~, or as a series of hexadecimal byte values separated by
commas, e.g., ~aBc~ and 0D,0A are each valid patterns. The two patterns
need not be the same length, and

may be ~~ in order to
delete from the file. Max pattern size is 120 bytes.

is the name, optionally including a path, of an EXISTING file
to be filtered. Output is to file with same , but with the
extension .FLT. Multiple may be included on the command line
and each will be filtered in turn.

The only limit on the number of files to be filtered is the fact that
DOS will only accept a command-line of up to 127 characters. Thus, any
pattern specifications plus the files to be filtered cannot be longer
than 127 characters. There is no limit on the size of the files to be
filtered or on the type of file, i.e., this program will filter text or
binary files with equal ease.

NOTE: This program automatically avoids filename collisions and will NOT
overwrite an existing file. The filename collision avoidance routine
works as in the following example:

Assuming that the following statements are executed in order with
no intervening statements, we have -

filter ~something~ ~something else~ test -> output test.flt
filter ~something~ ~something else~ test -> output test$$$$.flt
filter ~something~ ~something else~ test -> output test$$$a.flt
filter ~something~ ~something else~ test -> output test$$$b.flt
filter ~something~ ~something else~ test -> output test$$$c.flt

Continuing repetition would eventually lead to -> output test$zzz.flt,
which would be the last name produced by the collision avoidance routine.
This method will generate a maximum of 17,577 different filenames and
so should be sufficient for most of us. Note well that the names are
generated such that each successive output file will follow in
alphabetical order. Thus, if you do several filterings of a file, you
can always tell in what order the output was produced.

Examples:

filter 0D,0A 0A test - This will find each carriage return/linefeed
sequence (0D,0A - this is the DOS standard end-of-line sequence) and
replace it with just a linefeed (0A - this is the Unix/Xenix standard
newline character).

filter ~a~ ~A~ test - This will replace each 'a' in test with 'A'.

filter 09 ~ ~ test - This will replace each tab character
(a non-printable control character) in test with five spaces.

filter ~Randall A. Maddox~ ~~ filter.doc - This will delete my
name from this file.

AUTHOR:

Randall A. Maddox
12209 M Peach Crest Drive
Germantown, MD 20874
(301) 428-9581

DEVELOPMENT SYSTEM:

LOGITECH MODULA-2, MS/PCDOS, Version 3.0, August 1987. I cannot
recommend either Modula-2 or the Logitech compiler highly enough. If you
are still programming in some other language, give it up. The future
is here now.

UPDATE HISTORY:

Originally written: 11/28/87 by Randy Maddox
Released version 1.0: 12/9/87 by Randy Maddox

REQUIREMENTS/SPECIFICATIONS:

This program should run on any PC/MSDOS computer with version 2.0 or
better. It needs about 110K of free memory to work in. The filtering
process uses two 30K buffers, one for input and one for output, and so
should be relatively independent of disk speeds. Filtering times can
be estimated on the basis of processing about 4 or 5K of input per
second on the hard disk of an 8MHz AT compatible. The program cannot be
interrupted with ^C or ^Break, but will accept its own break character of
^X at any point. This was done to ensure that files get cleaned up
properly if the program is aborted.

DISCLAIMER AND NOTES:

I have tested this program to my satisfaction and use it myself, however,
there is no guarantee stated or implied. The program is released freely
for your free use and distribution. If you make any significant changes
to the source code, I would appreciate a copy mailed to the address
above. If you turn up any bugs, please let me know and I will try to
fix them. Again, no promises. Please feel free to use any portion
of the source code in your own programs. My only request is that you
not remove my name from the source for this program or from the
program sign-on. This program may be found on the Generation 5 BBS at
(202) 495-8983, 495-8984, 495-2932.