                              //
ͻͻ  ͻͻ//ĿĿĿ
   ͼ ɻ          //           
   ͻ ȼȼ ͻ  ͼ  //    ٳ    
ͻ      ɻ        // ٳ  Ŀ  ڿ  
ͼ        ͼ  ͻ //              
                //              
ͼͼͼ//   
                      //

                                 Version 2.1a
                       (c) 1991-1995 by Craig A. Cassidy



 A DOS command line utility that allows you to perform a word-processor-like
 search and replace on text strings in standard ASCII text files.


   ¿
   



SWITCH is a small utility designed to replace occurrences of strings in ASCII
text files.  The usefulness of this utility comes from its ability to
perform numerous changes without user intervention thus allowing you to
quickly make global changes to a file or to run the program from within a
batch file.




Ŀ
 I. Syntax Ŀ
 
  

      Command Line Syntax (Input File Format): Ŀ
                                                                           
      SWITCH targetfile /f:input-file                                      
     

      Command Line Syntax (No Input File): Ŀ
                                                                           
      SWITCH targetfile search-string replace-string [optional parameters] 
     
                               - figure 1 -


   There are several possible command line options you may use with the
   SWITCH program.  The format of the command line will vary greatly
   depending on the source of input for the "switch."  In all cases the
   first required parameter will be the name of the file that you wish to 
   change (referred to as "targetfile" in figure 1).

   If you wish to switch only one set of strings in your target file, you may
   specify them on the command line as the second and third required
   parameters.  These two parameters are referred to as "search-string" and
   "replace-string" in the figure above.  Optionally you could specify a
   source-file-name using the /f: option (ex: /f:myfile.txt).  Doing this
   overrides the need to specify any options other than the targetfile.

   The "TargetFile" option may contain wildcards (i.e. "*" and "?").  These
   wildcards are used in the same manner they would be for a DOS command
   such as "DEL".  When using wildcards SWITCH will process all files meeting
   the criteria specified.  "targetfile" may also contain a fully specified
   path name (i.e. "C:\WORD\DOCS\MYFILE.TXT").

   Both the "Search-String" and "Target-String" parameters may contain
   multiple word phrases (i.e. "Mary had a little lamb.") so long as they
   are surrounded by quotes.




Ŀ
 II. Optional Parameters Ŀ
 
  

    In order to customize the way SWITCH will do a search-and-replace, you
    must specify certain optional parameters either on the command line or
    in the input file.  These parameters must be preceded by a "/" if used
    on the command line.

    Following is a description of each option:

     ͻ
      Code  Description                                                  
     Ķ
       c    Case-Sensitivity Off                                         
                                                                         
            Turns case-sensitivity OFF when searching for a string.      
            When searching for "hello" in a text and SWITCH finds the    
            words "Hello" or "HELLO" they will be recognized and         
            switched if the "c" parameter is specified.  SWITCH by       
            default will assume the search will be case sensitive.       
     Ķ
       v    View Altered Lines                                           
                                                                         
            This option will display each altered line on the screen as  
            it is switched for the user to monitor.  If the number of    
            changes exceeds the number of lines visible on the screen    
            then SWITCH will pause until the user has pressed a key.     
     Ķ
       p    Prompt For File Names                                        
                                                                         
            When a number of files have been specified as targets for a  
            "switch" the user may wish to be prompted for confirmation   
            before each one is altered.  The "p" option does just that.  
            As each file meeting the specified criteria is encountered,  
            SWITCH will request a (y/n) confirmation from the user.      
     Ķ
       w    Whole Words Only                                             
                                                                         
            In some situations you may need to switch a word that could  
            be a subset of a larger word.  To illustrate, suppose you    
            want to change all occurrences of the word "car" to          
            "automobile" in a text.  Without the "w" option the word     
            "card" would be accidentally switched to "automobiled."      
            By default SWITCH will NOT assume that you are switching     
            whole words only.                                            
     Ķ
       s    Search Subdirectories                                      * 
                                                                         
            SWITCH is capable of searching and replacing strings in      
            multiple files at once using wildcards in the target-file    
            parameter.  In addition to this feature, SWITCH provides a   
            means of searching for files outside of the specified (or    
            default) path.  The "s" option will allow the program to     
            search for files in or BENEATH the specified path on the DOS 
            directory tree.                                              
                                                                         
                    C:\DOS                                          
                         DATATEXT                                
                         UTILS   DOCS                                
                                                                         
            In the above directory tree if the following switch command  
            were to be executed: "SWITCH C:\DATA\*.TXT hi hello /s"      
            then all files ending in a ".TXT" in the "\DATA",            
            "\DATA\TEXT" and "\DATA\DOCS" directories would be switched. 
     Ķ
       f    Specify Input File                                         * 
                                                                         
            The "f" option allows for the switching of numerous search   
            and replace strings within the specified file(s) by using    
            an input file containing a list of all of the search and     
            replace strings SWITCH will use.  The syntax for this        
            parameter is "/f:filename" where filename is the name of the 
            input file.                                                  
                                                                         
            Example:  SWITCH *.txt /f:myfile                             
                                                                         
            In this example all ".TXT" files are switched using the      
            criteria found in the file called "MYFILE.TXT."  See the     
            section titled "Input File Format" for details on creating   
            an input file.                                               
     Ķ
       r    Simply displays the registration information for the SWITCH  
            program.  Please register this product.                    * 
     ͼ
                           - Table One: Options -

     * Denotes options not available WITHIN an input file.




Ŀ
 III. Input File Format Ŀ
 
  

    When using an input file to perform multiple switches the following
    conventions must be followed for each line:

          search-string,replace-string,options

    One line for each search and replace string pair must be created.  The
    strings must be separated by a comma and any options to be used in the
    switch must be placed on the same line separated again by a comma. An
    example of an input file might look like this:

            Ŀ
             hello,Hello,cw                                      
             switch,SWITCH,c                                     
             Old,New,cv                                          
             Garbage Man,Waste Disposal Technician,cv            
             Stewardess,Flight Attendant,cv                      
                                                                 
            ڿڿڿ                                         ڿ  ڿ
                              ڿ                   ٳڿ
                       ڿ       ڿڿڿĿڿ    ڿĿڿ 
                    ڿڿڿ ڿ 
                                     
                            - Example One -


    In Example One the five search-strings are replaced by their
    corresponding replace strings using the options particular to each pair.
    Note that phrases containing more than one word ARE valid.  Unlike the
    command-line, multiple word phrases do not need to be surrounded by
    quotes.

    This file may be created with any editor capable of saving to an ASCII
    text file.



Ŀ
 IV. Examples Ŀ
 
  

    The following examples demonstrate just a few ways you might use the
    SWITCH utility.  The first example is a simple application where a field
    in the target file needs to be changed to a user's initials from a
    generic label called simply "initials":


      ڴ No Input File Example Ŀ
                                                                            
       C:\>SWITCH datafile.txt Initials CAC /c /v /w                        
                                                                            
                                   
                                           Optional Parameters       
                                      Target string (what the search  
                                        string will be switched to)     
                                Search string                          
                      Name of the target file to be switched            
             Executes the SWITCH Program                                 
         DOS Command Prompt                                               
                                                                            
      
                            - Example Two -

    This example will switch all occurrences of the string "initials" to "CAC"
    in the file "DATAFILE.TXT."  It will not care if "initials" is capitalized
    in any spot (via the "/c") and it will not switch any word that CONTAINS
    the word "initials" (via the "/w") such as "myinitials."  SWITCH will also
    display each altered line on the screen for the user to view (via the
    "/v" option).

    The next example demonstrates an entirely different way of using SWITCH. 
    In the following example the "/f:" option is used specifying that all
    search and replace pairs will be input from a text file rather than from
    the command-line.

      ڴ Input File Example Ŀ
                                                                            
       C:\>SWITCH \data\*.txt /f:sw-file.txt /s /p                          
                                                                            
                                    
                                            Optional Parameters       
                                  Name of input file containing a list 
                                    of search and replace strings        
                      File specification (files to be switched)         
             Executes the SWITCH Program                                 
         DOS Command Prompt                                               
                                                                            
      
                           - Example Three -

    The above example also makes use of the powerful "/s" option which, in 
    this instance will allow SWITCH to perform on all ".TXT" files in the
    "\DATA" directory and ALL directories that fall beneath it on the
    directory tree.

    The "/p" option in this case will cause SWITCH to pause before each file
    matching the specified description to ask the user if the file should be 
    altered similar as in the following example:

           SWITCH thisfile.txt? (y/n): _

    The computer will halt processing until the user presses either the "y"
    or the "n" key therefore this option is not recommended for batch file
    applications.



Ŀ
 V. Disclaimer Ŀ
 
  

    SWITCH has been tested extensively and has not exhibited any problems
    causing loss of data integrity or otherwise.  This does not mean that
    this product (or any other) is infallible.  You should always keep
    backup copies of any data that is valuable to you.

    Use this software at your own risk.  We can not be responsible for any
    damages due to loss of data, data corruption or other means.



Ŀ
 VI. Registration Ŀ
 
  

    Should you find this software to be useful you are urged to register it.
    Once you have done this you will receive a registration number and proof
    of purchase as well as any future updates to the software as they become
    available.  Register by sending $25 to:

         Craig Cassidy
         58 S. Forge Manor Dr.
         Phoenixville, PA  19460
         
         CompuServe: 72124,1723

    Comments and suggestions are also welcome.


             ۿ ۿ  ۿ ۿ ۿ ۿ ۿ ۿ
              ۳  ۳    ۳ ۳
             ۿ ۳ۿ۳   ۳      ۳   ۳     ۳
             ۳ ۳   ۳      ۳   ۳     ۳
             ۳ ۳ ۿ   ۳   ۿ ۳ ۳
                       
                   V2.1a (c) 1991-1995 by Craig A. Cassidy
