home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / fileutil / chgv200.arj / CHANGE.DOC next >
Encoding:
Text File  |  1991-03-18  |  21.1 KB  |  522 lines
  1.  
  2.  
  3.  
  4.  
  5.    CHANGE User Manual
  6.  
  7.    Utility:        CHANGE v2.00
  8.    Date:   21-Oct-1990
  9.    Last Update: 2-Feb-1991
  10.  
  11.    This work is (c) Copyright 1989'90'91 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 $25.00 in U.S.  currency.
  19.  
  20.    Registered Users receive the latest version of the  software  by  return
  21.    mail  and  all updates made to this software for 1 year from the date of
  22.    registration.   Updates  are  averaging  every  three  to  four  months.
  23.    Registered  versions  of the software do not have any of the advertising
  24.    or other annoying banners, and all of the output may be redirected using
  25.    the  DOS  redirection  operators  or suppressed completely.  Any special
  26.    modifications you may require are available by special request.
  27.  
  28.    Help support the Shareware Concept!
  29.  
  30.  
  31.    Disclaimer:
  32.  
  33.    This software is provided 'as is' and is without  any  warranty  of  any
  34.    kind,  whether  express  or  implied,  including, but not limited to the
  35.    implied warranties of fitness for a particular purpose.  I will  not  be
  36.    liable  for  any special, indirect, incidental, consequential or similar
  37.    damages due to any loss of any kind related to the use of this  software
  38.    or  for any other reason, even if I or an agent of mine has been advised
  39.    of the possibility of such damages.  In no event shall my liability  for
  40.    any  damages ever exceed the price paid for the license to use software,
  41.    regardless of the form of the claim.  The person  choosing  to  use  the
  42.    software  assumes any and all risks as to the quality and performance of
  43.    the software.
  44.  
  45.    Acknowlegements:
  46.  
  47.    Special thanks to my wife Loretta for putting up with all of the time  I
  48.    put in on these little projects.
  49.  
  50.    Thanks to Roedy Green for his constructive feedback on the  program  and
  51.    documentation.
  52.  
  53.    Description
  54.  
  55.    CHANGE allows you to make global changes to the contents of  files.   It
  56.    works  in  much  the  same  way  as your favorite word processors global
  57.  
  58.                                      1
  59.  
  60.                                 CHANGE v2.00
  61.  
  62.  
  63.    change feature.
  64.  
  65.    There are two major differences.
  66.  
  67.          o  The change(s) can  be  propagated  through  all  of  the  files
  68.             specified in a wildcard filespec on the command line.  This can
  69.             include all files in all subdirectories of the current  one  or
  70.             all disks attached to the system.
  71.  
  72.          o  You may specify many changes to be made with one  pass  through
  73.             the file(s).
  74.  
  75.    This utility is indispensable when:
  76.          o  Working with a large number of source files  and  you  need  to
  77.             change variable names.
  78.          o  Working on old code  and  you  want  to  retrofit  some  naming
  79.             standards to make the code make more sense.
  80.          o  Anytime there are a large number of files and a large number of
  81.             changes that need to be made quickly.
  82.  
  83.    Usage
  84.  
  85.    If no parameters are passed  in  to  CHANGE  a  usage  summary  will  be
  86.    printed.   Additional  help  is available in all of my programs by using
  87.    the /HELP switch.
  88.  
  89.    In general:
  90.  
  91.     Usage:
  92.          CHANGE <filespec> <matchString> <replacementString> [...] [/switches]
  93.  
  94.     CHANGE - locates all occurances of the specified file(s) and replaces
  95.             the search string(s) with the specified replacement string(s).
  96.  
  97.     <filespec> may contain a drive, path and filename.  The drive is the volume
  98.     that will be searched.  all files matching the <filespec> will be modified.
  99.     any path entered within the <filespec> is ignored.
  100.  
  101.     Search and Replace strings are single words and uppercased by default.
  102.     Valid delimiters are ('") and search,replace pairs may be separated by spaces
  103.     or commas.  If either string contains DOS redirection characters be sure to
  104.     surround the strings with DOUBLE QUOTES '"'.
  105.     That is the ONLY way to prevent DOS from usurping them.
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.                                      2
  117.  
  118.                                 CHANGE v2.00
  119.  
  120.  
  121.      Currently supported switches:  
  122.                      (Only the upper case characters are required.)
  123.  
  124.        /Help               - Displays this message.
  125.  
  126.        /ALl                - Causes all fixed drives to be searched.
  127.  
  128.        /SHow_context       - Causes the line that matched to be displayed prior
  129.           to the change and prompts the user to confirm that specific change.
  130.           Changes may be allowed (Press 'Y'); Disallowed (press 'N' or RETURN);
  131.           Make all of the changes found from here to the end of this file,
  132.           (press ^Z); Make no more changes to this file, but keep the changes
  133.            made so far (press ESC); or abort the changes completely, (press '^C').
  134.           The default is /NOSHow_context in CHANGE as shipped, See the notes on the
  135.           CHGINST program below.
  136.  
  137.        /[NO]Prefix_change      - Only make the CHANGE if the matchstring is at the
  138.           beginning of a string.  Match 'thisx', not 'xthisx' or 'xthis'.
  139.  
  140.        /[NO]SUffix_change      - Only make the CHANGE if the matchstring is at the
  141.           end of a string.  Match 'xthis', not 'xthisx' or 'thisx'.
  142.  
  143.        /[NO]Whole_words        - Only make a CHANGE if the matchstring is a whole
  144.           surrounded by nonalphanumerics.  Match 'this', not 'xthis' or 'thisx'.
  145.  
  146.        /[NO]SUbdirectories - Causes all subdirectories of the current one to be
  147.           searched.
  148.           The default is /NOSUBDIRECTORIES
  149.  
  150.        /[NO]CAse_sensitive - Allows the searching to be performed respecting
  151.           the case of the match and replacement strings.
  152.           The default is /NOCASE_SENSITIVE in CHANGE as shipped, See the notes on the
  153.           CHGINST program below.
  154.  
  155.        /[NO]Unique_bak     - Guarantees that backup files created will be unique.
  156.           This will prevent CHANGE from deleting a backup file that already
  157.           exists.  CHANGE automatically enables this option when wildcard
  158.           filespecs (like TEST.*) are specified that can overwrite backup files
  159.           that CHANGE just created.
  160.           The default is /Unique_bak in CHANGE as shipped, See the notes on the
  161.           CHGINST program below.
  162.  
  163.        /Binary_file        - This option allows files containing <EOF> characters
  164.           or search strings that span <CR><LF> sequences to be processed.
  165.           /Text_file and /Binary_file are mutually exclusive, /Binary_file takes
  166.           precedence if both are found on the command line.
  167.           This is a synonym for /NOText_file
  168.           /Binary_file is the default in CHANGE as shipped, See the notes on
  169.           the CHGINST program below.
  170.  
  171.        /Text_file          - This option processes files about 2 times faster
  172.           than Binary_file mode. => Note the restrictions listed below.
  173.  
  174.                                      3
  175.  
  176.                                 CHANGE v2.00
  177.  
  178.  
  179.           This is a synonym for /NOBinary_mode
  180.  
  181.        /[NO]Floppysize=n   - Defines the size in KB of the largest floppy on
  182.           your system you want searched.  By default drives a: and B: are not 
  183.           checked at all.  EX: /ALL/FLOPPYSIZE=1200 would check the size of each
  184.           drive before searching.  Only those 1.2MB and up would be searched.
  185.  
  186.        /[NO]COnfirm_change - Prompts for permission to make changes to each
  187.           FILESPEC matched that actually contains a match. This allows the user
  188.           to selectively modify files.
  189.  
  190.        /ANy_attribute      - Change all files matching the FILESPEC, regardless
  191.           of special file attributes. /CONFIRM_CHANGE option is set by default,
  192.           but may be overridden.
  193.  
  194.        /[NO]Log            - Do [NOT] write progress messages to the console.
  195.           The default is /NOLog in CHANGE as shipped, See the notes on the
  196.           CHGINST program below.
  197.  
  198.    CHANGE is now being shipped with a utility called CHGINST.  (new  as  of
  199.    v2.00)
  200.  
  201.    This program allows you to reconfigure the defaults of the most commonly
  202.    used switches to suit your own specific needs.
  203.  
  204.    To use CHGINST just run it from the command line.  It  will  search  for
  205.    CHANGE  in  the  current  directory  and  along the DOS PATH.  If change
  206.    cannot be found it will stop and suggest the following:
  207.  
  208.    Either move CHANGE into the same directory  with  CHGINST,  move  CHANGE
  209.    into a directory along your DOS PATH, or invoke CHGINST with the name of
  210.    the directory that CHANGE is in as a parameter.
  211.  
  212.    Ex:
  213.        CHANGE is in C:\NEWSTUFF and CHGINST is in C:\ use
  214.        CHGINST                -> if C:\NEWSTUFF is in your PATH,
  215.        CHGINST C:\NEWSTUFF    -> if C:\NEWSTUFF is NOT in your PATH.
  216.  
  217.        Note:
  218.          CHGINST DOES depend on CHANGE being called CHANGE.EXE!
  219.  
  220.    General command line handling:
  221.  
  222.    Switches may be placed anywhere on the command line except within quoted
  223.    strings.   Switches  may  be  abbreviated  to the smallest unique string
  224.    among the switches the program supports.
  225.  
  226.    /A is allowed, and would mean to the  program  /ALL  and  /ANYATTRIBUTE.
  227.    /AL/AN would be a better, more specific way to say the same thing.
  228.  
  229.    Everything  on  the  command  line  is  converted  to  uppercase  unless
  230.    surrounded  by  quotes.   Both  double  (")  and  single  (') quotes are
  231.  
  232.                                      4
  233.  
  234.                                 CHANGE v2.00
  235.  
  236.  
  237.    supported.  If your strings contain the DOS re-direction operators  <  >
  238.    or  |  then you MUST enclose the string in DOUBLE QUOTES!  Double Quotes
  239.    will prevent DOS  from  using  them  for  redirection  of  the  standard
  240.    input/output files.
  241.  
  242.    Non printable characters may be placed into the quoted  strings  on  the
  243.    command  line or in indirect files (discussed below) using the following
  244.    syntax:  #nnn where nnn is  the  Decimal  ASCII  code  for  the  desired
  245.    character.   If the end of line characters of a text file (CR and/or LF)
  246.    are being modified the file  MUST  be  converted  in  /BINARY_MODE  (the
  247.    default).
  248.  
  249.    Ex.  #007 - would be converted to the ASCII BEL character.
  250.  
  251.    Normally the DOS command line  supports  parameters  up  to  128  bytes.
  252.    Under  4DOS  this  restriction  is  increased to 255 characters.  CHANGE
  253.    supports the additional characters it can get from the 4DOS environment.
  254.    In addition indirect parameter files can be used for changes that may be
  255.    repeated.  The total size of the resulting  parameter  string  is  still
  256.    restricted to 255 bytes at present.
  257.  
  258.  
  259.    Indirect Parameter Files:
  260.  
  261.    To use an indirect file place an '@' at the beginning of the name of the
  262.    indirect file on the command line.  The indirect file itself may contain
  263.    anything that is normally  allowed  on  the  command  line  for  CHANGE.
  264.    Switches specified in the indirect file may be overridden or added to by
  265.    specifying the new switches on the command line following  the  indirect
  266.    file's name.
  267.  
  268.    CHANGE TEST.PAS @varchang.lis /SUBDIR
  269.  
  270.    This would include  the  list  of  change  strings  found  in  the  file
  271.    VARCHANG.LIS  in  the  current  directory.   The  lines  in the file are
  272.    concatenated together with a space appended to the end of each  line  up
  273.    to the 255 byte max length.  If the resulting command line has an uneven
  274.    number of CHANGE strings specified an error will be reported.
  275.  
  276.    Examples:
  277.  
  278.  
  279.         1.  To rename the ever popular 'foobar'  variable  to  something  a
  280.             little  more  meaningful like 'MyVar' in the program 'test.pas'
  281.             you would use the following CHANGE command:
  282.             CHANGE test.pas 'foobar' 'MyVar'
  283.  
  284.         2.  To do the same in all of your Pascal files in a given directory
  285.             you would use:
  286.             CHANGE *.pas 'foobar' 'MyVar'
  287.  
  288.  
  289.  
  290.                                      5
  291.  
  292.                                 CHANGE v2.00
  293.  
  294.  
  295.         3.  To do the same in all of your Pascal files on a given drive you
  296.             would use:
  297.             CHANGE *.pas 'foobar' 'MyVar' /all
  298.  
  299.         4.  To change strings that contain special characters you  need  to
  300.             represent  the  special  characters in some fashion and 'allow'
  301.             CHANGE to see them.  Any character in  the  ASCII  set  may  be
  302.             specified  in  a  QUOTED  STRING  by  using a # followed by the
  303.             character's three digit decimal ASCII code, for  instance  #007
  304.             is the BEL character.
  305.  
  306.             To reformat a LF delimited text file into a more standard  CRLF
  307.             delimited file use the following:
  308.             CHANGE STRANGE.C '#010' '#013#010'
  309.  
  310.             To change instances of a string only at the start or end  of  a
  311.             line use:
  312.             CHANGE text.fil 'EndString' 'NewEndString'/Prefix
  313.             CHANGE text.fil 'StartString' 'NewStartString'/SUffix
  314.  
  315.         5.  Several CHANGEs may be combined.  The  following  CHANGE  turns
  316.             the  variables  called 'var1' into 'MyOtherVar' and reformats a
  317.             LF delimited text file to a CRLF delimited text file.
  318.             CHANGE *.pas 'foobar' 'MyVar' 'var1' 'MyOtherVar' '#010' '#013#010'
  319.  
  320.         6.  If you have a large or complex change like the one above it  is
  321.             often  better  to  use  an  indirect  file.  The indirect file,
  322.             'BIGCHG.IND', for that change would look like this:
  323.  
  324.             'foobar'          'MyVar'
  325.             'var1'            'MyOtherVar'
  326.             '#010'            '#013#010'
  327.  
  328.             And the invocation of CHANGE would be:
  329.             CHANGE *.PAS @BIGCHG.IND
  330.  
  331.    Change History
  332.  
  333.    The following changes have been  made  to  CHANGE  since  it's  original
  334.    release:
  335.  
  336.         1.  v1.00 - initial release.
  337.         2.  V1.01 - New features and minor bugfixes:
  338.              o  Added /BINARY_MODE.
  339.              o  Speeded up the /TEXT_MODE operation.
  340.              o  Added multiple match,replace string capability.
  341.              o  made a bugfix the error recovery.
  342.         3.  V1.02 - New features:
  343.              o  Add /ANY_ATTRIBUTE.
  344.              o  Add /CONFIRM_CHANGE.
  345.  
  346.  
  347.  
  348.                                      6
  349.  
  350.                                 CHANGE v2.00
  351.  
  352.  
  353.              o  Released as Shareware.
  354.         4.  V1.03 - New features:
  355.              o  Fixed display of files as each is  completed  the  name  is
  356.                 left on a line of it's own.
  357.              o  Now when a file is scanned, but has no matches  it  is  NOT
  358.                 updated.   Previously  ALL  files  that were looked at were
  359.                 marked as updated.
  360.         5.  V1.04 - New features:
  361.              o  /SUB now causes matching files in the current or  specified
  362.                 directory and it's sub-directories to be processed.
  363.              o  A new /SHOW_CONTEXT switch to:
  364.                  -  display the LINE that is about to be changed.
  365.                  -  allow the user to confirm changes on an  item  by  item
  366.                     basis.
  367.              o  A new /WHOLE_WORDS switch to only match when the string  is
  368.                 surrounded by non-alphanumerics.
  369.              o  a new /[NO]LOG switch has been added to allow the  user  to
  370.                 specify  that  progress messages should [NOT] be written to
  371.                 the console.  The default is /LOG.
  372.              o  a new /[NO]UNIQUE_BAK switch has been added  to  allow  the
  373.                 user  to  specify  that  CHANGE  should  not  overwrite any
  374.                 existing .BAK files.  Now if there  is  a  conflict  CHANGE
  375.                 attempts to use .BAL then .BAM etc...
  376.              o  bug fixes:
  377.              o  In previous versions if you attempted to CHANGE a text file
  378.                 that  was not CRLF delimited without using /BINARY_MODE the
  379.                 output file would be truncated to 257 bytes.  This has been
  380.                 trapped  for  and  a  warning  is  issued  allowing  you to
  381.                 allow/disallow saving the changes made.
  382.  
  383.                 A backup file has always been made to presere the  original
  384.                 file.
  385.              o  In previous versions if you made a change with  a  wildcard
  386.                                              t
  387.                 filespec  that  like  TEST.  to process TEST.001, TEST.002,
  388.                 etc.  the backup files would  be  created  on  top  of  one
  389.                 another.   CHANGE  would only leave the backup file for the
  390.                             f
  391.                 last TEST.  file processed  intact.   Now  the  /UNIQUE_BAK
  392.                 option is enabled when this situation is detected.
  393.              o  In previous versions if you made a change with  a  wildcard
  394.                                                                 ,
  395.                 filespec  that included backup files (ex.  TEST., TEST.B??)
  396.                 CHANGE would loop back around and process the backup  files
  397.                 as well.  This situation is now detected and informs you of
  398.                 the problem and warns you that if  you  decide  to  proceed
  399.                 CHANGE will NOT CREATE BACKUP FILES for the files changed.
  400.         6.  V1.05 - New features:
  401.              o  When using the  /SHowcontext  switch  there  are  some  new
  402.                 responses  that  are  allowed.  Pressing ESC will cause the
  403.                 rest of the file to be copied with  out  any  more  changes
  404.                 being  made.   No more prompting will be done.  The changes
  405.                 that have been allowed to date will be saved.   Pressing  Z
  406.                 will  cause  the rest of the file to be copied APPLYING all
  407.                 of the changes to the rest of the  file  without  any  more
  408.  
  409.                                      7
  410.  
  411.                                 CHANGE v2.00
  412.  
  413.  
  414.                 prompting.
  415.  
  416.                 In either of these cases prompting  for  each  change  will
  417.                 resume  in the next file to be processed if the changes are
  418.                 being made to a wildcard list of files.
  419.              o  Optimized the io buffer sizes for Maximum io performance.
  420.              o  Optimized the code for speed in the critical areas and  for
  421.                 size elsewhere.
  422.         7.  V2.00 - New features and modifications:
  423.              o  rewrote /Binary_file for speed.
  424.              o  Changed /Text_file to be the optional mode.  /Text_file  is
  425.                 faster, but it does not handle files containing binary data
  426.                 gracefully.  Use /Text_file for making the fastest  changes
  427.                 possible to CRLF delimited text files.
  428.              o  Enabled /WHolewords in /Binary_file.
  429.              o  Enabled /SHowcontext for /Binary_file.
  430.              o  Greatly improved the way the context is displayed.
  431.              o  Removed /SHowcontext feature from /Text_file.
  432.              o  Added  /Prefix  and  /SUffix   to   both   /Text_file   and
  433.                 /binary_file.
  434.  
  435.                 When /SUffix is specified 'this' will match 'xthis' but not
  436.                 'this'  or  'xthisx' or 'thisx'.  When /Prefix is specified
  437.                 'this' will match 'thisx' but not  'this'  or  'xthisx'  or
  438.                 'xthis'.   The  /WHolewords switch implies BOTH /SUffix and
  439.                 /Prefix.
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.                                      8
  468.  
  469.                                 CHANGE v2.00
  470.  
  471.  
  472.    Known Problems:
  473.  
  474.    The following problems are known to exist in this version:
  475.  
  476.  
  477.         1.  When CHANGE is used on a file that had DOS file protection bits
  478.             set,  the  protection  bits are LOST!  When CHANGE finds one of
  479.             these files and it is told it is Ok to change it,  CHANGE  sets
  480.             the  file's protection to ARCHIVE only.  When the original file
  481.             is renamed to the .BAK version it is left with just the ARCHIVE
  482.             bit  set.   The new version of the file is set to ARCHIVE only.
  483.             It is left  up  to  the  User  to  reset  the  file  protection
  484.             appropriately.
  485.  
  486.             I don't view this as a problem, but you should be aware of it.
  487.  
  488.         2.  When running CHANGE on a Netware file volume you must have  the
  489.             privleges   required   to  edit  the  files  and  to  create  a
  490.             subdirectory off the  directory  containing  the  files  to  be
  491.             CHANGEd.
  492.  
  493.    Planned Changes:
  494.  
  495.         1.  In  addition  to  wildcards,  the  command  line  will  support
  496.             comma-delimited lists of filenames.  This will allow files with
  497.             very different names to be processed in one pass.
  498.  
  499.             Barring unexpected problems this should be released as  a  part
  500.             of v2.01.
  501.  
  502.    If wish to report a problem with this software I can be reached  at  the
  503.    above  address,  or send BixMail to JClinton detailing the nature of the
  504.    problem encountered.
  505.  
  506.    As always I am open to new comments and suggestions!
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.                                      9
  522.