home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-386-Vol-2of3.iso / c / chg205.zip / CHANGE.TXT < prev    next >
Text File  |  1993-02-07  |  27KB  |  620 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                        CHANGE
  9.  
  10.                                      User Manual
  11.  
  12.                                     Version 2.05
  13.  
  14.  
  15.  
  16.  
  17.                                    John W. Clinton
  18.                                     P.O. Box 678
  19.                                    Boston, MA 02136
  20.                                     Bix: JClinton
  21.                                    CIS: 70244,1340
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.             Program and accompanying documentation copyright 1989-'92 by
  61.                                   John W. Clinton.
  62.                                 All rights reserved.
  63.  
  64.  
  65.  
  66.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  67.  
  68.             ____________            Introduction            ____________            Introduction            ____________            Introduction
  69.  
  70.  
  71.             Please pass this software around to your friends and
  72.             associates. Feel free to use this software for a month. If
  73.             you find CHANGE as useful as I do, please Register!. Full
  74.             registration is only $25.00 in U.S. funds.
  75.  
  76.             Registered  Users  receive  the  latest   advertisement-free
  77.             version of the software. Delivery options include EMail  via
  78.             Bix, Compuserve, or  U.S. mail. Registered  Users will  also
  79.             receive all updates made  to CHANGE for a  period of 1  year
  80.             from the date of registration.  Updates to CHANGE have  been
  81.             averaging one every six to eight months. Registered versions
  82.             of the software are smaller and run faster. They do not have
  83.             any of the advertising or other annoying banners. All of the
  84.             output may be redirected using DOS redirection operators  or
  85.             may be suppressed  completely. I often  include a number  of
  86.             other useful utilities with the distribution media as  space
  87.             and availability permit. Any  special modifications you  may
  88.             require  are  available  to  registered  users  by   special
  89.             arrangement. As a matter of policy  I do not currently  make
  90.             the source for any products available.
  91.  
  92.                          Help support the Shareware Concept!                         Help support the Shareware Concept!                         Help support the Shareware Concept!
  93.  
  94.             ___________            Disclaimer:            ___________            Disclaimer:            ___________            Disclaimer:
  95.  
  96.  
  97.             This software is provided 'as is' and is without any
  98.             warranty of any kind, whether express or implied, including,
  99.             but not limited to the implied warranties of fitness for a
  100.             particular purpose. I will not be liable for any special,
  101.             indirect, incidental, consequential or similar damages due
  102.             to any loss of any kind related to the use of this software
  103.             or for any other reason, even if I or an agent of mine has
  104.             been advised of the possibility of such damages. In no event
  105.             shall my liability for any damages ever exceed the price
  106.             paid for the license to use software, regardless of the form
  107.             of the claim. The person choosing to use the software
  108.             assumes any and all risks as to the quality and performance
  109.             of the software.
  110.  
  111.             ________________            Acknowledgments:            ________________            Acknowledgments:            ________________            Acknowledgments:
  112.  
  113.  
  114.             Special thanks to my wife Loretta for putting up with all of
  115.                      the time I put in on these little projects.
  116.              Special thanks to Roedy Green for his constructive feedback
  117.                           on the program and documentation.
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.                                           2
  125.  
  126.  
  127.  
  128.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  129.  
  130.             ____________            Description:            ____________            Description:            ____________            Description:
  131.  
  132.  
  133.             CHANGE allows you to make global changes to the contents of
  134.             files. It works in much the same way as your favorite word
  135.             processor's global change feature.
  136.  
  137.             There are two major differences.
  138.  
  139.                The change(s) are propagated through all of the files in
  140.                a set of comma delimited wildcard filespecs on the
  141.                command line. This can include all files in all sub
  142.                directories of the current sub directory or every
  143.                directory on all disks attached to the system.
  144.  
  145.                You may specify all of the changes to be made with one
  146.                pass through the file(s).
  147.  
  148.             This utility is indispensable when:            This utility is indispensable when:            This utility is indispensable when:
  149.  
  150.                Working with a large number of source files and you need
  151.                to change variable or function names, literals, etc.
  152.                globally.
  153.  
  154.                Working on old code and you want to retrofit it with new
  155.                naming standards to bring the code up to date.
  156.  
  157.                Anytime there are a large number of files and a large
  158.                number of changes that need to be made _______                                                      quickly.
  159.  
  160.  
  161.             Usage:            Usage:            Usage:
  162.  
  163.             If no parameters are passed in to CHANGE a usage summary
  164.             will be printed. Additional help is available by using the
  165.             /HELP switch.
  166.  
  167.             In general:            In general:            In general:
  168.  
  169.                  CHANGE <filespeclist> <matchString> <replacementString>
  170.             [...] [/switches]
  171.  
  172.             CHANGE - locates all occurrences of the specified file(s)
  173.             and replaces the search string(s) with the specified
  174.             replacement string(s).
  175.  
  176.             Each filespec in the <filespeclist> may contain a drive,
  177.             path and filename. The drive is the volume that will be
  178.             searched. All files matching the files in the <filespeclist>
  179.             will be search and modified as needed.
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.                                           3
  187.  
  188.  
  189.  
  190.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  191.  
  192.             Examples:            Examples:            Examples:
  193.  
  194.              Change all C sources in the current directory. Make 'aa'
  195.             into 'bb'.
  196.  
  197.                  CHANGE *.c 'aa' 'bb'
  198.  
  199.             Change all C source files in .\SRC, all Headers in .\INC and
  200.             all files in .\TMP.  Make 'foo' into 'foobar'.
  201.  
  202.                  CHANGE SRC\*.C,INC\*.H,TMP\*.* 'foo','foobar'
  203.  
  204.             Search and Replace strings are single words or quoted
  205.             strings. Either single or double quotes will do. Everything
  206.             on the command line is uppercased unless surrounded by
  207.             quotes. The Search and Replace parameters may be separated
  208.             by spaces or commas. If DOS redirection characters are part
  209.             of any string on the command line they MUST be surrounded by
  210.             DOUBLE QUOTES!  That is the ONLY way to prevent DOS from
  211.             usurping them.
  212.  
  213.             __________________            Customizing CHANGE            __________________            Customizing CHANGE            __________________            Customizing CHANGE
  214.  
  215.  
  216.             CHANGE is now being shipped with a utility called CHGINST.
  217.             This program allows you to re configure the defaults of the
  218.             most commonly used (but not all) switches to suit your own
  219.             specific needs. To use CHGINST just run it from the command
  220.             line. It will search for CHANGE in the current directory and
  221.             along the DOS PATH. If change cannot be found it will stop
  222.             and suggest the following:
  223.  
  224.             Either move CHANGE into the same directory with CHGINST,
  225.             move CHANGE into a directory along your DOS PATH, or invoke
  226.             CHGINST with the name of the directory that CHANGE is in as
  227.             a parameter.
  228.  
  229.             Example:            Example:            Example:
  230.  
  231.                  CHANGE is in C:\UTILS and CHGINST is in C:\ use
  232.  
  233.                  CHGINST        -> if C:\UTILS is in your PATH,
  234.  
  235.                  CHGINST C:\UTILS  -> if C:\UTILS is NOT in your PATH.
  236.  
  237.                Note:               Note:               Note:
  238.  
  239.                  CHGINST DOES depend on CHANGE being called CHANGE.EXE!
  240.  
  241.             ______________________________            General command line handling:            ______________________________            General command line handling:            ______________________________            General command line handling:
  242.  
  243.  
  244.             Switches are placed anywhere on the command line except
  245.             within quoted strings.  Switches may be abbreviated to the
  246.  
  247.  
  248.                                           4
  249.  
  250.  
  251.  
  252.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  253.  
  254.             smallest unique string among the switches the program
  255.             supports. The absolute minimum number of characters required
  256.             for each of the switches is indicated by the uppercase part
  257.             of the switch names on the help screen. Everything on the
  258.             command line is converted to uppercase unless surrounded by
  259.             quotes.  Both double (") and single (') quotes are
  260.             supported. If you need imbedded special characters or spaces
  261.             in a parameter surround it with quotes. Text containing
  262.             single quotes may be surrounded by double quotes, and text
  263.             containing single quotes may be surrounded by double quotes.
  264.             Non printable characters may be placed into the quoted
  265.             strings on the command line or in indirect files (discussed
  266.             below) using the following syntax: #nnn or ^a where 'nnn' is
  267.             the Decimal ASCII code for the desired character and 'a' is
  268.             '@'..'Z' corresponding to ^@ through ^Z.
  269.  
  270.             DOS Notes:            DOS Notes:            DOS Notes:
  271.  
  272.                1.DOS has a gotcha for strings like "Contains 4 spaces '
  273.                  '". It will convert the 4 spaces to a single space
  274.                  before CHANGE gets control. This is only a problem for
  275.                  parameters entered on the command line. Indirect files
  276.                  handle this situation correctly. CHANGE also supports
  277.                  an enviroment string 'CMDLINE=' if it is present as a
  278.                  source for it's command line. This permits 4DOS users
  279.                  to automatically avoid this problem. It also allows
  280.                  them to support up to 255 characters on the command
  281.                  line.
  282.  
  283.                2.If your string(s) contain the DOS re-direction
  284.                  operators '<' '>' or '|' then you MUST enclose the
  285.                  string in DOUBLE QUOTES! Double Quotes will prevent DOS
  286.                  from using them for redirection of the standard
  287.                  input/output files.
  288.  
  289.             Examples:            Examples:            Examples:
  290.  
  291.                  #007  - Is the ASCII BEL Character.
  292.  
  293.                  ^G   - also the ASCII BEL character.
  294.  
  295.                  5#0075 - would be converted to 5's surrounding a BEL.
  296.  
  297.                  x#7x  - would be converted to x's surrounding a BEL.
  298.  
  299.             The leading zeros are required in ex. 1&3 to keep the other
  300.             numbers from confusing CHANGE. They may be omitted when
  301.             there is only one way to interpret the data. These special
  302.             characters ( '#' and '^' ) may appear in your data as long
  303.             as they are unambiguous. When in doubt, use two of the
  304.             special characters to get one. See the examples below.
  305.  
  306.             Normally the DOS command line supports parameters up to 128
  307.             bytes. Indirect parameter files may be used for changes that
  308.  
  309.  
  310.                                           5
  311.  
  312.  
  313.  
  314.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  315.  
  316.             either require more than 128 bytes of input OR for CHANGEs
  317.             that may be used again in the future. The total size of the
  318.             parameters may now total in excess of 64KB.
  319.  
  320.             _________________________            Indirect Parameter Files:            _________________________            Indirect Parameter Files:            _________________________            Indirect Parameter Files:
  321.  
  322.  
  323.             To use an indirect file place an '@' at the beginning of the
  324.             name of the indirect file on the command line. The indirect
  325.             file itself may contain anything that is normally allowed on
  326.             the command line for CHANGE.
  327.  
  328.               Switches specified in the indirect file may be overridden
  329.             or added to by specifying the new switches on the command
  330.             line following the indirect file's name.
  331.  
  332.                  CHANGE TEST.PAS @varchang.lis /SUBDIR
  333.  
  334.             This would include the list of change strings found in the
  335.             file VARCHANG.LIS (in the current directory).  The lines in
  336.             the file are concatenated together with a space appended to
  337.             the end of each line. If the resulting command line has an
  338.             odd number of CHANGE strings specified an error will be
  339.             reported.
  340.  
  341.                A reminder about Case:               A reminder about Case:               A reminder about Case:
  342.  
  343.             Remember that the command line is always uppercased first.
  344.             If you are using the /CASE switch then you will probably
  345.             want to surround your match and replace strings with quotes.
  346.             If you want lower case in your replacements then be sure to
  347.             surround the replace string with quotes! Be sure when using
  348.             foreign language character sets or plain binary data that
  349.             you use both quoting and the /CASE switch to prevent any
  350.             potential problems with the interpretation of these
  351.             characters!
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.                                           6
  373.  
  374.  
  375.  
  376.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  377.  
  378.             More Examples:            More Examples:            More Examples:
  379.  
  380.             1. To rename the ever popular 'foobar' variable to 'MyVar'
  381.               in the program 'test.pas' you would use the following
  382.               CHANGE command:
  383.  
  384.                  CHANGE test.pas 'foobar' 'MyVar'
  385.  
  386.             2. To change foobar to @#^foobar (use of special chars)
  387.               double up the special chars. Use:
  388.  
  389.                  CHANGE *.pas 'foobar' '@@##^^foobar'
  390.  
  391.             3. To change strings that contain special characters you
  392.               need to represent the special characters in some fashion
  393.               and 'allow' CHANGE to see them. Any character in the ASCII
  394.               set may be specified in a QUOTED STRING by using a #
  395.               followed by the character's three digit decimal ASCII
  396.               code, for instance #007 is the BEL character.
  397.  
  398.             To reformat a LF delimited text file into a more standard
  399.             CRLF delimited file use the following:
  400.  
  401.                  CHANGE STRANGE.C ^J ^M^J
  402.  
  403.             4. Several CHANGEs may be combined. The following CHANGE
  404.               turns the variables called 'var1' into 'MyOtherVar' and
  405.               reformats a LF delimited text file to a CRLF delimited
  406.               text file.
  407.  
  408.                  CHANGE *.PAS 'foobar','MyVar' 'var1','MyOtherVar'
  409.             #10,#13#10
  410.  
  411.             5. If you have a large or complex change like the one above
  412.               it is often better to use an indirect file. The indirect
  413.               file, 'BIGCHG.IND', for that change would look like this:
  414.                  !===Start of file BIGCHG.IND===
  415.                  ! Comments are allowed within indirect files.
  416.                  ! They are lines that being with an '!'
  417.                  'foobar', 'MyVar'
  418.                  'var1',        'MyOtherVar'
  419.                  #10,      #13#10
  420.                  !===End of file BIGCHG.IND===
  421.  
  422.             And the invocation of CHANGE would be:
  423.  
  424.                  CHANGE *.PAS @BIGCHG.IND
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.                                           7
  435.  
  436.  
  437.  
  438.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  439.  
  440.             ______________            Change History            ______________            Change History            ______________            Change History
  441.  
  442.  
  443.             A complete history of CHANGE has been moved to the file
  444.             HISTORY.DOC.
  445.  
  446.             _______________            Known Problems:            _______________            Known Problems:            _______________            Known Problems:
  447.  
  448.  
  449.             The following problems are known to exist in this version:
  450.  
  451.             1. When CHANGE is used on a file that had DOS file
  452.               protection bits set, the protection bits are LOST! When
  453.               CHANGE finds one of these files and it is told it is Ok to
  454.               change it, CHANGE sets the file's protection to ARCHIVE
  455.               only. When the original file is renamed to the .BAK
  456.               version it is left with just the ARCHIVE bit set.  The new
  457.               version of the file is set to ARCHIVE only. It is left up
  458.               to the User to reset the file protection appropriately.
  459.  
  460.             I don't view this as a bug, but you should be aware of it.
  461.  
  462.             2. When running CHANGE on a Netware file volume you must
  463.               have the privileges required to edit the files and to
  464.               create a subdirectory in the directory containing the
  465.               file(s) to be CHANGEd.
  466.  
  467.             ________________            Planned Changes:            ________________            Planned Changes:            ________________            Planned Changes:
  468.  
  469.  
  470.             CHANGE is currently 92% Turbo Pascal v6.0, the remainder is
  471.             TASM.
  472.  
  473.             If I get enough requests I will be adding unix grep style
  474.             'regular expression' pattern matching. If you need this
  475.             please let me know! ( So far there has been 1 inquiry )
  476.  
  477.             ______________________            Encountering Problems:            ______________________            Encountering Problems:            ______________________            Encountering Problems:
  478.  
  479.  
  480.             If you wish to report a problem with this software I can be
  481.             reached at the above address, or send electronic mail to me
  482.             via Bix (JClinton) or CompuServe (70244,1340). Please
  483.             provide as much detail into the nature of the problem
  484.             encountered, along with the system configuration details and
  485.             SMALL examples of the data that demonstrates the problem.
  486.  
  487.               As always I welcome new ideas, comments and suggestions!
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.                                           8
  497.  
  498.  
  499.  
  500.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  501.  
  502.             Appendix A            Appendix A            Appendix A
  503.  
  504.             Currently supported switches:            Currently supported switches:            Currently supported switches:
  505.                           (Only the upper case characters are required.)
  506.  
  507.             /Help           - Displays this message.
  508.             /[NO]ALL        - Causes all fixed drives to be completely
  509.                             searched.
  510.             /[NO]SHow_context   - Causes the line that matched to be
  511.                             displayed prior to the change and prompts
  512.                             the user to confirm that specific change.
  513.                             Changes may be allowed (Press 'Y');
  514.                             Disallowed (press 'N' or RETURN); Make all
  515.                             of the changes found from here to the end
  516.                             of this file, (press ^Z); Make no more
  517.                             changes to this file, but keep the changes
  518.                             made so far (press ESC); or abort the
  519.                             changes made to this file completely,
  520.                             (press '^C'). Press ? for additional help
  521.                             at the CHANGE prompt. The default is
  522.                             /SHow_context in CHANGE as shipped, See the
  523.                             notes on the CHGINST program below.
  524.              /[NO]HEX_display   - When /SHow_context is in use this
  525.                             makes the HexViewer provide the first look
  526.                             at the file. 'A' and 'H' can still be used
  527.                             to switch between the Hex and ASCII
  528.                             viewers.
  529.              /[NO]Prefix_change - Only make the CHANGE if the
  530.                             matchstring is at the beginning of a
  531.                             string. Match 'thisx', not 'xthisx' or
  532.                             'xthis'.
  533.              /[NO]SUffix_change  - Only make the CHANGE if the
  534.                             matchstring is at the end of a string.
  535.                             Match 'xthis', not 'xthisx' or 'thisx'.
  536.              /[NO]Whole_words   - Only make a CHANGE if the matchstring
  537.                             is a whole surrounded by non alphanumerics.
  538.                             Match 'this', not 'xthis' or 'thisx'.
  539.              /[NO]Sub directories    - Causes all sub directories of the
  540.                             current one to be searched. The default is
  541.                             \NOSUbdirectories in CHANGE as shipped, See
  542.                             the notes on the CHGINST program below.
  543.              /[NO]Case_sensitive     - Allows the searching to be
  544.                             performed respecting the case of the match
  545.                             and replacement strings. The default is
  546.                             /NOCASE_SENSITIVE in CHANGE as shipped, See
  547.                             the notes on the CHGINST program below.
  548.              /[NO]Unique_bak    - Guarantees that backup files created
  549.                             will be unique. This will prevent CHANGE
  550.                             from deleting a backup file that already
  551.                             exists. CHANGE automatically enables this
  552.                             option when wildcard filespecs (like
  553.                             TEST.*) are specified that can overwrite
  554.                             backup files that CHANGE just created.
  555.  
  556.  
  557.  
  558.                                           9
  559.  
  560.  
  561.  
  562.                                     CHANGE v2.05                                    CHANGE v2.05                                    CHANGE v2.05
  563.  
  564.              The default is /Unique_bak in CHANGE as shipped, See the
  565.                             notes on the CHGINST program below.
  566.              /[NO]Floppysize=n  - Defines the size in KB of the largest
  567.                             floppy on your system you want searched. By
  568.                             default drives a: and B: are not checked at
  569.                             all. EX: /ALL/FLOPPYSIZE=1200 would check
  570.                             the size of each drive before searching.
  571.                             Only those 1.2MB and up would be searched.
  572.              /[NO]COnfirm_change     - Prompts for permission to make
  573.                             changes to each FILESPEC matched that
  574.                             actually contains a match. This allows the
  575.                             user to selectively modify files.
  576.              /ANy_attribute - Change all files matching the FILESPEC,
  577.                             regardless of special file attributes.
  578.                             /CONFIRM_CHANGE option is set by default,
  579.                             but may be overridden.
  580.              /[NO]Log       - Do [NOT] write progress messages to the
  581.                             console. The default is /NOLog in CHANGE as
  582.                             shipped, See the notes on the CHGINST
  583.                             program below.
  584.              /[NO]BACKups   - Do [NOT] rename the original files to
  585.                             .BAK. The default is /BACKups in CHANGE as
  586.                             shipped, See the notes on the CHGINST
  587.                             program below.
  588.             * /[NO]Quote_mode=? - Do [NOT] use the quote 'respect'
  589.                             features.
  590.                             ?: Only_in_quotes  == Just change things
  591.                             WITHIN quotes.
  592.                             Protect_quotes     == Just change things
  593.                             OUTSIDE quotes.
  594.                             Ignore_quotes == (delivered default) change
  595.                             in and out of quotes.
  596.                             The default is /Quote_mode=Ignore
  597.             * /QUote_char=? - Specify a quote character.
  598.                             ?: Single_quotes   == Specify that quotes
  599.                             are "'".
  600.                             Double_quotes == Specify that quotes are
  601.                             '"'.
  602.                             <any_char>    == Specify a custom quote
  603.                             character.
  604.                             This character may be (paradoxically)
  605.                             presented in quotes!
  606.                             The default is /QUOTE_CHAR='
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.                                          10