                     4sight.btm  ver. 1.3

      4dos file name completion and file viewer utility
                Copyright Bob Larson  March 93

            4sight is distributed as Freeware.              

INTRODUCTION

     4sight is a combination alias - btm file system that provides an
     alternate to the file name completion service provided by 4dos.

     Features of 4sight include:

     * tcsh - like file name completion.  

     * pop-up window file name completion

     * pop-up file viewer

     * ability to exclude selected files from the above 3 services

     * Uses the path to search for executable files

     4sight.btm must be called by an key alias which first uses ^K to
     save the current command line onto the history stack, for example  

          alias @f7=^K@4sight /w /x^Xr

     where ^K is <control-k> and ^X is <control-x>.  Up to 6 aliases
     may be defined to provide different services.  Note that these
     aliases cannot be created on the command line.  See the "Installation"
     section for information on how to create the needed aliases.

     4sight requires 4dos version 4, and kstack.com must be loaded.

SYNTAX
          4sight [/t /w /v /?] [/x]

          Switches:
               /t  tcsh type file name completion
               /w  pop-up window type file name completion
               /v  file viewer
               /?  display help
               /x  disable exclude files

EXCLUDE FILES

     You may designate files to be excluded using the %exclude environment
     variable, which contains 1 or more file specifications (wildcards 
     permitted) separated by semi-colons or blanks.  Example:

     set exclude=*.bak;*.tmp;

     will cause 4sight to ignore all *.bak and *.tmp files, unless 4sight
     is invoked with the /x switch.  

ACTIONS

     For brevity sake in the following descriptions, the key-aliases used 
     to invoke 4sight will be referred to as "hot-keys", as if it were a 
     tsr program. Specifically, we will refer to the T hot-key, the W hot-key,
     and the V hot-key, representing the key aliases used to invoke the
     3 actions 4sight can take (Tcsh file completion, Window file completion,
     and View file).  In all cases, when 4sight is executed by a hot-key, the
     current command line is erased and replaced with "@4sight /options".  
     I have not found a way to avoid this.


A) tcsh-like file name completion
     
   4sight will take 1 of 3 actions when invoked with the T hot-key, 
   depending on the number of files which can be completed, and 
   whether or not the filename was the only word on the command line.

     If the filename was the only word on the command line, or
     if a path was specified:
	  
     1) If no files or directories can be completed, 4sight will
        beep and restore the command line.

     2) If only 1 file can be completed, it will completed that
        filename. If it is a subdirectory, a trailing \ will be added.

     3) If more than one file and/or directory can be completed, 4sight
        will list all the files, 5 to a row, using the 4dos directory
        colorization scheme if you have configured it.  On the next command
        line it will complete the file name with as many characters as
        are common to all files listed. 

     If the filename was the only word on the command line and no
	  path was specified:

	  4) 4sight will search the directories listed in the %path variable
        for an executable file which matches.  If a file extention was
        specified, it is ignored. It then behaves as in above 3 actions, 
        except that it will list files in the first directory in which 
        a match was found.  Both executable and non-executable files will 
        be listed.

        Example:

        If the directory d:\data contains 3 files (foo1.bar foo2.bar, and
        boo.bar) and you start with the command line:

                  c:\prompt> edit d:\data\fo
     
        Hitting the T hot-key will result in 2 files being listed:

                    foo1.bar foo2.bar
          
                    c:\prompt> edit d:\data\foo

       If you then enter 1 and hit the T hot-key again, the next command
       line will result in the file name being completed (foo1.bar).


B) Pop-up window file name completion

     When invoked with the W hot-key, 4sight will behave much like the
	  tcsh file name completion, with the following exceptions:
     
     1) If more than one file and/or directory can be completed, 4sight
         will list all the files in a pop-up window. In addition to file
         names, the files dates, times and 4dos file descriptions will 
         also be visible.  You can scroll up and select a file.  The
         action taken will depend on the file selected:

          a) If you abort by hitting the escape key, the original 
             command line will be restored.

          b) If a file other than a directory is selected, that file 
             name will be completed on the next command line.
 
          c) If a directory is selected, the window will be refreshed
            with a contents of that directory.  You can thus traverse
            a directory tree to select a file in a directory other
            than where you started. To complete to a directory name,
            select the current directory, i.e., the "." directory, which
            is always the first item in the file list.

C) File viewing

     Invoking 4sight with the V hot-key allows you to easily view
     (using the 4dos internal command "list") one or more text files 
     without losing your current command line. After viewing the 
     file(s) the original command line will be restored. 

     If 0 or 1 file names could be completed, it will take an action 
     similar to the file name completion actions are taken, except that
     the file is listed rather than the name being completed. If no files 
     can be completed 4sight will beep and restore the original command
     line.  If only 1 file can be completed, 4sight will list the file,
     but after exiting list, will restore the original command line.

     If more than 1 file can be completed, 4sight will popup a select
     window and allow you to select 1 or more file to view using list.
     After exiting list, the original command line is restored.


     
INSTALLATION

     Installing 4sight involves copying the file 4sight.btm to a 
     directory accessible by your path variable and defining from 1 
     to 6 aliases used to invoke 4sight.  Also note that 4sight requires
     kstack.com to be loaded.  

     The file 4sight.als contains 6 aliases which can be assigned 
     with the /r option of the alias command:

          alias /r 4sight.als

     You may wish to edit 4sight.als to change the keys the aliases 
     are assigned to.

     Defaults as provided in 4sight.als are:

          @f4=^K@4sight /v^Xr 
          @shift-f4=^K@4sight /v /x^Xr
          @f6=^K@4sight /t^Xr 
          @shift-f6=^K@4sight /t /x^Xr 
          @f7=^K@4sight /w^Xr
          @shift-f7=^K@4sight /w /x^Xr

     Which assigns to the following keys these 4sight modes:

     F4:                 File viewing.
     Shift-F4:           File viewing, disable exclude files.

     F6:                 tcsh file name completion.
     Shift-F6            tcsh file name completion, disable exclude files.

     F7:                 window file name completion.
     Shift-F7            window file name completion, disable exclude files.

     Note that if you view the file 4sight.als, you will not see the ^K or
     ^X, but rather their extended character set representations, i.e.,the
     "male fertility symbol" and an up-arrow, respectively.  Also note that 
     the "@" immediately before "4sight" is essential and without it 4sight
     will not function properly.  This is because the ^K saves the current
     command line to the history stack, which 4sight.btm later retrieves.
     The "@" prevents 4sight from being added to the directory stack and
     assures that the original command line is the last item in the stack
     so that it is easily retrieved.

     The aliases can also be created by redirecting the console to
     a file by issuing the command:

               copy con foo.bar

     Anything then typed will be saved to the file foo.bar, until you signal
     end-of-file with a <control-z><enter>

BUGS, HEADACHES, MISC. NOTES, and SUCH THINGS

     4sight will not operate properly if it is invoked on a command
     line which contains redirection or pipe characters (<>|) or commas.
 
     If the command line contains any environment variables, on the 
     restored command line the environment variables will be expanded.

     If a large exclude list is used and/or many files match the 
     exclude list, 4sight will run somewhat slower.  

     Differences between 4dos's and 4sights file name completion:
     4dos's internal filename completion will only match executable
     files when the filename being completing is at the start
     of the command line.  4sight will match both executable
	  and non-executable file, but will do so in the first 
	  directory of the %path statement in which an executable file
	  is found.
	  
     In addition, 4dos allows you to scroll back on the command
     line and complete a filename.  4 sight always acts on only
     the last word of the comand line.

     4sight uses temporary files created with the %@unique[] function.
     All temporary files are deleted by 4sight unless it is prematurely
     aborted. The temporary files will be located as follows:

         The directory pointed to by the %temp4dos environment variable,
         if it exists.

         The directory pointed to by the %temp environment variable,
         if it exists.

         The current directory.

     4sight may run considerably faster if the temporary files are
     directed to a ram disk by the %temp4dos or %temp variables.

     4sight uses lots of environment variables, but most are unset
     as soon as they are no longer needed.  You should not get
     "out of environment space" errors unless your free environment
     is very small.
     
     Frequent use of 4sight tends to fill up the directory stack.

     About the only fix to some of these problems is to re-write
     4sight as a tsr binary, a project which I am considering 
     undertaking. The choking behavior when redirection characters
     are on the original command line may possibly be solved 
     by running the file containing the directory stack through 
     sed to enclose the offending characters in backquotes, 
     but I haven't tried it yet.

     The file 4sight.btm only contains a minimum of comments.  The
     start and end of each subroutine are identified by comments.
     I felt the file was long enough (> 300 lines).
     My apologies to anyone trying to decipher the logic of the 
     program!
     

HISTORY 

     Version 1.0: Limited release as fnc-win.btm, only provided
     window file name completion.  

     Version 1.01: Fixed some minor bugs with version 1.0

     Version 1.1
         Renamed to 4sight (pretty catchy, wouldn't you say?)
         added tcsh file name completion
         added file viewing ability
         added exclude file ability

		Version 1.2
			Disable aliases
			Altered to override noclobber
			Added check to see if kstack.com is loaded
			fixed minor bugs when matching directories

		Version 1.3
			Figured out proper way to redirect standard error of
            except command, making the subroutine "exclude" unnecessary.
         Added searching the %path for executable files.
		   Streamlined "get_hist" and "build_arg" subroutines
			
COMMUNICATIONS

     I would appreciate hearing about any problems or bugs found
     with 4sight, or any enhancements made to it.  Those with
     internet email access can reach me at 

          blarson@uiuc.edu

     If that address fails sometime in the future, it may be that 
     I have left my current employment, in which case the following 
     address should be used:

          blarson@heartland.bradley.edu

     I can also be reached by snail mail at:

          Bob Larson
          1812 Crescent Dr.
          Champaign, IL 61821
    
