L S H LOG SHELL FOR ZCPR3.3 SYSTEMS SUMMARY ----- LSH is a screen oriented command line editing shell. Its interface may be toggled between a normal blank line with system prompt and a full screen text editor. Command lines are saved in an ordinary text file, limited in size by disk capacity. On callup, LSH reads the named log file into the editor, and the user can then enter new command lines or move among ones already in the log. In either screen or line mode, a command line is executed by pressing . LSHINST.COM installs the program default settings and control key bindings. HELPLSH.COM displays a help screen when run from LSH. INVOCATION ------ SYNTAX: LSH [logfile] Install LSH shell using the log file specified. The default type is CMD. If no DIR is specified, the file is searched for in the current DIR, then in LSH's DIR. If the file is not found, and there is no DIR specification, the file is created in LSH's DIR. If no log file is specified, LSH.CMD is the default. [The default name is LSH's current name. If you rename the program to X.COM, the default log file becomes X.CMD.] As LSH is distributed, you can't load a log file with a blank type because LSH will look for a file with the default type. If that is a problem, change the default type to blanks. Examples: LSH Start LSH with LSH.CMD. LSH WORK Use WORK.CMD in current DIR if it exists, else use or create it in LSH's DIR. LSH FOO:WORK Use or create WORK.CMD in FOO: directory. LSH FOO:MY.LOG Open specific file type. SYSTEM REQUIREMENTS ----------- ZCPR 3.3+ with external FCB, shell stack, TCAP. Shell stack entry must be at least 32 bytes (standard). Terminal line wrap must be ON for line mode to work properly. COMMAND SUMMARY ------- The commands which follow are installed with LSHINST. Be sure to run the either the installation program or the help program to see the current control key set. (The default uses WordStar as a starting point.) SHIFT KEYS: The number of available control keys is expanded by using lead-in keys to access some command functions. Four lead-in keys are available. Usage is: . Example: ^KQ (or ^K^Q) Lead-in key #1 (ESC) Lead-in key #2 (^K) Lead-in key #3 (^Q) Lead-in key #4 (^P) The installable functions are listed below along with their initial settings. Those marked with "-" are not installed in LSH's distributed version. EDITING FUNCTIONS: Execution key CR Command line is run Backspace BSP Destructive Char left ^S Non-destructive backspace Char right ^D Line up ^E Go to start of previous line Line down ^X Go to start of next line Word right ^F (Word separator characters may be installed) Word left ^A Line end/start ^J First to line end. If there, to start Line start ^QS Line end ^QD Up screen ^R First to top of screen, then previous screen [Retype Line ^R LINE Mode only]Down screen ^C First to bottom of screen, then next screen First screen ^W Top of file Last screen ^Z End of file. (Quickest way to append to log) Delete char ^G At cursor Delete left DEL Destructive backspace Del word rt ^T Del word lt - Delete line ^Y ... and save to delete buffer Delete to EOL ^QY ... and save to delete buffer Undelete ^U Enter whatever text is in delete buffer Undo changes ^QU Cancel changes to current line Carriage rtn - Usually preempted by the ENTRY key New line ^N Same as in INSERT mode Insert/ovrwrite ^V Toggle text insertion mode Control key - Trigger for control key insertion Clear to EOF ^KZ Zap everything from cursor to end of file QUEUE FUNCTIONS: Keep line to Q ^KB Save current line, advance to next Keep and kill ^KK Save line, delete it, advance to next Insert Q ^KI Insert queue contents at line Insert & clr ^KV Insert queue, then clear it Clear Q ^KY Duplicate line ^B Copy current line SPECIAL FUNCTIONS: Old line srch ^O Look for match to current line up to cursor Search dir ESC O Toggle search direction forward or backward Line sequence ^L Go to line after one last executed Auto seq ESC L Automatic return to next line on reentry Toggle save ESC S Recording on/off Quit shell ESC Q Finished with LSH Mode ESC ESC Full-screen mode / single-line mode Warm boot ESC C Do warm boot if at beginning of line Pause ESC CR Shell pause for key strike before reentry Text lines ESC T Set # text lines for SCREEN mode [Time display " LINE mode, show time in system prompt] Token TAB # Replicate, save tokens 1..9 Mark place ^PZ Line markers are retained in log file Go to mark ^QZ Any number may be set Clear markers ^KH Deletes all place markers Complete Name HOME Match an incomplete file spec to disk files HELP ESC J Run preset command line - HELPLSH.COM COMMAND DETAILS --------- The descriptions below refer to the default command set. ENTRY KEY: The entry key causes the current line to execute as a command. For editing purposes, a ^N will substitute for . (It inserts a at the cursor.) SPECIAL FUNCTIONS: Q - QUIT the shell " ESC - Toggle MODE of operation [full screen or line] " T - Set number of TEXT lines. [ 1 .. screen size ] " CR - Execute line with shell pause " S - Toggle SAVE on/off " L - Toggle LINE sequencing " O - Toggle OLD string search direction " J - HELP screen " C - Warm boot [ ^C not available ] Many functions have no analog in a pure editor. LSH requires commands to stop the shell, initiate a warm boot, pause before shell execution (to look at the screen before it is wiped out), etc. Most of these are assigned to the escape key. SWITCH MODES: LSH operates in two modes. In LINE mode, LSH shows a system prompt pretty much as usual. LSH's presence is not that obvious until you make use of its editing features or recall old lines. In SCREEN mode, a selectable number of command lines appear in a text window at the top of the screen. You have what amounts to a menu of command lines to chose from. Move the cursor to a line, press , and it executes. Screen mode is handy for editing, rearranging, or just viewing the log file. [ The "modes" are actually separate editors. In LINE mode, LSH has no way of finding out where it is on the screen. The only cursor movement commands possible are backspace and advance by re-printing. In FULL SCREEN mode, LSH must know where it is to use GOTOXY. Therefore, it always comes up at the top of the screen. Most of the full screen commands are available in line mode - except queue functions and shell pause.] SET TEXT LINES: T The number of text lines displayed may be set on-the-fly. The installation program also lets you set the default number. I find that 4-5 lines is enough to show me where I am in the log file and what is coming. The display is also crisper when the entire screen doesn't have to be rewritten. The minimum setting is 1 line; the maximum is CRT lines less three. For convenience, you can request some large number like 99, and LSH will set the maximum lines available. In LINE mode, this function has no meaning. LSH uses the same control sequence to toggle display of the system time on the prompt line. SHELL PAUSE: In screen mode, you may want LSH to pause before putting up its display to give you time to inspect console output from the last command before it is overwritten. You can force a shell pause by executing the line with . LSH can also be installed to pause automatically. If the text window is only a few lines in size, there is generally room below the display for console output. LSH clears the lower part of the screen, leaving the command lines showing. When there are many lines in the text window, it makes more sense to clear the screen on command execution, let the command run, pause, clear the screen again, and redisplay the command lines. You can set the decision point. The default setting is 10 lines. If you put it to 0 lines, LSH will always do a shell pause. If you set it to 99 lines, the automatic pause function is disabled. SAVE: ESC S None of the usual ^KX, ^KS, ^KD, ^KL, functions are implemented. LSH has a recording toggle instead. When ON, all changes made are saved to disk. When OFF, any changes to the file are temporary and are lost between invocations. OLD LINE: ^O, ESC O A ^O will search for a match to the current line up to the cursor position. Press ^O again to continue the search. To reverse the search direction, press ESC O. Default is backward. If you are at the start of a line, blank or not, you can type some characters, then search. If a match is found, the characters you just typed are NOT saved. LINE SEQUENCE: ^L, ESC L LSH ordinarily comes up on a blank line at the end of the log. Before running a command line, it stores a pointer to the current line. When LSH runs again, it increments that pointer to the NEXT line. To go right to it, press ^L. ESC L toggles an automatic ^L on entry to the editor. The effect of auto line sequencing is to present the log line by line, "replaying" it. Single-line and full-screen modes use independent auto sequence flags. The default is auto ON for full-screen, auto OFF for single-line. [ If the log has been changed with the SAVE state off or with an independent editor, the pointer may not give you the line you expected. ] PLACE MARKER: ^PZ, ^QZ, ^KH An unlimited number of line markers may be set. They are maintained between invocations of LSH. ^PZ sets a marker to the current line. ^QZ goes to the next marker in reverse direction through the file, wrapping to the end of the text. ^KH clears all the markers. [ In order to guarantee that the markers stay with the right line when text is added or deleted, it was necessary to set the high bit of the character at the start of the line, rather than using pointers. That can cause trouble when a text editor which sets high bits for its own purposes is used on the history file. The clear command will reset all high bits in the file. ] UNDO: ^QU While a line is being edited, it is held in a line buffer. UNDO cancels any changes to the current line by reloading the line buffer from the body of the text. Once you move off the line or delete it, the line buffer is loaded back into the text and UNDO has no effect. Use this command if you want to start over or to delete a search string (for ^O command) typed in at the start of the line when the search is unsuccessful. UNDELETE: ^U A line deletion or delete to end of line saves the text to a delete buffer. The buffer's contents may be entered at the cursor with ^U. This function can immediately recover from an accidental deletion, or can be used to move deleted text somewhere else. Note that the buffer is entered on the line according to the setting of the insert/overwrite toggle. CONTROL CHAR: - If you need to put control characters directly into the command line, use the installation program to assign this function to a key. (It is disabled as LSH is distributed.) CAUTION - since ^Z is the end of file marker for text files, you truncate the log by inserting it. (Use ECHO ^Z.) COMPLETE: HOME This idea is taken directly from EASE and works the same way. The cursor is assumed to be at the end of an incomplete file specification, e.g. ROOT:Z. The Complete command finds successive matches from the disk and displays one with each press of the HOME key. This does not work properly if a file type is present: the command simply appends *.* to the filename as given. When changing the default key binding for this command, be sure to assign it to a single control key. LSH must know if you just executed this command so it knows it has to continue looking. LSH's control key parser can't do that for two-key commands. HELP: ESC J HELPLSH is a tool which generates a screen showing LSH's current command key set. ESC J runs an internally stored command line which has been set to HELPLSH. Be sure that HELPLSH.COM is somewhere on the path so that the command processor can find it or else just install a DIR reference. When (or if) you don't want the help screen, you can install some other command line to be run by this function. One possibility would be an ARUNZ alias which could easily be changed as desired without reinstalling the command line in LSH. I use ZFILER a lot, and have installed the line to run that. ADVANCED FEATURES ----------------- LSH has a few features which are idiosyncratic. They can be quite useful to heavy users, but you needn't remember them to get productive use from the program. MOVING TEXT: LSH uses a queue rather than block move functions to re- organize the history file. ^KB - Keep line to queue, advance to next ^KK - Keep and Kill line, advance to next ^KV - Insert queue contents, then clear the queue ^KI - Insert queue contents, leave queue alone ^KY - Clear the queue ^B - Duplicate line A queue picks up command lines as you mark them, then deposits them where you like. (First in, first out.) That is just what we are most likely to do in this application. If you have ever suffered the tedium of re-ordering a list with the usual block functions, you will appreciate an alternate way to do it. (Or, if you don't appreciate it, the log file is available to your text editor.) Note that ^KK adds the line to the queue then deletes it, leaving the cursor at the start of the next line. Sitting on the ^K key sucks lines up. Do not use ^KB and ^KK as a pair. Duplicate Line combines several Q-functions into one keystroke. It is equivalent to ^KY ^KB ^KV ^KY, i.e. clear Q, pick up line, copy line, clear Q again. This is the way to rapidly produce copies of a template or prototype line. Another intended use is to re-execute a command line with "GO" substituted for the first token. The installation program allows a flag to be set which causes this substitution to occur automatically. For example: original line --> ROOT:CRUNCH XX*.Z80 BACKUP: ^B and edit --> GO XX*.INC BACKUP: TOKEN REPEAT: TAB n There are two "advanced features" for moving text which also use the delete buffer. 1) Token Repeat saves the token # (1 - 9) you have selected into the buffer, then enters it at the cursor. Its purpose is to save typing. (This is Rick Charnes' idea, and he loves it.) While playing with this command, you can cancel any mistakes with UNDO. For example zde myprogrm.z80;z80asm TAB2;TAB2 generates the line: zde myprogrm.z80;z80asm myprogrm;myprogrm Since token repeat uses the delete buffer, the second TAB2 in the example could just as well have been a ^U. 2) TAB TAB yanks the current line from the cursor position into the delete buffer. It loads the buffer with the same text which delete-to-end-of-line would delete. The buffer contents can be entered later with UNDELETE (^U). This can be used to store a string you intend to use several times when building a series of command lines. ERROR MESSAGES -------- LOG OVFL - There is not enough TPA to hold the log file. Solution: change the default READ RECS to something smaller. If the TPA is nearly full and you enter a lot of text, LSH will eventually stop accepting input. If your system has a very small TPA, use the Type4 version of LSH. (The Type3 version is preferred because it loads faster and has no preset limit on the amount of new text which may be entered on each invocation.) STACK FULL - The shell stack is either non-existent or full. In the latter case, pop something off the stack, then try again. LOG? - The log file in use can't be found (erased, disk changed). NAME? - The log file specification must be unambiguous. TCAP? - The editor couldn't find needed support in your TCAP entry. Are you sure it is loaded? One condition that LSH does NOT complain about is a text line that is not a command line: comments, titles, etc. To insure that the command processor doesn't try to run them, start them with ";" or with NOTE. With that caveat, it can be useful to keep notes in the history file. INSTALLATION PROGRAM ---------------- LSH comes with an installation program to make it easy to alter its command key set and default configuration. Actually, it would be almost impossible to do so with a patcher because of the system used to encode the command keys. To run the installation, type LSHINST [lsh]. The [] enclose a default file name which you can alter with a DIR reference or another file name to install. A menu comes up with three areas of installation - Defaults, Editor, and Terminal. LSHINST contains several information screens which describe the installation in detail. Please note that no installation is required before using the program. COPYRIGHT NOTICE -------- LSH, its documentation, and its installation program is Copyright (C) 1989, 1990 by Robert Friefeld. All rights are reserved. Any duplication for commercial use requires the advance written permission of the author. Rob Friefeld 4607 Colorado Street Long Beach, CA 90814 February 23, 1989