Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 112.lha / ConMan_v1.1 / ConMan.doc < prev next >

Wrap

Text File | 1986-11-20 | 17.5 KB | 355 lines

======================================================================== ConMan V1.1 Copyright (c) 1987, 1988 by William S. Hawes ======================================================================== ConMan is a replacement console handler that provides line editing and command history for any program that uses CON: windows. It runs under AmigaDOS V1.2 and is completely transparent to other software. After ConMan has been activated, all CON: windows opened by AmigaDOS will automatically use the ConMan handler. This includes command windows opened by NEWCLI as well as any data input/output windows that your program may use. Version 1.1 offers several new features including command searching, word-delete keys, an "undo" buffer, a utility to preload or save the history buffer, and a command to select a keymap. The most surprising new feature, though, is an old feature --- ConMan is still shareware! You've probably noticed that a number of popular shareware programs have "gone commercial" and demand payment in advance; ConMan won't join these, although my future products will be commercial until there is greater public awareness towards shareware. ----- Line Editing ----- ConMan allows you to edit the active (command) line using the left- and right-arrow keys for cursor positioning. The shifted left-arrow key skips to the beginning of the current or previous word, and the shifted right-arrow key skips to the start of the next word. ConMan supports both insert and overstrike editing modes. The CTRL-A key toggles between the two modes, and the CTRL-^ key unconditionally selects insert mode. The default input mode is insert, but you can set the global -o flag to select overstrike mode. The input mode normally reverts to the default mode each time you press RETURN, but the global -s ("sticky") flag will cause the mode to remain set until you change it explicitly. You can select the preferred input mode when you first install ConMan, and can change it at any time using the SetCMan command utility. Try experimenting to see which input mode you like best, but note that these are global flags and therefore apply to ALL ConMan windows. Refer to the paragraph on installation for a list of the global option flags. There are several keys that can be used to delete characters, words, or the entire line. The DEL key deletes the character under the cursor, and the BACKSPACE key deletes the character to the left of the cursor. CTRL-Y deletes from the cursor position to the end of the line, and CTRL-U deletes from the cursor to the start of the line. CTRL-X deletes the entire line, in keeping with the default CON: device. Function keys F7 and F8 can be used to delete words in the backwards and forwards direction, respectively. They work just like the shifted left- and right-arrow keys except that the characters are deleted. CTRL-Z deletes both the current line and any lines that have been typed ahead (but not yet read); this is very handy if you want to completely abandon all typed-ahead lines. CTRL-R provides a less drastic recall by posting the typed-ahead lines back to the command line. The Undo Buffer. If you're editing a line and accidentally hit the up- or down-arrow key, all is not lost. Just press the CTRL-- (control-minus) key and the former line will be posted back to the active line. Only lines that have been changed are added to the undo buffer. Flow Control. CTRL-S and CTRL-Q have been implemented to hold and release the screen output, respectively. While the CTRL-S action is not strictly necessary, since entering any character will halt output to the screen, it is a standard control option. CTRL-W clears the entire window and refreshes the active line. End-of-File. One other control character is recognized: CTRL-\ sends an end-of-file (a zero-length block) to the task reading from the handler. All characters not explicitly required for editing purposes are passed on to the command line. In order to provide a consistent display, characters that might cause interference with the display (like CTRL-L) are displayed as a caret (^) followed by the uppercase alphabetic character. Version 1.1 now supports the CTRL-N (shift-in) and CTRL-O (shift-out) characters. Miscellaneous non-printable characters are displayed as a hash mark. ----- Command History ----- ConMan "remembers" the commands that you type and lets you recall them sequentially using the up- and down-arrow keys. If you go past the line you want, the down-arrow key will retrieve the next (more recent) line. The shifted up-arrow key recalls the oldest line, and shifted down-arrow recalls the most recent line. The CTRL-B key will clear the buffer. The history buffer is organized as a fixed-length memory pool with a default length of 488 bytes. New lines are inserted at one end, and the oldest lines are "pushed off" the other end to make room. The number of lines that can be saved depends on their lengths, but is generally in the range of 25 to 30. The default size can be changed when you install ConMan by using the -b option followed by the desired size in bytes. For example, the command "conman -c -b1000" installs ConMan with a 1000-byte history buffer. ConMan maintains the history in one of two modes. In the default mode, recalled lines are not re-entered into the history buffer unless the line was "touched," and the history index pointer is left positioned at the retrieved line. This mode is convenient if you often go back into the buffer to retrieve sequences of commands. In "true history" mode, every line is re-entered into the history buffer, even if it hasn't been modified after being recalled. The history pointer is always reset (to the most recent line) whenever a line is added to the buffer. The history mode can be selected when ConMan is installed or by using the SetCMan utility. If you prefer to regard the history buffer as a circular buffer rather than a stack, try setting the -wrap option with ConMan or SetCMan. The index will "wrap-around" when it hits the top or bottom of the stack. Release V1.1 of ConMan includes a command called "History" that will save, load, or display the history buffer. Refer to the "history.doc" file for more information. ----- Function Keys ----- There are several additional editing functions and window control features that use the function keys. Key F1 shrinks ("iconifies") the window to its minimum size, and F2 "zooms" the window to its maximum size (usually the entire screen.) Both keys act as "toggles," and shrunken windows may be zoomed (and vice-versa.) If the window was opened without a sizing gadget, neither F1 or F2 will have any effect. Keys F5 and F6 are used to search for commands. If you type a partial command line and then press F6, ConMan searches in the up-arrow direction for a line matching up to the cursor position. You can move the cursor to the right to constrain the search. Key F5 works similarly in the down-arrow direction. Keys F7 and F8 delete words in the backwards and forwards direction. They operate just like the shifted left- and right-arrow keys except that the words are deleted rather than just skipped over. Function key F9 moves the screen to the front or back of the display, and F10 moves the window to the front or back. Both keys act as "toggles" provided that you don't deactivate the window or screen. These keys are useful when you're working with multiple windows or screens and need to peek at the one in back. ----- Window Definitions ----- ConMan accepts the standard AmigaDOS window specifications. For example, "CON:160/50/320/100/MyWindow" specifies a window 320x100 pixels in size, beginning in position (160,50). The numeric parameters are truncated against the maximum screen size, so a larger-than-normal window may be safely specified (for those of you using "morerows"). The default size is the full screen width and height. ConMan sets the minimum window size to allow room for the close gadget and depth gadgets. Various Intuition options and gadgets can be selected by including a list of attributes after the window title. Here's how it works: put another slash ("/") after the window title, and follow it with any of the attribute options listed below. Option Character Default Value ---------------- ------------- A <==> Activate Activated B <==> BackDrop Not a backdrop C <==> Close gadget No close gadget D <==> Depth gadgets Depth gadgets M <==> Move (drag) gadget Drag gadget N <==> NoBorder Border (sorry, "B" was used) R <==> Refresh (SMART/SIMPLE) Smart refresh S <==> Sizing gadget Sizing gadget Z <==> Zero-Zero Not a GZZ Each option character serves to TOGGLE the corresponding window attribute, so if you include an option twice, it will cancel the effect. The closing slash is optional. My apologies to those who wanted a slash in the title. Examples: CON:10/10/300/100/Behind/nb/ a borderless backdrop window. CON:10/10/300/100/Fixed/acm a nonactivated window, with a close gadget, that won't budge. ----- Installation ---- To install ConMan you will need to copy two files to your system disk, but don't worry --- they're both small. Install the file "Conhandler" (184 bytes) in your L: directory, to keep those bigger handlers company. Then copy the file "conhandler.library" (6152 bytes) into your LIBS: directory. If you received ConMan in the form of an ARCed file, first unARC it and then be sure to rename "conlib.lib" and "chandler", or use the provided "ARCinstall" script to copy the files. Once these files have been installed, issue the command "conman -c" to activate the handler. You should only run ConMan once, as it allocates 20 bytes of memory for the handler name string which won't be released. After you've activated ConMan, open a window using NEWCLI and check to to make sure that the new window has line editing and command history. Once every thing is working properly, you should place the "conman -c" command in your startup-sequence so that it's always available. NOTE: ConMan affects only those windows opened AFTER you activate it! It would be very impolite indeed to pull the old handler out from under the existing windows. You can specify several command line arguments with the ConMan command: Code Action ------ ------ -bNNNN select buffer size NNNN bytes -c install as CON: (the default) -o select overstrike mode -r install as RAW: -s select "sticky" mode -t maintain "true history" -w select "wrap-around" history These command options can appear in any order and remain in effect until you reboot the computer. The -q option used in previous releases is now obsolete, as ConMan writes its copyright to standard output by default. A separate utility program called "SetCMan" has been provided to modify or display the global options. You can use SetCMan to change the -o, -s, -t, or -w options at any time. Examples: setcman ? setcman -o -s -t If you usually operate from WorkBench and only occasionally need a CLI, you can activate ConMan by using the icons. First double-click on the "LoadLib" icon to load the conhandler library, and then activate ConMan by double-clicking the "ConMan" icon. The next CLI you open should now have the line editing and command history provided by ConMan. ----- Distribution ----- This program is distributed as shareware (user-supported software) to Amigoid life-forms everywhere! Make sure your friends get a copy. Your contributions are greatly appreciated and will help me maintain ConMan as well as develop new products. Send all correspondence to: William S. Hawes P.O. Box 308 Maynard, MA 01754 (617) 568-8695 My network addresses are BIX: whawes, PLINK: whawes, and CIS: 72230,267. The suggested contribution is $10 (based on an earlier survey), but any amount is welcome. Fewer than 200 people have contributed in the year since ConMan was first released. Although this is actually good by shareware standards, it wouldn't suffice to buy even one full-page ad in (for example) AmigaWorld. Commercial vendors are welcome to include ConMan with their products, provided that it's noted as being shareware and that the documentation accompanies the software. ----- Other Products ----- I have a couple of other products available commercially. ARexx and WShell can be found at better dealers**, or you can order them directly from me at the above address. ARexx is a multitasking implementation of the REXX language, a high-level interpreted language designed for macro-processing. ARexx can be used as the macro language for any software package that includes an ARexx interface. ............................ Only $49.95 (plus $2.00 shipping) WShell is a fully-compatible CLI replacement with aliases, built-in and resident commands, concurrent piping (as in pgm1 | pgm2 | ... | pgmN), extended prompt/window titlebar fields, transparent support for REXX macro programs, and a number of other features. Isn't it time you put some mussel in your command environment? Just 50 clams (+ $2.00 shipping) ** better dealers are those that stock ARexx and WShell. ----- Further Notes ----- ConMan also accepts input specifications in the form "CON:w20480", where the hex digits following the "w" are the absolute address of an Intuition window pointer. This allows you to attach a console handler to an existing window in a multitasking-safe way (unlike the methods that require setting a field in the DOS device list). If you're writing in C, you could use the following sequence to open a window and attach a DOS console to it: window = OpenWindow(&newwindow); /* get a window */ sprintf(buffer,"CON:W%x",window); /* build the name string */ file = Open(buffer,MODE_OLDFILE); /* open a console stream */ You can open a console window on a custom screen by including the hex address of the screen in the specification string, as in "CON:S123abc/10/10/300/100/MyWindow." Other Names. ConMan answers to several names in addition to "CON:". You can define it as the "CNC:" device by appending the included "mountlist" file to your DEVS:mountlist and then issuing the command "mount CNC:". The CNC: device can then be used just like a CON: window. This allows the CON: definition to be left intact, in case there are any incompatibilities between ConMan and your existing software (but please let me know of any problems!) ConMan is also a pipe-handler responding to the name PIP:NNNN, where NNNN is the "capacity" of the pipe. It must be opened using a private packet called ACTION_DOUBLE (value 2000L); the filehandle you get from a call to Open() counts for two and so can be cloned by your program. My WShell command shell uses the ConMan PIP: device as the pipe handler. Keymapping. ConMan supports the Amiga's keymapping facility, which allows you to reassign the editing functions to the keys of your choice. To do this, you must first construct a keymap either in assembly language or with the help of a keymap editor. You can then load the keymap using the SetMap program on your WorkBench disk. By default SetMap makes a keymap global; if you want to use a special keymap from just one CLI, you can use the included KeyMap command to define the desired map. KeyMap with no arguments will display a list of the available keymaps. ----- What Next? ----- Several additional features will be added in the next release of ConMan. A number of people have requested an option to have the handler not display typed-ahead lines, so that the running program can write freely to the screen and lines will be displayed only as they are read. Also in the works is support for an improved "iconify" state, so that the window can be double-clicked to bring it back up to the former size. I'm planning to release a ROM version of ConMan as soon as the hardware vendors start including decoded ROM sockets on their boards. If you're interested in ROM-based software, drop me a note (or write directly to the hardware companies). ----- Bugs ----- All known bugs have been fixed in this release, so you should find it to be very reliable. If you do find a problem, PLEASE report it so I can fix it! There is a warning with regard to the "shrink" and "zoom" keys: rapid toggling between window states will crash the machine. The problem appears to be an interaction between Intuition and the console device and will probably get fixed when Commodore upgrades the console device in version 1.4. Until then, take it easy with the F1/F2 keys. An additional warning: the console device exhibits serious problems with windows below some minimum size. Opening windows of certain sizes (e.g. con:0/0/10/20/) may cause the machine to crash, whether or not ConMan is active. For these reasons, I strongly urge you avoid console windows smaller than 60X25 or so. ----- Acknowledgements ----- Special thanks to John Toebes and the Software Distillery for all the great suggestions, and to the contributors who helped make V1.1 possible. WSH (03/07/88)