GF - A Generalized Filter, v1.3
 
                              Dave Ramsey

   GF 1.3 is hereby placed in the public domain, May 8, 1989. (Version 
1.1 was an interim version which never got out the door. I didn't want 
to release it without getting the DU: support working right...)

   The intent of GF is quite simple - to allow the user to replace any 
character in a specified input file with any other character on a global 
basis. The reason that I wrote GF was because I frequently get text 
files that were probably prepared on Un*x systems and which have only 
bare linefeeds as line terminators. To read these files, I needed a 
quick tool to change all LFs to CRs; GF fills that bill.

   In order to use GF, the user must specify four arguments. These are 
the input file, the output file, the search character and the 
replacement character. GF allows the user to specify control characters 
for either the search character or the replacement character by 
preceding them with a '^'. Likewise, since ZCPR and CPM convert the 
command line to all uppercase, GF allows the user to specify a lowercase 
character by preceding that argument with a `~` character. For instance:

  A0>GF INFILE.TXT OUTFILE.TXT ^J ^M

will convert all the linefeeds in INFILE.TXT to carriage returns in the 
file OUTFILE.TXT. (I've used it often in this mode to clean up documents 
prepared on Un*x systems since Un*x uses only a bare linefeed as a line 
terminator.)

   Likewise, the command:

  A0>GF INFILE.TXT OUTFILE.TXT Z ~z

will convert all uppercase Z's to lower case z's.

   In version 1.1, I added another option - specifying the search and/or 
replacement characters with a hexadecimal escape sequence. For example,

  A0>GF INFILE.TXT OUTFILE.TXT \7F \0D

will convert all ASCII delete characters to carriage returns. 
Additionally, I added some more smarts to GF so that it only recognizes 
control characters specified with a '^' if they are from 01h to 1Ah, 
i.e. ^A through ^Z. Other control characters should now be specified 
with the hex escape sequences.

   Something which I failed to mention previously was that in order to 
use any of the GF "trigger" characters, you simply repeat them twice on 
the command line. For example, use \\ or ~~ or ^^ to get one of those 
specific ASCII characters as a search character or a replacement 
character. 

   Finally, I made the darn thing work with separate user areas. (I had 
realized that CP/M's BDOS had trouble with user areas but this is 
ridiculous! - Thanks, Howard!)

   If invoked with no arguments or the wrong number of arguments, GF 
will present a help screen to the user. This help screen is presented 
below:


GF, Version 1.3 - A Generalized Filter.
Syntax:
        GF du:fn1 du:fn2 oldch newch
   Where:
       du:fn1     is the input file spec;
       du:fn2     is the output file spec;
       oldchar    is the search character; and
       newchar    is the replacement character.,
   A ^ character before either oldchar or newchar
   tells GF to convert it to a control character.
   A ~ character before either oldchar or newchar
   tells GF to convert it to lowercase.
   A \ signals a hexadecimal string.
   i.e. \0D or ^M is a carriage return and ~M is an "m"
   To use a trigger char, simply type it twice - 
   i.e. \\ or ^^ or ~~ will do the trick.



NOTES: (1) While I've written a number of Turbo Pascal and Turbo 
Modula-2 programs for my Z80 Ampro system, I've not had the time to 
involve myself deeply in Z80 assembly language programs. Job, personal 
affairs, and many hours of overtime using Fortran on IBM and Unisys 
mainframes generally dampened my enthusiasm for developing Z80 and 
Z-System software. This is my first stand-alone Z80 application and 
except for the changes I made to my Sanyo MBC-1000 BIOS three years ago, 
is probably the largest Z80 project I've undertaken to date. So if my 
coding style isnt the best, or if I've made some obviously foolish 
errors, please be gentle with the criticisms! I want to hear about them 
but don't need a reprimand.
   (2) I'm interested in using the Z-System SYSLIB routines as much as 
possible. If I could have used them better or if there are routines to 
do things that I have done, let me know.
   (3) If there are additional things you would like in GF (I can't 
imagine what else anyone would want in a simple, generalized file 
filter) leave me a message on Z-Node #3 (Newton Center), Z-Node #2 
(Ladera), or Z-Node #24 (Cedar Mill) *OR* go ahead and add it yourself. 
After all, GF is in the public domain!


   Special thanks to Cameron Cotrill for encouraging me and to Howard 
Goldstein for pointing out all the "dumb" things I'd done in version 
1.0. After a short phone session with Howard, I learned three things I 
shouldn't have done at all and ways to do another half dozen better!