home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxmulch2.zip / rxmulch.txt < prev    next >
Text File  |  1996-11-25  |  10KB  |  271 lines
  1. About RxMulch
  2. =============
  3.  
  4. RxMulch is a simple REXX-program which allows for counting the occurrences of a
  5. string in a file and for replacing strings in a file.
  6.  
  7. You may tell RxMulch the strings on the command-line or use a simple ASCII-file
  8. which may contain several search- and replacement-strings (each being on its
  9. own line).
  10.  
  11. It is also possible to use RxMulch as a function for other REXX-programs.
  12.  
  13. Possible usages:
  14.  
  15.   - replacing (multiple) strings in a file,
  16.   - replacing strings in a file (e.g. e-mail-address that changed),
  17.   - removing/adding blank-lines from/to files, etc.
  18.   - replacing control-characters with their hexadecimal- or decimal-values
  19.     shown as a clear string and vice-versa (nice to analyze binary values in
  20.     control-files),
  21.   - patching a string in a file without DEBUG,
  22.  
  23. You can undo changes by merely preceding the switch or the controlfile with a
  24. minus (-).
  25.  
  26. RxMulch always shows you the number of occurrences resp. changes which took
  27. place.
  28.  
  29. Hint: information for the user is being displayed on STDERR:, therefore messages
  30.       do not interfere with pipes if you are using STDIN and STDOUT as source
  31.       and target.
  32.  
  33. You can use control-files to define the search and replace strings, see
  34. sample-files:
  35.  
  36.               ASC2UNIX.CTL (change CRLF to LF)
  37.  
  38.               COMMCHAR.CTL (show control-characters with their communication
  39.                             names; leave CRLF unchanged to make the file
  40.                             editable)
  41.  
  42.               CRLF.CTL     (remove empty lines once, i.e. CRLFCRLF -> CRLF)
  43.  
  44.               CTL_CHAR.CTL (show control-characters with their control-sequences
  45.                             names; leave CRLF unchanged to make the file
  46.                             editable)
  47.  
  48.               DEC_CHAR.CTL (show control-characters with their decimal values;
  49.                             leave CRLF unchanged to make the file editable)
  50.  
  51.               HEX_CHAR.CTL (show control-characters with their hexadecimal
  52.                             values; leave CRLF unchanged to make the file
  53.                             editable)
  54.  
  55.               HTML.CTL (example for exchanging HTML/SGML-entities: German
  56.                         umlauts with codepage 850)
  57.  
  58.               VENTURA.CTL   (make Ventura CHP-files editable; they contain
  59.                              absolute path-names; don't forget the STY-file)
  60.  
  61.  
  62. rxMulch.cmd: program to find/replace characters (strings) in file; allows
  63.              definition of hexadecimal or decimal value of single
  64.              characters
  65.  
  66. usage:
  67.  
  68.  rxMulch [infile] [outfile] {[-]controlfile | /[-]switch}
  69.    infile:      if missing from STDIN:
  70.  
  71.    outfile:     if missing, RxMulch will replace infile;
  72.                 if no infile than output to STDOUT:
  73.  
  74.    controlfile OR switch MUST be present:
  75.  
  76.    controlfile: change for every search-string/replace-string line the
  77.                 'search-string' into 'replace-string'; if more than one
  78.                 search/replace-line is given, subsequent search/replaces
  79.                 start from the beginning.
  80.                 If the controlfile is preceded with a minus (-) the
  81.                 meaning of the 'search-string' and 'replace-string' is
  82.                 swapped.
  83.                 If a line is empty or if there is a semi-colon (;) at the very
  84.                 first column, the line is treated as a comment.
  85.  
  86.  
  87.    switch:      If the switch is preceded with a minus (-) the meaning of
  88.                 the 'search-string' and 'replace-string' is swapped.
  89.  
  90.                 'C'search-string/replace-string
  91.                 ... Change all occurrences of 'search-string' to
  92.                     'replace-string'.
  93.  
  94.                 '[L[1|2|3|4|5]][H[1|2]]'
  95.                 ...  change low-/high-characters to any of the following
  96.                      representations:
  97.  
  98.                      L: change all low-char values c2d(0-32)
  99.                          L .... defaults to L1
  100.                          L1 ... char(0-32) to decimal
  101.                          L2 ... char(0-32) to hexadecimal
  102.                          L3 ... char(0-32) to control-sequence
  103.                          L4 ... char(0-32) to abbreviated comm-characters
  104.                          L5 ... char(0-32) to all representations above
  105.  
  106.                      H: change all high-char values c2d(128-255)
  107.                          H  ... defaults to H1
  108.                          H1 ... char(128-255) to decimal
  109.                          H2 ... char(128-255) to hexadecimal
  110.  
  111.                      The appropriate search-string/replace-string pairs are
  112.                      generated automatically.
  113.  
  114.                 'F'search-string/replace-string
  115.                 ... count the number of occurrences of 'search-string'
  116.  
  117.    search-string/replace-string:
  118.                (delimiter)search-values(delimiter)replace-values(delimiter)
  119.  
  120.          delimiter:
  121.                 very first character in search-string/replace-string
  122.  
  123.          search-values
  124.          replace-values:
  125.                 any ASCII-string intermixed with the following escape-codes
  126.  
  127.                 escape-codes:
  128.                     @C    ... CR
  129.                     @L    ... LF
  130.                     @T    ... TAB
  131.                     @E    ... ESC
  132.                     @Z    ... CTL-Z
  133.                     @@    ... @ (escape for @)
  134.                     @Xnn
  135.                     @Hnn  ... char with the hexadecimal of value 'nn'
  136.                     @Dnnn ... char with the decimal value 'nnn'
  137.  
  138. RxMulch can be called as a function from another REXX-program, e.g.
  139.  
  140.    some_variable = RxMulch(REXXstring, "[/][-]switch")
  141.  
  142. examples:
  143.  
  144.     rxMulch infile outfile controlfile
  145.         ... change 'infile' according to 'controlfile', place results into
  146.             'outfile'
  147.  
  148.  
  149.  
  150.     rxMulch infile controlfile
  151.         ... change 'infile' according to 'controlfile', place results into
  152.             'infile' (i.e. replace 'infile' itself)
  153.  
  154.  
  155.  
  156.     rxMulch infile crlf.ctl
  157.         ... remove empty lines (i.e. CRLFCRLF -> CRLF)
  158.  
  159. or via the commandline:
  160.  
  161.     rxMulch infile /C.@c@l@c@l.@c@l.
  162.         ... change 'infile' according to commandline switch (replace
  163.             consecutive carriage-return/linefeeds with one
  164.             carriage-return/linefeed, i.e. remove one empty line), replace
  165.             'infile'; could be also expressed as:
  166.                   rxMulch infile /C.@xd@xa@xd@xa.@xd@xa.
  167.                   rxMulch infile /C!@d13@d10@d13@d10!@d13@d10!
  168.                   rxMulch infile /C/@d13@d10@d13@d10/@c@l/
  169.  
  170.  
  171.  
  172.     rxMulch infile -crlf.ctl
  173.         ... add an empty line after each line (i.e. CRLF -> CRLFCRLF)
  174.  
  175. or via commandline:
  176.  
  177.     rxMulch infile /-C.@c@l@c@l.@c@l.
  178.         ... change 'infile' according to commandline switch (replace a
  179.             carriage-return/linefeed with two consecutive
  180.             carriage-return/linefeeds, i.e. insert an empty line after each
  181.             line), replace 'infile'; could be also expressed as:
  182.                   rxMulch infile /C,@c@l,@c@l@c@l,
  183.                   rxMulch infile /C=@x0d@x0a=@x0d@x0a@x0dx@0a=
  184.                   rxMulch infile /C=@d13@d10=@d13@d10@x0dx@0a=
  185.  
  186.  
  187.  
  188.     rxMulch infile asc2unix.ctl
  189.         ... change an ASCII-text file to Unix-style (i.e. CRLF -> LF)
  190.  
  191.  
  192.  
  193.     rxMulch infile -asc2unix.ctl
  194.         ... change a Unix-text file to ASCII-style (i.e. LF -> CRLF)
  195.  
  196.  
  197.  
  198.  
  199.     rxMulch < some_in_file > some_out_file controlfile
  200.         ... change 'some_in_file' according to 'controlfile', place results
  201.             into 'some_out_file'; 'some_in_file' and 'some_out_file' are
  202.             redirected ('<' and '>'). rxMulch therefore can be used in pipes
  203.             too.
  204.  
  205.  
  206.  
  207.     rxMulch infile outfile1 /C.Microsoft Excel.Lotus 1-2-3.
  208.         ... change 'infile' according to commandline switch (replace all
  209.             occurrences of 'Microsoft Excel' with 'Lotus 1-2-3'), place
  210.             results into 'outfile1'
  211.  
  212.  
  213.  
  214.     rxMulch outfile1 outfile2 /-C.Microsoft Excel.Lotus 1-2-3.
  215.         ... change 'outfile1' according to commandline switch (replace all
  216.             occurrences of 'Lotus 1-2-3' with 'Microsoft Excel', note the
  217.             minus (-) right before the switch-character), place results into
  218.             'outfile2'; could be also expressed as:
  219.                   rxMulch outfile1 outfile2 /C.Lotus 1-2-3.Microsoft Excel.
  220.  
  221.  
  222.     rxMulch infile /C.;.@c@l.
  223.         ... change 'infile' according to commandline switch (replace
  224.             semicolons (;) with a carriage-return/linefeed), replace
  225.             'infile'; could be also expressed as:
  226.                   rxMulch infile /C.;.@xd@xa.
  227.                   rxMulch infile /C.;.@x0d@x0a.
  228.                   rxMulch infile /C.;.@d13@d10.
  229.  
  230.  
  231.  
  232.     rxMulch infile /C=@x00@x00@x00@x00=@x01@x01@x01@x01=
  233.         ... change 'infile' according to commandline switch (replace all
  234.             hexadecimal strings of 0x00000000 with 0x01010101), replace
  235.             'infile'; could be also expressed as:
  236.                   rxMulch infile /C=@x0@x0@x0@x0=@x1@x1@x1@x1=
  237.                   rxMulch infile /C/@d0@d0@d0@d0/@d1@d1@d1@d1/
  238.  
  239.  
  240.  
  241.     rxMulch infile /F.OS/2.
  242.         ... count occurrences of string 'OS/2' in 'infile'
  243.  
  244.  
  245.  
  246.     rxMulch infile /F.@c@l@c@l.
  247.         ... count number of lines in 'infile', which are immediately
  248.             followed by a blank line
  249.  
  250.  
  251.  
  252. examples for calling RxMulch from a REXX-procedure:
  253.  
  254.     string1 = 'this is nice'
  255.     string2 = RxMulch(string1, '/c.this.that.')  /* change 'this' to 'that' */
  256.         ... string2 = 'that is nice'
  257.     string2 = RxMulch(string2, '/-c.this.that.') /* change 'that' to 'this' */
  258.         ... string2 = 'this is nice'
  259.     occurrences = RxMulch(string2, 'f.this.')    /* count 'this' in string2 */
  260.         ... occurrences = 1
  261.  
  262.  
  263.  
  264. Rony G. Flatscher
  265. Wirtschaftsuniversitaet Wien
  266. Vienna/Austria/Europe
  267. 1996-11-25
  268. ------------------------------------------------------------
  269. 1996-11-25 Version taking advantage of Object Rexx (usage of CHANGESTR yields
  270.            performance increases of factor 50 and more), if installed
  271.