home *** CD-ROM | disk | FTP | other *** search
/ Oakland CPM Archive / oakcpm.iso / sigm / vol242 / sandr.doc < prev    next >
Encoding:
Text File  |  1986-02-13  |  7.1 KB  |  200 lines

  1. SANDR.DOC
  2.  
  3.  
  4.                     'Search AND Replace'
  5.  
  6.  
  7.         (C) Copyright 1983 Garry Womack
  8.         All Rights Reserved
  9.  
  10.             DISCLAIMER
  11. Soft Circuits, Inc. and the author make no claims or warranties, 
  12. either express or implied, with respect to the contents or accuracy 
  13. of this manual or with respect to the described software, their quality, 
  14. performance, merchantibility or fitness for any particular purpose.  This
  15. manual and the described software are sold 'AS IS' and the entire risk
  16. as to their quality and performance rests with the buyer.  The user must
  17. assume the entire risk of using the program.  Any liability of seller or
  18. manufacturer will be limited exclusively to product replacement or refund
  19. of the purchase price.
  20. The right is reserved to make any changes to this manual without
  21. obligation to notify any person of such changes.
  22.  
  23.  
  24.  
  25.             DESCRIPTION
  26. This is a utility which will search for any string up to 255 bytes
  27. long (binary and/or ascii), part of which may contain wildcard characters
  28. and substitute a specified string up to 255 bytes long (binary and/or ascii),
  29. part of which may contain wildcard copy indicators.
  30.  
  31. The original file is renamed to filename.BAK and the new file is renamed to
  32. the input file name.
  33. The source and destination disk may be specified.
  34.  
  35. The command line:
  36. SANDR [d1:]FN.FT [d2:]
  37.     \    \      \--optional destination drive spec (default drive used
  38.      \    \        if not specified)
  39.       \    \--source filename.filetype
  40.        \-optional source drive spec (default drive used if not specified)
  41.  
  42. A temporary file named FN.$$$ is used for the output file until processing
  43. is finished.  At that time the source file is renamed to FN.BAK and FN.$$$
  44. is renamed to FN.FT
  45.  
  46. The number of matches/substitutions is printed to console after processing.
  47.  
  48. note: CR is abbreviation for carriage return in following descriptions
  49.  
  50. 3 prompts then follow:
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58. PROMPT1:
  59. IS SOURCE FILE BINARY OR ASCII ? (B/A) ->
  60. enter either B or A  (this information is used to process the end of file
  61. minimizing the destination file length)
  62.  
  63. PROMPT2:
  64. SEARCH=
  65. special characters for search prompt are
  66.     :    ascii indicator, only has significance when in binary input
  67.         mode or used as 1st character after SEARCH prompt
  68.         (at all other times it is interpreted as an ascii colon) 
  69.         -causes input mode to toggle to ascii (all following char-
  70.          characters will be interpreted as ascii)
  71.     /    -causes input mode to toggle to binary (described under
  72.          prompt3)
  73.     *    wildcard -will match any byte in search
  74.         cannot be the 1st character specified
  75.     CR    ends input string, a linefeed will also end input
  76.         a control C if typed as 1st character after prompt will
  77.         cause a CP/M warmboot
  78.  
  79. PROMPT3:
  80. SUB===>
  81. special characters for substitution string prompt are
  82.     :    same definition as for prompt2
  83.     /    -causes input mode to toggle to binary
  84.         all following input is assumed to be in 2 digit hex format
  85.     0-9    hex digit
  86.     A-F    hex digit
  87.     ,    optional byte separator (to aid user to keep byte specifiers
  88.         legibly separated)
  89.     *    wildcard copy indicator -see below
  90.     CR    same definition as for prompt2
  91.  
  92. normal CP/M command line editing functions are used when entering an input
  93. line (if the 1st character typed is control C then warm boot is done)
  94.  
  95.  
  96.  
  97. how search and replace works:
  98. relative byte              1 1 1 1 1 1 1 1 1 1
  99. position index->1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 etc
  100. WINDOW--------->~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ each element==window(I)
  101. SEARCH STRING-->~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ each element==search(I)
  102. SUB STRING----->~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ each element==sub(I)
  103.  
  104. the window length is the greater of the search string length or substitution
  105. string length (up to 255)
  106.  
  107. note - window(1) is always defined as the 1st byte in window after the
  108. window is repositioned
  109.  
  110. step#0: the window is slid to the beginning of the source file
  111. step#1: I is set to 1,then search(I) is compared to window(I),
  112. if match is not found--step#1A: window(1) is written to output file and the
  113. window is shifted to the right by 1, then step#1 is repeated
  114. if match is found--step#1B:  I=I+1, search(I) is compared to window(I)
  115.     if at anytime a match doesn't occur, then step#1A is next
  116.     if search(I) was specified with the wildcard character '*' then
  117. step#1B is next
  118.     if all bytes in the search string match (up to the length of the
  119.     search string) all the bytes in the window then:
  120. step#2: I=1, subcnt is set to the length (in bytes) of substitution string
  121. step#2A:if subcnt=0 then step #3 is next
  122.     if sub(I) was not specified as the wildcard '*' then sub(I) is
  123.     written to the output file, I=I+1, subcnt=subcnt-1, then step#2A
  124.     if sub(I) was specified as the wildcard '*' then window(I) is
  125.     written to the output file, I=I+1, subcnt=subcnt-1, then step#2A
  126. step#3: the window is shifted right for the # of bytes in search string
  127.     then step#1
  128.  
  129. EXAMPLES:
  130. SEARCH=:brown dog
  131.     \    \-string to find
  132.      \-ascii mode (the following characters interpreted as ascii)
  133. SUB===>:black dog/0D,0A
  134.         \  \      \\ \ \-hex for linefeed
  135.          \  \      \\ \-comma (makes reading for user easier) optional
  136.           \  \      \\-hex for carriage return
  137.            \  \      \-binary mode indicator
  138.             \  \-ascii string
  139.              \-ascii indicator
  140. every occurrance of 'brown dog' is replaced with 'black dog' and a CR LF
  141.  
  142. SEARCH=:b**** dog
  143. SUB===>:black********
  144. if     'beige dog is ' is in the source file then when
  145.        'beige dog' is found it would be replaced with
  146.        'black dog is '
  147. if     'brown dog can' is in the source file then when
  148.        'brown dog' is found it would be replaced with
  149.        'black dog can'
  150.  
  151.  
  152.  
  153.  SEARCH=/0d0a******09
  154.  SUB===>/0D0A******::/09  (note that the 1st ':' toggles to ascii mode
  155.             so I wouldn't have to look up hex code for ':')
  156. if    CRLF'label3'TAB is in the source file it would be replaced with
  157.     CRLF'label3:'TAB   (TAB is the tab byte 09hex)
  158. this is an example of how a colon could be inserted after labels in a
  159. source file for an assembler, by specifying the search to start with
  160. CRLF, this forces the match to occur only at the beginning of a line
  161.  
  162.  SEARCH=:          (6 ascii spaces)
  163.  SUB===>/09
  164. this replaces all occurances of 6 contigious spaces with a tab (decreases
  165. file length)
  166.  
  167.  SEARCH=/09
  168.  SUB===>:       (6 ascii spaces)
  169. expands all tabs in file to 6 ascii spaces
  170.  
  171.  SEARCH=/0C
  172.  SUB===>        (null or empty string)
  173. removes all form feeds from file
  174.  
  175. NOTE:    a literal '*' must be specified in binary mode (hex) in SEARCH or SUB
  176.     a literal ':' must be specified in either binary or after an
  177. earlier':'
  178.     a literal '/' must be specified in binary mode in hex
  179.  
  180.  
  181.  SEARCH=/cd,05,00
  182.  SUB===>:CALL BDOS
  183. could search a '.COM' file for all occurances of a call to BDOS with an
  184. ascii statement 'CALL BDOS', the file could then be examined by DUMPA.COM
  185. or DDT dump to find out if and where bdos calls were in a program
  186.  
  187.  SEARCH=/1B**
  188.  SUB===>:^^^  ( 3 up arrows)
  189. could detect if any 3 byte escape sequences existed in an ascii source file
  190. (they will now appear as ^^^ in ascii file)
  191.  
  192. If it is desired to just find out the number of occurances of a byte/string
  193. in a file, just enter search string, and '*' in the substitution string for
  194. each byte in the search string- the file will not be altered but the count
  195. of the occurances will be shown.
  196.  
  197.  
  198. end.
  199.  
  200.