home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / fileutil / chgv104.com / CHANGE.DOC next >
Encoding:
Text File  |  1990-12-16  |  15.8 KB  |  410 lines

  1.  
  2.  
  3.  
  4.  
  5.    CHANGE User Manual
  6.  
  7.    Utility:        CHANGE v1.04
  8.    Date:   21-Oct-1990
  9.    Last Update: 10-Dec-1990
  10.  
  11.    This work is (c) Copyright 1990 by John W. Clinton.
  12.    23 Goff Street
  13.    Hyde Park, MA 02136
  14.  
  15.    All rights reserved.
  16.    Please pass this software around to your friends and  associates.   Feel
  17.    free  to use this software for a month.  If you find CHANGE as useful as
  18.    I do, please Register!.  Full registration is $15.00 in U.S.  currency.
  19.  
  20.    Registered Users receive the latest version of the  software  by  return
  21.    mail  and  any updates made to this software for 1 year from the date of
  22.    registration.  Registered versions of the software do not  have  any  of
  23.    the  advertising  in the banner, and all of the output may be redirected
  24.    using the DOS redirection operators.  Any special modifications that may
  25.    be required are available by special arrangements.
  26.  
  27.    Help support the Shareware Concept!
  28.  
  29.  
  30.    Disclaimer:
  31.  
  32.    This software is provided 'as is' and is without  any  warranty  of  any
  33.    kind,  whether  express  or  implied,  including, but not limited to the
  34.    implied warranties of fitness for a particular purpose.  I will  not  be
  35.    liable  for  any special, indirect, incidental, consequential or similar
  36.    damages due to any loss of any kind related to the use of this  software
  37.    or  for any other reason, even if I or an agent of mine has been advised
  38.    of the possibility of such damages.  In no event shall my liability  for
  39.    any  damages ever exceed the price paid for the license to use software,
  40.    regardless of the form of the claim.  The person  choosing  to  use  the
  41.    software  assumes any and all risks as to the quality and performance of
  42.    the software.
  43.  
  44.    Acknowlegements:
  45.  
  46.    Special thanks to my wife Loretta for putting up with all of the time  I
  47.    put in on these little projects.
  48.  
  49.    Thanks to Roedy Green for his constructive feedback on the  program  and
  50.    documentation.
  51.  
  52.    Description
  53.  
  54.    CHANGE allows you to make global changes to the contents of  files.   It
  55.    works  in  much  the  same  way  as your favorite word processors global
  56.    change feature.  There are two major differences.
  57.  
  58.                                      1
  59.  
  60.                                 CHANGE v1.04
  61.  
  62.  
  63.          o  The change(s) can  be  propagated  through  all  of  the  files
  64.             specified in a wildcard filespec on the command line;
  65.          o  You may specify several  changes  to  be  made  with  one  pass
  66.             through the file(s).
  67.  
  68.    This utility is indispensable when:
  69.          o  Working with a large number of source files and someone decides
  70.             that variable names need to change.
  71.          o  Working on old code  and  you  want  to  retrofit  some  naming
  72.             standards.
  73.          o  Anytime there are a large number of files and a large number of
  74.             changes that need to be made quickly.
  75.  
  76.    Usage
  77.  
  78.    If no parameters are passed  in  to  CHANGE  a  usage  summary  will  be
  79.    printed.   Additional  help  is available in all of my programs by using
  80.    the /HELP switch.
  81.  
  82.    In general:
  83.  
  84.       Usage:
  85.          CHANGE <FILESPEC> <matchString> <replacementString> [...] [/switches]
  86.  
  87.     CHANGE - locates all occurances of the specified file( s ) and replaces
  88.             the search string(s) with the specified replacement string(s).
  89.  
  90.     <filespec> may contain a drive, path and filename.  The drive is the volume
  91.     that will be searched.  all files matching the <filespec> will be modified.
  92.     any path entered within the <filespec> is ignored.
  93.  
  94.     Search and Replace strings are single words and uppercased by default.
  95.     Valid delimiters are ('") and search,replace pairs may be separated by spaces
  96.     or commas.  If either string contains DOS redirection characters be sure to
  97.     surround the strings with DOUBLE QUOTES '"'.
  98.     That is the ONLY way to prevent DOS from usurping them.
  99.  
  100.      Currently supported switches:  (Upper case is all that is required.)
  101.        /Help               - Displays this message.
  102.        /ALl                - Causes all fixed drives to be searched.
  103.        /SHow_context       - Causes the line that matched to be displayed prior
  104.           to the change and prompts the user to confirm it.
  105.        /Whole_words        - Before a change is made check to be sure the string
  106.           that was found is surrounded by non-alphanumerics.
  107.        /[NO]SUbdirectories - Causes all subdirectories of the current one to be
  108.           searched.
  109.           The default is /NOSUBDIRECTORIES
  110.        /[NO]CAse_sensitive - Allows the searching to be performed respecting
  111.           the case of the match and replacement strings.
  112.           The default is /NOCASE_SENSITIVE
  113.  
  114.  
  115.  
  116.                                      2
  117.  
  118.                                 CHANGE v1.04
  119.  
  120.  
  121.        /[NO]Unique_bak     - Guarantees that backup files created will be unique.
  122.           This will prevent CHANGE from deleting a backup file that already
  123.           exists.  CHANGE automatically enables this option when wildcard
  124.           filespecs (like TEST.*) are specified that can overwrite backup files
  125.           that CHANGE just created.
  126.           The default is /NOUNIQUE_BAK
  127.        /Text_file          - This option is the default, and is about 3 times
  128.           faster than BINARY_FILE mode.  Note the restrictions listed below.
  129.        /Binary_file        - This option allows files containing <EOF> characters
  130.           or search strings that span <CR><LF> sequences to be processed.
  131.           /TEXT_FILE and /BINARY_FILE are mutually exclusive, /BINARY_FILE takes
  132.           precedence if both are found on the command line.
  133.        /[NO]Floppysize=n   - Defines the size in KB of the largest floppy on
  134.           your system you want searched.  By default drives a: and B: are not
  135.           checked at all.  EX: /ALL/FLOPPYSIZE=1200 would check the size of each
  136.           drive before searching.  Only those 1.2MB and up would be searched.
  137.        /[NO]COnfirm_change - Prompts for permission to make changes to each
  138.           FILESPEC matched that actually contains a match. This allows the user
  139.           to selectively modify files.
  140.        /ANy_attribute      - Change all files matching the FILESPEC, regardless
  141.           of special file attributes. /CONFIRM_CHANGE option is set by default,
  142.           but may be overridden.
  143.        /[NO]Log            - Do [NOT] write progress messages to the console.
  144.  
  145.    General command line handling:
  146.  
  147.    Switches may be placed anywhere on the command line except within quoted
  148.    strings.   Switches  may  be  abbreviated  to the smallest unique string
  149.    among the switches the program supports.
  150.  
  151.    /A is allowed, and would mean to the  program  /ALL  and  /ANYATTRIBUTE.
  152.    /AL/AN would be a better, more specific way to say the same thing.
  153.  
  154.    Everything  on  the  command  line  is  converted  to  uppercase  unless
  155.    surrounded  by  quotes.   Both  double  (")  and  single  (') quotes are
  156.    supported.   If  your  string  need  to  contain  the  DOS  re-direction
  157.    operators < > | then you MUST enclose the string in DOUBLE QUOTES!  They
  158.    will prevent DOS  from  using  them  for  redirection  of  the  standard
  159.    input/output files.
  160.  
  161.    Non printable characters may be placed into the quoted  strings  on  the
  162.    command  line or in indirect files (discussed below) using the following
  163.    syntax:  #nnn where nnn is the ASCII code for the desired character.  If
  164.    the  end  of  line  characters  of  a text file (CR and/or LF) are being
  165.    modified the file MUST be converted in /BINARY_MODE.
  166.    Ex.  #007 - would be converted to the ASCII BEL character.
  167.  
  168.    Normally the DOS command line  supports  parameters  up  to  128  bytes.
  169.    Under  4DOS  this  restriction  is  increased to 255 characters.  CHANGE
  170.    supports the additional characters it can get from  4DOS.   In  addition
  171.    indirect  parameter  files can be used for changes that may be repeated.
  172.    The total size of the resulting parameter string is still restricted  to
  173.  
  174.                                      3
  175.  
  176.                                 CHANGE v1.04
  177.  
  178.  
  179.    255 bytes at present.
  180.  
  181.  
  182.    Indirect Parameter Files:
  183.  
  184.    To use an indirect file place an '@' at the beginning of the name of the
  185.    indirect file on the command line.  The indirect file itself may contain
  186.    anything that is normally  allowed  on  the  command  line  for  CHANGE.
  187.    Switches specified in the indirect file may be overridden or added to by
  188.    specifying the new switches on the command line following  the  indirect
  189.    file's name.
  190.  
  191.    CHANGE TEST.PAS @varchang.lis /SUBDIR
  192.  
  193.    This would include  the  list  of  change  strings  found  in  the  file
  194.    VARCHANG.LIS  in  the  current  directory.   The  lines  in the file are
  195.    concatenated together with a space appended to the end of each  line  up
  196.    to the 255 byte max length.  If the resulting command line has an uneven
  197.    number of CHANGE strings specified an error will be reported.
  198.  
  199.    Examples:
  200.  
  201.  
  202.         1.  To rename the ever popular 'foobar'  variable  to  something  a
  203.             little  more  meaningful like 'MyVar' in the program 'test.pas'
  204.             you would use the following CHANGE command:
  205.             CHANGE test.pas 'foobar' 'MyVar'
  206.  
  207.         2.  To do the same in all of your Pascal files in a given directory
  208.             you would use:
  209.             CHANGE *.pas 'foobar' 'MyVar'
  210.  
  211.         3.  To do the same in all of your Pascal files on a given drive you
  212.             would use:
  213.             CHANGE *.pas 'foobar' 'MyVar' /all
  214.  
  215.         4.  To change strings that contain special characters you  need  to
  216.             represent  the  special  characters in some fashion and 'allow'
  217.             change to see them.  Any character in  the  ASCII  set  may  be
  218.             specified  in  a  QUOTED  STRING  by  using a # followed by the
  219.             character's three digit decimal ASCII code, for  instance  #007
  220.             is the BEL character.
  221.  
  222.             To reformat a LF delimited text file into a more standard  CRLF
  223.             delimited file use the following:
  224.             CHANGE STRANGE.C '#010' '#013#010'
  225.  
  226.             To change instances of a string only at the start or end  of  a
  227.             line use:
  228.             CHANGE text.fil 'EndString#013' 'NewEndString#013'
  229.             CHANGE text.fil '#010StartString' '#010NewStartString'
  230.  
  231.  
  232.                                      4
  233.  
  234.                                 CHANGE v1.04
  235.  
  236.  
  237.         5.  Many things may be combined, the  above  change  plus  changing
  238.             variables  called  'var1' to 'MyOtherVar' and reformatting a LF
  239.             delimited text file to a CRLF delimited text file.
  240.             CHANGE *.pas 'foobar' 'MyVar' 'var1' 'MyOtherVar' '#010' '#013#010' -
  241.             '#013StartString' '#013NewStartString'
  242.  
  243.         6.  If you have a large or complex change like the one above it  is
  244.             often  better  to  use  an  indirect  file.  The indirect file,
  245.             'BIGCHG.IND', for that change would look like this:
  246.  
  247.             'foobar'          'MyVar'
  248.             'var1'            'MyOtherVar'
  249.             '#010'            '#013#010'
  250.             '#010StartString' '#010NewStartString'
  251.  
  252.             And the invocation of CHANGE would be:
  253.             CHANGE *.PAS @BIGCHG.IND
  254.  
  255.    Change History
  256.  
  257.    The following changes have been made to the software listed above:
  258.  
  259.         1.  v1.00 - initial release.
  260.         2.  V1.01 - New features and minor bugfixes:
  261.              o  Added /BINARY_MODE.
  262.              o  Speeded up the /TEXT_MODE operation.
  263.              o  Added multiple match,replace string capability.
  264.              o  made a bugfix the error recovery.
  265.         3.  V1.02 - New features:
  266.              o  Add /ANY_ATTRIBUTE.
  267.              o  Add /CONFIRM_CHANGE.
  268.              o  Released as Shareware.
  269.         4.  V1.03 - New features:
  270.              o  Fixed display of files as each is  completed  the  name  is
  271.                 left on a line of it's own.
  272.              o  Now when a file is scanned, but has no matches  it  is  NOT
  273.                 updated.   Previously  ALL  files  that were looked at were
  274.                 marked as updated.
  275.         5.  V1.04 - New features:
  276.              o  /SUB now causes matching files in the current or  specified
  277.                 directory and it's sub-directories to be processed.
  278.              o  A new /SHOW_CONTEXT switch to:
  279.                  -  display the LINE that is about to be changed.
  280.                  -  allow the user to confirm changes on an  item  by  item
  281.                     basis.
  282.              o  A new /WHOLE_WORDS switch to only match when the  string is
  283.                 surrounded by non-alphanumerics.
  284.              o  a new /[NO]LOG switch has been added to allow the  user  to
  285.                 specify  that  progress messages should [NOT] be written to
  286.                 the console.  The default is /LOG.
  287.  
  288.  
  289.  
  290.                                      5
  291.  
  292.                                 CHANGE v1.04
  293.  
  294.  
  295.              o  a new /[NO]UNIQUE_BAK switch has been  added  to  allow the
  296.                 user  to  specify  that  CHANGE  should  not  overwrite any
  297.                 existing .BAK files.  Now if there  is  a  conflict  CHANGE
  298.                 attempts to use .BAL then .BAM etc...
  299.              o  bug fixes:
  300.              o  In previous versions if you attempted to CHANGE a text file
  301.                 that  was not CRLF delimited without using /BINARY_MODE the
  302.                 output file would be truncated to 257 bytes.  This has been
  303.                 trapped  for  and  a  warning  is  issued  allowing  you to
  304.                 allow/disallow saving the changes made.
  305.  
  306.                 A backup file has always been made to presere the  original
  307.                 file.
  308.              o  In previous versions if you made a change with  a  wildcard
  309.                                              t
  310.                 filespec  that  like  TEST.  to process TEST.001, TEST.002,
  311.                 etc.  the backup files would  be  created  on  top  of  one
  312.                 another.   CHANGE  would only leave the backup file for the
  313.                             f
  314.                 last TEST.  file  processed  intact.   Now  the /UNIQUE_BAK
  315.                 option is enabled when this situation is detected.
  316.              o  In previous versions if you made a change with  a  wildcard
  317.                 filespec  that included backup files (ex.  TEST., TEST.B??)
  318.                 CHANGE would loop back around and process the backup  files
  319.                 as well.  This situation is now detected and informs you of
  320.                 the problem and warns you that if  you  decide  to  proceed
  321.                 CHANGE will NOT CREATE BACKUP FILES for the files changed.
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.                                      6
  352.  
  353.                                 CHANGE v1.04
  354.  
  355.  
  356.    Known Problems
  357.  
  358.    The following problems are known to exist in this version:
  359.  
  360.  
  361.         1.  When CHANGE is used on a file that had DOS file protection bits
  362.             set,  the  protection  bits are LOST!  When CHANGE finds one of
  363.             these files and it is told it is Ok to change it,  CHANGE  sets
  364.             the  file's protection to ARCHIVE only.  When the original file
  365.             is renamed to the .BAK version it is left with just the ARCHIVE
  366.             bit  set.   The new version of the file is set to ARCHIVE only.
  367.             It is left  up  to  the  User  to  reset  the  file  protection
  368.             appropriately.
  369.  
  370.             I don't view this as a problem, but you should be aware of it.
  371.  
  372.    If wish to report a problem with this software I can be reached  at  the
  373.    above  address,  or send BixMail to JClinton detailing the nature of the
  374.    problem encountered.
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.                                      7
  410.