Hindsite.btm version 1.0 copyright Bob Larson blarson@uiuc.edu 20 December 1993 INDEX OVERVIEW REQUIREMENTS INSTALLATION copying files configuring cache-c.btm configuring hs.btm alias definitions USING HINDSITE Refreshing the cache Command completion History recall BUGS, WARNINGS, and LIMITATIONS ACKNOWLEDGEMENTS COMMUNICATIONS OVERVIEW Hindsite is pair of 4dos (c) batch files which provide several useful functions, including: * Command completion. Enter a partial command name on the command line, and hindsite will display a window with commands which the partial name could complete to. This includes internal commands, aliases, and external programs. 4dos extended wildcards are fully supported. Scroll through the window, select the command you want, and you will be returned to the command line with the completed command. * Command correction. Misspell a command, and instead of receiving a "Unknown command" response, hindsite will display a window of command names to select from. Select the correct command, and you will be returned to the command line with all arguments intact. * Hindsite also provides for csh-type history recall. Entering "!!" on the command line will recall the last command, and entering "!xyz" will recall the last command which started with "xyz". Other forms of command recall available in csh are not currently implemented in hindsite. Hindsite consists of two 4dos .btm programs: cache-c.btm: Creates a cache file of the names of internal commands, alias, and executable files in directories accessible by the path environment variable. The names of files with executable extensions can optionally be included in the cache. Keystroke aliases are not included in the cache, and the set of internal commands to be included in the cache is user defined. hs.btm: Invoked by the unknown_cmd alias introduced with version 5.0 of 4dos. It is a batch file which is only executed when an attempt is made to execute a command which 4dos is unable to run. When a correct command is executed, hindsite is not executed at all. When executed hs.btm will attempt to match the command name with those listed in the cache file and/or files in the current or specified directory. REQUIREMENTS * 4dos version 5.0 or greater * Kstack.com, the 4dos keystack stuffing program, must be loaded into memory. * One of a variety of grep programs is required by Hindsite. Grep is a program similar to the find.com, but more powerful. Several grep programs are readily available, some of which are free. Grep and egrep have been tested and verified to work. Fgrep and sgrep will not work without modification of hs.btm * An included companion program, cache-c.btm must first be executed before hindsite is operated. Cache-c.btm creates a cache file containing command, alias and external program names which hindsite uses. * Cache-c.btm requires a sorting program. This can either be the sort program distributed with ms-dos, or preferably, a sort program which has the ability to remove copies of duplicate lines. An example of such a program is a port of the unix sort program. * For those with Internet access, all of the required programs are available from Simtel mirror sites, in the msdos/gnuish directory as well as the msdos/textutil directory. INSTALLATION Several steps are required to install hindsite, including defining aliases and configuring both hs.btm and cache-c.btm so they can find required or optional external programs. Configuring hs.btm and cache-c.btm is done by setting environment variables within the batch files. Most variables are used to point to external programs; these must point to the program itself, and NOT TO AN ALIAS! Within these batch files aliases are temporarily disabled. Please follow the instructions below. Copying Files Copy cache-c.btm and hs.btm to a directory included in your path variable. Both programs use one environment variable, %cmd_list, which contains the path and name of the cache file. %cmd_list can be set by one of three methods: 1) Use the set command prior to use of cache-c.btm or hs.btm. The set command can be issued from the command line or can be placed in autoexec.bat or 4start.bat. 2) Specify the name of the cache file on the cache-c.btm command line: cache-c e:\cmd.lst Cache-c.btm will then set the value of the %cmd_list variable. If both methods 1) and 2) are used, option 2) will take precedence. 3) If neither option 1) or 2) are used, cache-c.btm will create a file unique file and set %cmd_list on it's own. The file will be placed in the directory pointed to by the %temp variable if it is set, or in the current directory otherwise. Configuring cache-c.btm Cache-c.btm must be configured so that it will know if external programs are to be used. Near the beginning of hs.btm is a subroutine "config", where all options are selected. There are four environment variables set in config, which the user can change the value of as follows: Variable: _sort_prog Default: _sort_prog=sort _sort_prog holds the path and name of the program used to sort the command cache. You can also specify options as required. For example, to use the unix sort program in the directory tools on drive c:, specify that the sorting should be case-insensitive, and that copies of duplicate lines be removed, change the variable to read: set _sort_prog=c:\tools\sort -f -u If you opt to use the sort program supplied with ms-dos, no options are needed. Just make sure you set the next variable, _sort_unique, to "y". Variable: _sort_unique Default: _sort_unique=y If _sort_unique holds the value "y" or "Y", a subroutine in cache-c.btm will be used to remove duplicate entries in the command cache. If set to any other value, cache-c.btm will assume that this has already been done by the sorting program. Having this done by the sorting program is highly recommended, as the subroutine in cache-c.btm is very slow. Variable: _sed_prog Default: not set, commented out by "REM" Set this variable to the path and name of the stream editor program sed.exe, if you have it. In the default condition, a subroutine in cache-c.btm will edit the alias names to make them suitable for the command cache. Again, sed works much faster and is recommended. Variable: exes Default: exes=*.com;*.exe;*.bat;*.btm; exes contains the extensions of files which will be included in the cache when cache-c.btm searches all directories in the path variable. Internal Commands: At the very end of cache-c.btm is a list of 4dos internal commands which will be added to the cache. This list may be added to or deleted from as desired. Configuring hs.btm hs.btm requires one environment variable, which specifies the name and location of the grep program. It is located in the main routine near the start of the file. Variable: _grep_prog Default: _grep_prog=grep You can change this to specify the location and options of the grep program you use. To use the gnuish egrep in directory tools on drive c, with the option to make the search case insensitive, change it to: set _grep_prog=c:\tools\egrep -i Alias definitions Hs.btm is invoked by the unknown command alias. Before defining this alias, please be sure that the necessary modifications to cache-c.btm and hs.btm have been made, and that cache-c has been executed so that a cache file exists. Define the unknown_cmd carefully; if it can not find hs.btm, it will enter an infinite loop and cause a stack overflow error. The following is the format I suggest for the unknown_cmd alias (but entered on one line): alias `unknown_cmd=iff %_batch == 0 then^c:\hs^else^echo Unknown command` With this alias defined, hs.btm will be invoked whenever 4dos is unable to find a command, alias, or external program, unless the error occurred from within a batch file. 4dos will automatically pass the bad command line to hs.btm. You may optionally define other aliases for invoking hs.btm. For command completion, I find the following key alias to be useful: alias @@f5=** This will invoke hs.btm with whatever was on the command line, even if the command line was empty. It is also handy if you want to complete a command, but the part you have typed is another command e.g., you want to complete the command dirsort, and have only typed in "dir". Users can define other aliases to invoke hs.btm, as long as they pass the command and it's arguments (if any) to hs. USE OF HINDSITE Refreshing the cache: If you use hindsite on a regular basis you will probably want to put cache-c.btm in your autoexec.bat file. Unless it is the last command, make sure you use the "CALL" command to execute it, or the rest of autoexec.bat will not be executed. Cache-c.btm can be rerun at anytime to update the cache file to account for changes in the path variable or if you add or delete aliases. At present the only option is to completely recreate the cache file. If the recommended sed and sort programs are used, however, this is not a very time consuming operation. Whenever the cache file is refreshed it is unnecessary to explicitly define the location of the cache file; it will already be set in the %cmd_list environment variable. Command completion: Two different pop up windows are used by hindsite. The circumstances which cause each window to appear are described below. One window contains command names (internal, alias, and programs on the path) from the cache file, and will have the title "Commands". The commands in this window are sorted alphabetically. It is possible to distinguish what type each command is. External command will be lower-case and have extensions, aliases will be lower-case and not have extensions, and internal commands will be upper-case and not have extensions. The other window is the file completion window. It is the same window which is displayed when you hot the F7 key, and is titled "Files". Which window pops up depends on the command line hindsite is given, where it finds matches, and how many matches it finds. The following list the how hindsite will act under different situations: 1) Command completion when no path is specified: In this case hs.btm will attempt to match the command line with commands listed in the cache file. 4dos wildcards are fully supported. If an extension is specified, only names with the extension will match, and no aliases and internal commands will match. The actions taken by hindsite depend on the number of matches: 0 match: Exit, restore the original command line, position the cursor in the "home position" on the command line, and invoke the 4dos filename completion window (normally f7). 1 match: Return the completed filename. >1 match:Pop-up the command window with matching commands. The user can select the desired command, which will exit and return the user to the modified command line. If the user does not select a command, hindsite will act as if no commands match (i.e., pop up the filename completion window). 2) Command completion when a path is specified: Hindsite will assume the intended command is an external program in the specified directory. It will exit and pop- up the filename completion window. History recall: Two forms of history recall are implemented. "!!" will recall the last command, and !!search_string will recall the last command which matches the search_string. Any arguments following !! or !search_string will be added to the end of the recalled command. For history recall hindsite will use the history log file if available, otherwise it will dump the history stack to a file and read that. Use of the history log should be quicker, but how much so will vary from system to system. Note that unless you have a "histcopy = Y" directive in your 4dos.in file, the last command in the history stack which matches search_string may not be the most recent one executed. BUGS, WARNINGS and LIMITATIONS Hindsite will not act properly if it tries to complete a command when there is a redirection or piping symbol on the command line. 4dos handles these before passing the command line to hs.btm. Even if hindsite completes the command, the pipe or redirection will have already failed. Environment variables on the original command line will be expanded after command completion. A different situation occurs with aliases. Preceding a command with a "*" to prevent alias expansion doesn't work with hindsite. In the current version the "*" is interpreted as a wildcard. ACKNOWLEDGEMENTS Robert Chung (chung@qal.berkeley.edu) originated the idea of using a disk-based command cache. Peter T. Breuer (ptb@dit.upm.es) tested an early version and providing useful feedback. COMMUNICATIONS I would appreciate receiving any feedback, bug reports, wish lists etc. The address blarson@uiuc.edu should be good at least through mid-1995. After that, blarson@prairienet.org might be a better bet. Oh, and BTW, hindsite version 1.0 is freeware.