LSH, Version 1.10 Documentation August 25, 1991 L S H LOG SHELL FOR ZCPR3.3 SYSTEMS SUMMARY ----- LSH is a screen oriented command line editing shell which works like a text editor. Command lines are stored in an ordinary text file. On callup, LSH reads in the log file, then the user enters new command lines or moves among ones already in the log. Pressing runs the command line the cursor is on. The editor operates in Line Mode, which simulates the normal CP/M system prompt, or in full screen mode. LSHINST.COM installs the program default settings and control key bindings. HELPLSH.COM is a separate help screen utility run from within LSH. 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. INVOCATION ------ SYNTAX: LSH [dir:][logfile] [/C] Start LSH shell using the log file specified. The default type is VAR. 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.VAR 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.VAR.] 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.VAR. LSH WORK Use WORK.VAR in current DIR if it exists, else use or create it in LSH's DIR. LSH FOO:WORK Use or create WORK.VAR in FOO: directory. LSH FOO:MY.LOG Open specific file type. The command line option "/C" causes LSH to be invoked for a single run; it is not installed as a shell. This feature is a convenience when you just want to dig a command line out of the history. 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. 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. 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 Delete Command - Delete from cursor to char after next ";" Undelete ^U Enter whatever text is in delete buffer Undo changes ^QU Cancel changes to current line 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 to Q, 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 search ^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. Shell Pause ESC CR Run line and pause 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 token 1..9 Mark place ^PZ Set line marker Go to mark ^QZ (Any number may be set) Clear markers ^KH Deletes all line markers Complete Name HOME Match an incomplete file spec to disk files HELP ESC J Run preset command line - HELPLSH.COM User Patch ESC U Run user installed patch code 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 in ZCPR's multiple command line buffer. 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 in screen mode ] 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 which share a command key list. 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.] 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 go to the maximum lines available by just requesting some large number, like 99. In LINE mode, this function has no meaning. LSH uses T 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 log. You can set the decision point. The default setting is 10 lines. If you set 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 line beginning with the same characters as the current line up to the cursor position. Press ^O again to continue the search. To reverse the search direction, press ESC O. Default direction is backward. Console beep mean no match was found. 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. Line Sequence can be configured to return to the last command line run, rather than the one after it. That is, it would always return you to the same place in the log. [ 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 wanted.] 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 Marker 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 again after messing up the current line. For example, if you have typed a search string (for ^O command) and the search is unsuccessful, ^QU will get rid of the string for you. 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.) The CP/M printer toggle, ^P, does not work as a control character embedded in a command line. It only works when the BDOS is able to intercept it as characters are received via function #2. Editors do not get their input this way. COMPLETE COMMAND: 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. Complete finds successive matches from the disk and displays one with each press of the HOME key. When there are no more matches, you get a console beep. When complete is used at the first token on the line, it is assumed that only .COM file matches are wanted. Each match is displayed without the .COM type but with a space appended so you can go ahead and enter the command arguments immediately. If no DU is specified, the .COM search follows the path. Examples: edit *.ws edit foofile.ws edit poopile.ws u umap uncrunch *.* If the command line begins with "." or ":", the current DU is searched first, then the path is followed. If the command parser is overwhelmed by your efforts, you get a . File names are returned in their order on disk. 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. 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. SPECIAL FEATURES ----------------- LSH has a few features which go beyond basic needs. They can be quite useful to heavy users, but you don't need to remember them. MOVING TEXT: LSH uses a queue for reorganizing 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 one by one, 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 can be edited with 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, 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 --> 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. (See above: Delete Line, Delete to EOL) 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. While playing with this command, you can cancel any mistakes with UNDO (^QU). For example: zde myprogrm.z80;z80asm TAB2;TAB2 generates the line: zde myprogrm.z80;z80asm myprogrm;myprogrm 2) TAB TAB yanks the current line, from the cursor position, into the delete buffer without doing the deletion. The buffer content can be recovered later with UNDELETE (^U). USER PATCH: ESC U A small user's routine can be installed in a 32 byte patch area. The code there is run when the User Patch key is pressed. All registers are available; end with a RET. One use is a system specific patch to turn the printer on and off. The usual CP/M ^P printer toggle does not work because the editor does not input characters via BDOS function 2, so the BDOS never gets a chance to trap ^P. Embedding ^P in a command line does not work either. Code can be assembled to an object file and overlayed on LSH with BCOMP. The patch area is denoted by "USR> ..