home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / DOS / 4DOS / UTILS / 4SIGHT / 4SIGHT.TXT < prev   
Text File  |  1993-03-04  |  13KB  |  320 lines
  1.                      4sight.btm  ver. 1.3
  2.  
  3.       4dos file name completion and file viewer utility
  4.                 Copyright Bob Larson  March 93
  5.  
  6.             4sight is distributed as Freeware.              
  7.  
  8. INTRODUCTION
  9.  
  10.      4sight is a combination alias - btm file system that provides an
  11.      alternate to the file name completion service provided by 4dos.
  12.  
  13.      Features of 4sight include:
  14.  
  15.      * tcsh - like file name completion.  
  16.  
  17.      * pop-up window file name completion
  18.  
  19.      * pop-up file viewer
  20.  
  21.      * ability to exclude selected files from the above 3 services
  22.  
  23.      * Uses the path to search for executable files
  24.  
  25.      4sight.btm must be called by an key alias which first uses ^K to
  26.      save the current command line onto the history stack, for example  
  27.  
  28.           alias @f7=^K@4sight /w /x^Xr
  29.  
  30.      where ^K is <control-k> and ^X is <control-x>.  Up to 6 aliases
  31.      may be defined to provide different services.  Note that these
  32.      aliases cannot be created on the command line.  See the "Installation"
  33.      section for information on how to create the needed aliases.
  34.  
  35.      4sight requires 4dos version 4, and kstack.com must be loaded.
  36.  
  37. SYNTAX
  38.           4sight [/t /w /v /?] [/x]
  39.  
  40.           Switches:
  41.                /t  tcsh type file name completion
  42.                /w  pop-up window type file name completion
  43.                /v  file viewer
  44.                /?  display help
  45.                /x  disable exclude files
  46.  
  47. EXCLUDE FILES
  48.  
  49.      You may designate files to be excluded using the %exclude environment
  50.      variable, which contains 1 or more file specifications (wildcards 
  51.      permitted) separated by semi-colons or blanks.  Example:
  52.  
  53.      set exclude=*.bak;*.tmp;
  54.  
  55.      will cause 4sight to ignore all *.bak and *.tmp files, unless 4sight
  56.      is invoked with the /x switch.  
  57.  
  58. ACTIONS
  59.  
  60.      For brevity sake in the following descriptions, the key-aliases used 
  61.      to invoke 4sight will be referred to as "hot-keys", as if it were a 
  62.      tsr program. Specifically, we will refer to the T hot-key, the W hot-key,
  63.      and the V hot-key, representing the key aliases used to invoke the
  64.      3 actions 4sight can take (Tcsh file completion, Window file completion,
  65.      and View file).  In all cases, when 4sight is executed by a hot-key, the
  66.      current command line is erased and replaced with "@4sight /options".  
  67.      I have not found a way to avoid this.
  68.  
  69.  
  70. A) tcsh-like file name completion
  71.      
  72.    4sight will take 1 of 3 actions when invoked with the T hot-key, 
  73.    depending on the number of files which can be completed, and 
  74.    whether or not the filename was the only word on the command line.
  75.  
  76.      If the filename was the only word on the command line, or
  77.      if a path was specified:
  78.       
  79.      1) If no files or directories can be completed, 4sight will
  80.         beep and restore the command line.
  81.  
  82.      2) If only 1 file can be completed, it will completed that
  83.         filename. If it is a subdirectory, a trailing \ will be added.
  84.  
  85.      3) If more than one file and/or directory can be completed, 4sight
  86.         will list all the files, 5 to a row, using the 4dos directory
  87.         colorization scheme if you have configured it.  On the next command
  88.         line it will complete the file name with as many characters as
  89.         are common to all files listed. 
  90.  
  91.      If the filename was the only word on the command line and no
  92.       path was specified:
  93.  
  94.       4) 4sight will search the directories listed in the %path variable
  95.         for an executable file which matches.  If a file extention was
  96.         specified, it is ignored. It then behaves as in above 3 actions, 
  97.         except that it will list files in the first directory in which 
  98.         a match was found.  Both executable and non-executable files will 
  99.         be listed.
  100.  
  101.         Example:
  102.  
  103.         If the directory d:\data contains 3 files (foo1.bar foo2.bar, and
  104.         boo.bar) and you start with the command line:
  105.  
  106.                   c:\prompt> edit d:\data\fo
  107.      
  108.         Hitting the T hot-key will result in 2 files being listed:
  109.  
  110.                     foo1.bar foo2.bar
  111.           
  112.                     c:\prompt> edit d:\data\foo
  113.  
  114.        If you then enter 1 and hit the T hot-key again, the next command
  115.        line will result in the file name being completed (foo1.bar).
  116.  
  117.  
  118. B) Pop-up window file name completion
  119.  
  120.      When invoked with the W hot-key, 4sight will behave much like the
  121.       tcsh file name completion, with the following exceptions:
  122.      
  123.      1) If more than one file and/or directory can be completed, 4sight
  124.          will list all the files in a pop-up window. In addition to file
  125.          names, the files dates, times and 4dos file descriptions will 
  126.          also be visible.  You can scroll up and select a file.  The
  127.          action taken will depend on the file selected:
  128.  
  129.           a) If you abort by hitting the escape key, the original 
  130.              command line will be restored.
  131.  
  132.           b) If a file other than a directory is selected, that file 
  133.              name will be completed on the next command line.
  134.  
  135.           c) If a directory is selected, the window will be refreshed
  136.             with a contents of that directory.  You can thus traverse
  137.             a directory tree to select a file in a directory other
  138.             than where you started. To complete to a directory name,
  139.             select the current directory, i.e., the "." directory, which
  140.             is always the first item in the file list.
  141.  
  142. C) File viewing
  143.  
  144.      Invoking 4sight with the V hot-key allows you to easily view
  145.      (using the 4dos internal command "list") one or more text files 
  146.      without losing your current command line. After viewing the 
  147.      file(s) the original command line will be restored. 
  148.  
  149.      If 0 or 1 file names could be completed, it will take an action 
  150.      similar to the file name completion actions are taken, except that
  151.      the file is listed rather than the name being completed. If no files 
  152.      can be completed 4sight will beep and restore the original command
  153.      line.  If only 1 file can be completed, 4sight will list the file,
  154.      but after exiting list, will restore the original command line.
  155.  
  156.      If more than 1 file can be completed, 4sight will popup a select
  157.      window and allow you to select 1 or more file to view using list.
  158.      After exiting list, the original command line is restored.
  159.  
  160.  
  161.      
  162. INSTALLATION
  163.  
  164.      Installing 4sight involves copying the file 4sight.btm to a 
  165.      directory accessible by your path variable and defining from 1 
  166.      to 6 aliases used to invoke 4sight.  Also note that 4sight requires
  167.      kstack.com to be loaded.  
  168.  
  169.      The file 4sight.als contains 6 aliases which can be assigned 
  170.      with the /r option of the alias command:
  171.  
  172.           alias /r 4sight.als
  173.  
  174.      You may wish to edit 4sight.als to change the keys the aliases 
  175.      are assigned to.
  176.  
  177.      Defaults as provided in 4sight.als are:
  178.  
  179.           @f4=^K@4sight /v^Xr 
  180.           @shift-f4=^K@4sight /v /x^Xr
  181.           @f6=^K@4sight /t^Xr 
  182.           @shift-f6=^K@4sight /t /x^Xr 
  183.           @f7=^K@4sight /w^Xr
  184.           @shift-f7=^K@4sight /w /x^Xr
  185.  
  186.      Which assigns to the following keys these 4sight modes:
  187.  
  188.      F4:                 File viewing.
  189.      Shift-F4:           File viewing, disable exclude files.
  190.  
  191.      F6:                 tcsh file name completion.
  192.      Shift-F6            tcsh file name completion, disable exclude files.
  193.  
  194.      F7:                 window file name completion.
  195.      Shift-F7            window file name completion, disable exclude files.
  196.  
  197.      Note that if you view the file 4sight.als, you will not see the ^K or
  198.      ^X, but rather their extended character set representations, i.e.,the
  199.      "male fertility symbol" and an up-arrow, respectively.  Also note that 
  200.      the "@" immediately before "4sight" is essential and without it 4sight
  201.      will not function properly.  This is because the ^K saves the current
  202.      command line to the history stack, which 4sight.btm later retrieves.
  203.      The "@" prevents 4sight from being added to the directory stack and
  204.      assures that the original command line is the last item in the stack
  205.      so that it is easily retrieved.
  206.  
  207.      The aliases can also be created by redirecting the console to
  208.      a file by issuing the command:
  209.  
  210.                copy con foo.bar
  211.  
  212.      Anything then typed will be saved to the file foo.bar, until you signal
  213.      end-of-file with a <control-z><enter>
  214.  
  215. BUGS, HEADACHES, MISC. NOTES, and SUCH THINGS
  216.  
  217.      4sight will not operate properly if it is invoked on a command
  218.      line which contains redirection or pipe characters (<>|) or commas.
  219.  
  220.      If the command line contains any environment variables, on the 
  221.      restored command line the environment variables will be expanded.
  222.  
  223.      If a large exclude list is used and/or many files match the 
  224.      exclude list, 4sight will run somewhat slower.  
  225.  
  226.      Differences between 4dos's and 4sights file name completion:
  227.      4dos's internal filename completion will only match executable
  228.      files when the filename being completing is at the start
  229.      of the command line.  4sight will match both executable
  230.       and non-executable file, but will do so in the first 
  231.       directory of the %path statement in which an executable file
  232.       is found.
  233.       
  234.      In addition, 4dos allows you to scroll back on the command
  235.      line and complete a filename.  4 sight always acts on only
  236.      the last word of the comand line.
  237.  
  238.      4sight uses temporary files created with the %@unique[] function.
  239.      All temporary files are deleted by 4sight unless it is prematurely
  240.      aborted. The temporary files will be located as follows:
  241.  
  242.          The directory pointed to by the %temp4dos environment variable,
  243.          if it exists.
  244.  
  245.          The directory pointed to by the %temp environment variable,
  246.          if it exists.
  247.  
  248.          The current directory.
  249.  
  250.      4sight may run considerably faster if the temporary files are
  251.      directed to a ram disk by the %temp4dos or %temp variables.
  252.  
  253.      4sight uses lots of environment variables, but most are unset
  254.      as soon as they are no longer needed.  You should not get
  255.      "out of environment space" errors unless your free environment
  256.      is very small.
  257.      
  258.      Frequent use of 4sight tends to fill up the directory stack.
  259.  
  260.      About the only fix to some of these problems is to re-write
  261.      4sight as a tsr binary, a project which I am considering 
  262.      undertaking. The choking behavior when redirection characters
  263.      are on the original command line may possibly be solved 
  264.      by running the file containing the directory stack through 
  265.      sed to enclose the offending characters in backquotes, 
  266.      but I haven't tried it yet.
  267.  
  268.      The file 4sight.btm only contains a minimum of comments.  The
  269.      start and end of each subroutine are identified by comments.
  270.      I felt the file was long enough (> 300 lines).
  271.      My apologies to anyone trying to decipher the logic of the 
  272.      program!
  273.      
  274.  
  275. HISTORY 
  276.  
  277.      Version 1.0: Limited release as fnc-win.btm, only provided
  278.      window file name completion.  
  279.  
  280.      Version 1.01: Fixed some minor bugs with version 1.0
  281.  
  282.      Version 1.1
  283.          Renamed to 4sight (pretty catchy, wouldn't you say?)
  284.          added tcsh file name completion
  285.          added file viewing ability
  286.          added exclude file ability
  287.  
  288.         Version 1.2
  289.             Disable aliases
  290.             Altered to override noclobber
  291.             Added check to see if kstack.com is loaded
  292.             fixed minor bugs when matching directories
  293.  
  294.         Version 1.3
  295.             Figured out proper way to redirect standard error of
  296.             except command, making the subroutine "exclude" unnecessary.
  297.          Added searching the %path for executable files.
  298.            Streamlined "get_hist" and "build_arg" subroutines
  299.             
  300. COMMUNICATIONS
  301.  
  302.      I would appreciate hearing about any problems or bugs found
  303.      with 4sight, or any enhancements made to it.  Those with
  304.      internet email access can reach me at 
  305.  
  306.           blarson@uiuc.edu
  307.  
  308.      If that address fails sometime in the future, it may be that 
  309.      I have left my current employment, in which case the following 
  310.      address should be used:
  311.  
  312.           blarson@heartland.bradley.edu
  313.  
  314.      I can also be reached by snail mail at:
  315.  
  316.           Bob Larson
  317.           1812 Crescent Dr.
  318.           Champaign, IL 61821
  319.     
  320.