home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / BEEHIVE / UTILITYS / FINREP23.ARC / FINREP.DOC next >
Text File  |  1990-07-21  |  14KB  |  305 lines
  1. ;;01-19-86
  2.                      FINREP.DOC  Version 2.3
  3.                             06/15/86
  4.  
  5. Eric Gans
  6. French Department, UCLA
  7. Los Angeles, CA 90024
  8.  
  9.    * MS-DOS users: FINREP now exists for DOS. MS-DOS v1.0 is *
  10.    * equivalent to CP/M v2.3.                                *
  11.  
  12. Version 2.3
  13. Fixed  bug  that  made verification  incompatible  with  multiple 
  14. (wildcard)  files.   Allow wildcard (?,  not *) at end of  search 
  15. string.
  16.  
  17. Version 2.2
  18. Added  "V"  flag  to allow user verification  ("Replace  (y/n)?") 
  19. before replacement in text files; a few minor improvements.
  20.  
  21. Version 2.1
  22. Fixed bug that treated wildcard filetypes as single files.  Added 
  23. a couple of clarifications to DOC file.
  24.  
  25. Version 2.0
  26. Allows wildcard searches (various options),  wildcard  filetypes. 
  27. Easier entry of caps (!string!  instead of !s!t!r!i!n!g).  Allows 
  28. control characters other than letters (e.g., ^[,^@).
  29.  
  30. Version 1.1
  31. Fix:  Didn't  find a string immediately following a found string.  
  32. Failed to signal bad file write.
  33. Enhancements:  Allows wildcard filenames (NOT filetypes).  Better 
  34. error  checking.    Abort  from  console  with  <ESC>.    A   few 
  35. clarifications in the DOC file.
  36.  
  37.                               *****
  38.  
  39.      FINREP is a search/replace program that remedies most of the
  40. deficiencies of Wordstar's ^QA and other similar commands.  Aside
  41. from being faster, it has important additional features:
  42.  
  43.      - allows wildcards in search string (v2.0)
  44.      - allows wildcard filename (find/replace in groups of files)
  45.      - command-line entry allows batch processing by SUBMIT, etc.
  46.      - allows entry of control or hex characters (0-FF)
  47.      - can be used with object files (e.g., COM files)
  48.      - sets  capitalization (first letter or whole word) and high
  49.        bit of the last character according to the old string
  50.  
  51. This last feature means that,  for example,  if you are writing a 
  52. scenario where the characters' names appear sometimes in CAPS and 
  53. sometimes just Capitalized, you don't need two search/replaces to 
  54. replace one name with another: JOE will be replaced by HARRY, Joe 
  55. by Harry, and even joe by harry.  
  56.  
  57.                               *****
  58.  
  59. Format: finrep [d:]fn [newfn] /[switches]/ oldstring [newstring]
  60.  
  61. (Enter "finrep" alone for a brief command summary.)
  62.  
  63. If a second filename is given, the changes will be placed in that
  64. file;  if  not,  the  old filename will hold the changes and  the
  65. original  file will be changed from fn.ft to fn.BAK  (unless  the
  66. "B" switch is used).
  67.  
  68. Wildcards  (*,?) may be used anywhere in the filename;  if  there 
  69. are  wildcards in the filetype (after the ".") the B switch  will
  70. be  set  automatically  to suppress creation  of  BAK  files.  If 
  71. wildcards are used,  a second filename cannot be entered.  If you 
  72. enter:
  73.  
  74. A>finrep urk*.doc // "blurk" "zap"
  75.  
  76. the files urk01.doc,  urk33.doc,  urktty.doc would be modified as 
  77. expected and files urk01.bak, urk33.bak etc. would be created.
  78.  
  79. The characters "//" must be entered even if no switches are used.
  80.  
  81. The switches are as follows:
  82.  
  83. B  =  no BAK file.  This switch disables making a BAK  file;  the 
  84. original  file  will be lost.  (Use only if you did not  enter  a 
  85. second filename.)
  86.  
  87. Q = allow wildcards in search string. (The program runs faster if 
  88. this  switch is not used.)  The various options for this  command 
  89. are described below.
  90.  
  91. V = verify replacement.   If this switch is used,  the context of 
  92. the search string will be displayed on the screen and you will be 
  93. queried  re replacement.   This switch cannot be used along  with 
  94. the O or H switches (see below).
  95.  
  96. O = Object file.  If this switch is used, the program will ignore 
  97. end-of-file  markers (1AH),  as in PIP's "o"  command.   Use  for 
  98. search/replace in non-text files.   WARNING: if you don't use "O" 
  99. with  a  non-text  file it will be cut off after the  first  1AH. 
  100. That's why FINREP makes BAK files!
  101.  
  102. H  =  keep High bit.  With this switch,  all bytes  are  searched 
  103. exactly  as they are;  letters with the high bit set will not  be 
  104. identified  with their standard ASCII  counterparts.  
  105.  
  106. W = no Whole-word search.  This switch is used to search a string 
  107. whether  or not it is a whole word;  with it,  a search for "the" 
  108. will find "other", "their" etc.
  109.  
  110. NB  - The  program  defines a "word"  as  anything  preceded  and 
  111. followed  by  something other than a letter  (space,  punctuation 
  112. mark,  number, control character, beginning or end of file). Thus 
  113. this  switch  is not needed if the search string is a  series  of 
  114. words,  a  word  preceded  by a control  character  that  is  not 
  115. continguous to another word, etc.
  116.  
  117. C  = respect case.  This switch allows you to distinguish capital 
  118. from lower-case letters: in a search for "the", "The" will not be 
  119. found/replaced.  (NB: Upper case letters cannot be entered within 
  120. quotes; see below.)
  121.  
  122.  
  123. In normal operation (with no switches),  the search will  include 
  124. whole words only; it will ignore case and high bits, but will set 
  125. the  new  string  to  correspond  to the  old  in  this  respect, 
  126. capitalizing the first letter or the whole string and setting the 
  127. high  bit  of the last as required.  This last  feature  is  only 
  128. useful if the replacement string is one word long; if it contains 
  129. more than one word,  you may set the high bits when you enter the 
  130. string,  or let your word-processor (e.g. Wordstar) do it. If you 
  131. include  capitals  in  your  replacement  string,  they  will  be 
  132. respected even if the find string is not capitalized.
  133.  
  134. If  you want to search for a capitalized word,  you must use  the 
  135. "C"  switch (or the "H" or "O" switch);  FINREP will give you  an 
  136. error message if you don't. 
  137.  
  138. The last four switches are in the relation O > H > C       
  139.                                                  > W  ; 
  140. the "higher" switch includes the smaller.  Thus if the "H" switch 
  141. is used,  capitals and lower case will be distinguished,  and the 
  142. search will not be limited to whole words.
  143.  
  144. *****************************************************************
  145.  
  146. String entry:
  147.  
  148. The  find  and replace strings must be separated by a space  from 
  149. the switch entry and from each other.  Strings should be  entered 
  150. as follows:
  151.  
  152. ASCII     - in quotes: "blurk", "54%**90er @"
  153.  
  154. The following characters must NOT be placed between quotes:
  155.  
  156. HEX       - separate by commas: d,1A,cd,10,ff,3 
  157. CAPITALS  - between !!: !A!,!hello!          [NEW IN V2.0] 
  158. CONTROL CHARACTERS - preceded by ^: ^M,^m^j,^c,^C,^[,^^
  159. WILDCARDS - ????, ?n (1 <= n <= 9) or ?* (indeterminate)
  160.      The  "|" character is used to display a break in the replace 
  161. string (see below).
  162.  
  163. All ascii letters entered within quotes will be treated as  LOWER 
  164. CASE.  If  you  want  to search upper case letters with  the  "C" 
  165. switch,  or to put upper case letters in the replace string,  you 
  166. must  surround  them  with "!!",  unless you enter  them  as  hex 
  167. characters:  (A = 41, B = 42 ...). Sorry about this, but the CP/M 
  168. command line cannot distinguish upper from lower case.
  169.  
  170. Any  combination  of characters is  valid;  for  clarity,  groups 
  171. should  be separated by commas,  although this is only  necessary 
  172. for individual hex characters: !h!"ello",^m^j,e5,?7,32,!blurk!,^q 
  173. Quotes and !..!  must be closed.  To search/replace the quotation 
  174. mark,  enter it as a hex character ("=22h).   You can search  for 
  175. "!" if you keep it between quotes.
  176.  
  177. The  length  of the find/replace strings is limited to 30  bytes; 
  178. this  length  applies to the strings themselves and  not  to  the 
  179. keyboard entry,  which cannot exceed 127 bytes in all (blame CP/M 
  180. for  this).  Thus  ^j,cd,ff,3d is 4 bytes long.   In the case  of 
  181. indeterminate  wildcards,  up to 255 bytes are allowed,  but  the 
  182. limit of 30 still stands for the find/replace strings themselves.
  183.  
  184. If  you do not enter a replace string,  the  searched-for  string 
  185. will be replaced by nothing, i.e., deleted.
  186.  
  187. WILDCARDS (V2.0)
  188. The wildcard search has a great deal of flexibility.  For obvious 
  189. reasons,  wildcards  cannot appear at the beginning of the search 
  190. string.  (In versions below 2.3 they can't be at the end  either.  
  191. For  some  not-so-obvious reason this seemed a bad thing  at  the 
  192. time.)  The options are as follows:
  193.  
  194. 1. Simple wildcard search: all bytes of the search string will be 
  195. replaced.
  196.  
  197. finrep  zz.txt  /q/ "d"?2"e" "xxyz" will replace all  words  like 
  198. "done", "dare", "dove" etc. by "xxyz"  A maximum of four wildcard 
  199. groups are allowed in this form: thus "a"?"cd"?4"ijk"??"nopq"?"s" 
  200. is a permissible search string
  201.  
  202. 2.  Simple wildcard search with break. Only one wildcard group is 
  203. allowed;  the  replace string is divided in two,  with the  first 
  204. part  replacing  what precedes the wildcards and the second  what 
  205. follows;  the  intermediate bytes are left alone.   The break CAN 
  206. appear at the beginning or end of the replace string to  indicate 
  207. that  the corresponding part of the find string is to be deleted.  
  208. A blank replace string (entered simply as: | ) will delete both.
  209.  
  210. finrep  xx.txt /qw/ "d"?2"e" "xx"|"yzz" will replace the  "d"  in 
  211. this  pattern  with "xx" and the "e" with "yzz";  "done"  becomes 
  212. "xxonyyz", "madame" -> "maxxamyxx", etc.  (This last example only 
  213. works if the "W" switch is used.)
  214.  
  215. 3.  Indeterminate  wildcard  search/replace.   The  indeterminate 
  216. wildcard "?*" must be the only wildcard in the search string.  In 
  217. this  option  the  whole  string from the  beginning  to  end  is 
  218. replaced.   A  maximum of 255 characters will be allowed  in  the 
  219. search string; longer strings will not be found.
  220.  
  221. finrep  blurk.let  /qw/  "xy"?*"zq" "garbage"  will  replace  all 
  222. strings   beginning  and  ending  with  the  indicated   letters: 
  223. "xyrwerwerzq",  "xyuu  is  the nbrzq",  "xy ^C^Yzq" will  all  be 
  224. replaced by "garbage"
  225.  
  226. 4.  Indeterminate  wildcard with break.  This is a very  powerful 
  227. option  that allows you,  for example,  to replace  PerfectWriter 
  228. "fences" with WordStar control toggles (& vice versa). Here again 
  229. only  one  wildcard group is allowed in the  search  string;  the 
  230. intermediate bytes are left unchanged.
  231.  
  232. finrep   zap.kkk   /qw/   "123"?*"45"  "6"|"789"   will   replace 
  233. "zz123blurk blurk xxxc oo45rr" by "zz6blurk blurk xxxc oo789rr";
  234. finrep  perf.wri /qwc/ "@"!ux!"{"?*"}" ^s|^s will replace the  PW 
  235. underline fence @UX{ ...  } by WS's ^S ...  ^S  Note that the "C" 
  236. flag is used here to search for caps; if l.c. as well as caps are 
  237. acceptable,  it  could be omitted and the search  string  written 
  238. "@ux{"?*"}".   You  can delete the fences altogether by replacing 
  239. the ^s|^s by | in the last example.
  240.  
  241. One  user thought the word "break" was misleading and  should  be 
  242. replaced  by  "save," since the "|" in the replace  string  means 
  243. that  you  preserve the wildcard part of the  search  string.  In 
  244. other words:  finrep zap.txt /qw/ "<<"?*">>" will kill everything 
  245. between  the "<<..>>" whereas:  finrep zap.txt /qw/ "<<"?*">>"  | 
  246. will just kill the "<<>>" and "save" their contents.  
  247.  
  248. FINREP  can be aborted at any time by typing <ESC> (=1B  HEX).  I 
  249. preferred this to ^C since an extra ^C will be read by CP/M as  a 
  250. Warm Boot.
  251.  
  252. Except when the "V" switch is used, the only screen output is the 
  253. number of strings replaced and, if you use wildcards, the names & 
  254. total  number  of  files  processed.  If  you  want  to  see  the 
  255. replacement procedure in action, use a word-processor!
  256.  
  257. Notes:
  258.  
  259. 1.  FINREP  will modify files of any length;  it uses the  entire 
  260. memory  below the CCP as its buffer,  and writes to disk whenever 
  261. the  buffer  fills up.  Since it doesn't overwrite  the  CCP,  it 
  262. doesn't have to end with a Warm Boot.
  263.  
  264. 2.  There  is no intrinsic limit on the number of  files  allowed 
  265. under the wildcard filename option;  for sanity's sake,  you will 
  266. get an error message if there are more than 255.
  267.  
  268. 3.  If  you want to create a version of FINREP with some  of  the 
  269. switches preset,  run the program without a filename:      finrep 
  270. /[sw1][sw2]../  After  it  returns to the CP/M  prompt,  save  13
  271. finrep1.com  will  keep  the switches  as  you  like  them.  This 
  272. procedure  is  NOT  REVERSIBLE,  so  keep  your  original  FINREP 
  273. unchanged.
  274.  
  275. 4.  In deciding whether to capitalize a whole word/string, FINREP 
  276. looks  at the first two letters.  If the find string has only one 
  277. letter,  only the first letter of the replacement string will  be 
  278. capitalized.   If   the   word  to  be   replaced   has   unusual 
  279. captalization (e.g.  BBrrOOOmm),  use the "C" switch and/or enter 
  280. separate replacement strings for different variants.
  281.  
  282. 5.   In using indeterminate wildcards, you should usually use the 
  283. "W"  switch,  since  without it BOTH HALVES of the search  string 
  284. must  begin and end on word boundaries.   This is only likely  if 
  285. you are replacing whole words.
  286.  
  287. 6.  Re  speed,  FINREP  is  somewhat faster than  Wordstar's  ^QA 
  288. command.  But  if all you want to do is replace a string,  it  is 
  289. over  three  times faster,  since its time includes  loading  and 
  290. saving the file.  Measured on a long (84 K) file,  FINREP took 27 
  291. seconds and WS 34 for a typical search/replace.  But WS needs  at 
  292. least  10 seconds to load and a good minute to save the file  and 
  293. exit.  With a little practice, the command line can be entered as 
  294. fast  as  WS's,  and  it  can  be included  in  SUBMIT  files  or 
  295. reproduced by programs like SYNONYM or my SYN.COM.
  296.  
  297.                               *****
  298.  
  299. FINREP  was  written  at the request of  John-Mark  Stensvaag  of 
  300. Vanderbilt University.   At first I couldn't see the use for  it, 
  301. but  he  convinced me (he is a professor of  Law).  The  wildcard 
  302. features  added  in  v1.1  and  v2.0  were  also  his  idea;  the 
  303. verification  feature  in  v2.2 was ssuggested  by  J.  Olsen  of 
  304. Chicago.  I would appreciate hearing from you about (a) bugs  and 
  305. (b) suggestions for further enhancements.