OS/2 Professional

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

/ OS/2 Professional / OS2PRO194.ISO / os2 / fileutil / list / list3 / lst.doc next >

Wrap

Text File | 1989-09-13 | 27.5 KB | 581 lines

LST: A File Viewing Utility for OS/2 Protected Mode Version 1.02 13 September 1989 (c) Copyright Brady Flowers, 1989 All rights reserved I. Restrictions LST is supplied for personal, private use. Feel free to distribute LST given these restrictions: - the program shall be supplied in its original, unmodified form, which includes this documentation; - no fee is charged; - use for profit without a license is prohibited; - the program may not be included or bundled with other goods or services. Exceptions may be granted upon written request only. If you are using LST and find it of value, your gift in any amount ($15 suggested) will be greatly appreciated. Please make checks payable in U.S. dollars to Brady R. Flowers. Canadian and non-U.S. checks are not acceptable. For use by corporations and other institutions, please contact the author for a licensing arrangement. II. System Requirements LST is written for the IBM PC/AT, IBM PS/2, or any compatible computer that can run MS OS/2 or IBM OS/2. LST will run in OS/2 Protected Mode only and may be run from either a full screen OS/2 session or on a Presentation Manager VIO window. III. Using LST A. The Command Line Command line syntax for LST is as follows: LST [options] filespec [filespec ...] where: "filespec" is a valid OS/2 file name or ambiguous file spec. Examples are "lst.doc" or "c:\usr\*.txt". "options" is a string which begins with the character "-" followed by any of the following (in either upper or lower case): "h" forces the first file to be loaded in Hex Mode. The display mode, Hex or Text, may be altered from within LST also with the restriction that certain files are always displayed in Hex Mode (see discussion below). If this option if omitted, it defaults to Text Mode (with the exceptions noted below). "s" causes the first file loaded to be read from standard input rather than from disk. Other files may be given on the command line and subsequently displayed however the "stdin" file is not viewable in hex mode and the presence of the "s" option will negate any occurrence of the "h" option on the command line. "m" followed by any non-negative decimal number, allows you | to set the behavior of the mouse. If the number is | zero, the mouse handler operates in "polled" mode | which is bad as far as CPU usage goes but allows for | you to easily use both the mouse and the keyboard | interchangeably (this is the default setting). If the | number is one, the mouse is not polled but key strokes | from the keyboard will not be received in a timely | manner (actually this setting is just there for my | own debugging purposes). If the number is greater than | one, the mouse is completely disabled and all commands | must come from the keyboard. | | "z" followed by any non-negative decimal number, sets the | number of milliseconds LST yields to the CPU between | keystrokes and mouse events. If running LST seems to | be slowing other tasks running on your system down, | try setting this to a higher value. The default value | is two. | "t" followed by any non-negative decimal number, sets the tab expansion to that value. If the number is zero, tabs are not expanded and tab characters will be displayed on screen. In the current version of LST, this value is only alterable by the command line. If this option if omitted, it defaults to 2. "l" followed by any positive decimal number, sets the number screen rows to that value. LST will attempt to reset the video state to that number of rows. If the video mode cannot be reset appropriately, LST defaults to the current screen mode. In the current version of LST, this value is only alterable by the command line. If this option if omitted, it defaults to 43. "c" followed by any positive decimal number, sets the number screen columns to that value. LST will attempt to reset the video state to that number of columns. If the video mode cannot be reset appropriately, LST defaults to the current screen mode. In the current version of LST, this value is only alterable by the command line. If this option if omitted, it defaults to 80. "a" followed by nine hexadecimal bytes (eighteen characters from the set "0123456789abcdef") which specify the screen attributes for the following sections of LST's screen: Screen Area Default Color =================== ======= ============= Main Screen 03 Cyan on Black Main Screen Hilight 0b Bright Cyan on Black Menu and Menu Items 4e Yellow on Red Selected Menu Items 4f Bright White on Black Disabled Menu Items 43 Cyan on Red Status Line Message 0b Bright Cyan on Black Error Messages 0e Yellow on Black Scroll Bars 60 Black on Brown Modeless Dialog Boxes 31 Blue on Cyan If this option is absent, values default according to the above table. If it is present, it must either contain all eighteen bytes or must be the last option in the list. If an attribute is to retain its default value, any character other than a Hex digit may be used as a place holder. Examples: 1) Force Hex mode and 25 line display: LST -hl25 filespec 2) Tab stops at multiples of 8 columns and change Main screen to Yellow on Blue: LST -ta1e filespec 3) Change error to blinking Yellow on Black leaving everything else default: LST -a............8e filespec 4) Read the first display from the output of a program called ARC2 and subsequently display all files matching *.c in the current directory: ARC2 v foo.arc | LST -s *.c 5) Disable the mouse handler and increase the yield time between | keystrokes to 5 milliseconds: | LST -m3z5 filespec | Note: Options need not be the first thing on the command line, they may be interspersed with the filespecs and any given option may appear more than once, the last appearance of said option will define it's value. Note: See "The LST Environment Variable" below for a discussion on how to semipermanently set these options. B. The Menus LST uses a menu interface very similar to that found in OS/2 Presentation Manager applications or in Microsoft Windows applications. There is a menu bar across the top of the screen containing the following items: "File" "Search" "Options" "F1=Help" each of which may be activated by either clicking on the word with the mouse pointer or be typing Alt-F, Alt-S, Alt-O, or F1. The first three activate pulldown menus while "Help" actives a dialog box containing infor- mation concerning available keystrokes. While the menu is active, you may move from item to item using the left and right arrow keys or by clicking on another item. Typing the ESCape key removes any pulldown menu but leaves the menu active, typing it again deactivates the menu and returns you to file viewing mode. Clicking the mouse anywhere but on a menu will also return you to file viewing mode. While a pulldown menu is active, you may move the hilight on the pulldown using the up and down arrows. Typing the ENTER key selects or activate the hilit item. Typing the first letter of any item actives that item (if there is more than on item with the same first letter, the first such item is selected). Alternately, you may click the mouse pointer on any item to select it. The results of selecting any item on a pulldown menu are outlined below: "File" Menu "Open..." a dialog box appears and prompts you to enter a new file name. The edit field contains a default value (usually the current file name) which may be edited using the left and right arrow keys, the Home and End keys, and the Delete key or by clicking the mouse pointer within the edit field. The filename may be any valid OS/2 filespec, wildcards accepted. Type ENTER to direct LST to read the file or files adding it or them to the Pick List (see discussing of Pick List below) after the current file, or type ESCape or click the mouse pointer anywhere outside of the dialog box to abort the command. "Info" a dialog box appears containing the following infor- mation: The name of the current file, the time and date of its creation or last modification, and the file size in bytes. Type any key or click the mouse pointer anywhere to remove this dialog box. "Prev File" reload the previous file in the Pick List (see discussion on the Pick List below). This item will be disabled if the current file is the first item (or only item) on the Pick List. "Next File" reload the next file in the Pick List (see discussion on the Pick List below). This item will be disabled if the current file is the last item (or only item) on the Pick List. "Pick List" displays a dialog box containing the current Pick List (see discussion on the Pick List below). The current file is hilighted. The hilight may be moved using the up and down arrow or by clicking the mouse pointer on the dialog boxes scroll bar. Select a filename from this list by typing the ENTER key while the filename is hilit or by clicking the mouse pointer on the name. The indicated file is the reloaded into LST. Abort the Pick List command by typing ESCape or by clicking the mouse pointer anywhere outside of the dialog box. "About Lst" displays a dialog box the name of the program (LST), its author, and a copyright notice. Type any key or click the mouse pointer anywhere to remove this dialog box. "Exit" unconditionally exit LST, restoring the original screen mode and contents. "Search" Menu "Exact Match" a dialog box appears and prompts for a search pattern. The default value that appears may be edited using the left and right arrow keys, Home, End, and Delete keys. Type ENTER to begin a search in the current search direction (see Search Fwd/Back below) for a string that exactly matches the pattern. If found, the line is displayed center screen in the screen hilight color, else a "Pattern not found" error message is displayed. Abort the dialog box by typing ESCape or by clicking the mouse pointer anywhere outside of the dialog box. "Ignore Case" behaves in the same manner as "Exact Match" above except that the pattern will match any text that differs only by upper or lower case, i.e., "Abc" matches pattern "ABC". "Grep" mechanically behaves the same as "Exact Match" and "Ignore Case" above except that the search is based on what is know as a "regular expression." See the discus- sion on regular expressions below. "Next" repeat the last search in a forward direction using the same pattern and search method (Exact, Ignore Case, or Grep). "Previous" repeat the last search in a backward direction using the same pattern and search method (Exact, Ignore Case, or Grep). "Search Back" reverse the default direction for searches. After selected this option, the menu item becomes "Search Fwd" and will toggle between the two. "Search Fwd" see "Search Back" above. "Options" Menu "Hex Mode" causes the current file to be reread and displayed in Hex Mode. If the current file already is in Hex Mode, this item will be displayed "Text Mode" and selecting it will cause the file to be reread and displayed in Text Mode. "Text Mode" see "Hex Mode" above. C. Viewing the File General: While viewing the file, the following methods are available for navi- gating your way around the file: Keyboard: Up Arrow Move the display up one line in the file Down Arrow Move the display down one line in the file PgUp Key Move the display up one page in the file PgDn Key Move the display down one page in the file Home Key Move the display to the top of the file End Key Move the display to the end of the file Right Arrow Move the display right five columns Left Arrow Move the display left five columns Control-Left Arrow Move the display to column one. Note: there are other keystrokes that duplicate most of these functions. See discussion on Accelerators and Aliases below. Mouse: Vertical movement: Clicking the mouse pointer on the up or down arrow of the vertical scroll bar moves the display up or down by one line respectively. Click the mouse pointer on the scroll bar itself moves the display up by one page if the mouse pointer is above the scroll bar "thumb", or down by one page if the mouse pointer is below or on the "thumb". Horizontal movement: Clicking the mouse pointer on the left arrow of the horizontal scroll bar or on the scroll bar itself to the left of the "thumb" moves the display five columns to the left. Clicking the mouse pointer on the right arrow or on the scroll bar to the right of or on the "thumb" moves the display five columns to the right. Note: A "page" is defined to be the number of lines in the current file viewing window (three less than the number of screen lines). Text Mode: This is the default viewing mode for most files. The file appears on screen in much the same manner as it would in a text editor. If the Tab Stop setting (see discussion on command line options above) is greater than zero, tabs are expanded so that tab stops fall on columns which are multiples of that value (i.e., if tabs are set to 2, the default, tab stops are at columns 3, 5, 7, etc.); no other text filtering is done. Certain files will not look well presented in text mode and may not read in correctly. Binary files will not, in general, be read correctly in this mode. Thus files with any of the following extensions will automatically put LST into Hex Mode (see below): ".COM", ".EXE", ".OBJ", ".BIN", ".DEV", ".LIB", ".DLL", ".ARC", ".PKA", and cannot be viewed in Text Mode (unless of course they are renamed before executing LST). Hex Mode: This is the preferred viewing mode for binary (non-text) files. The display is altered when in this mode to display the file in standard "hex dump" format, that is: offset bytes ascii ====== ===== ===== xxxxxx xx xx xx xx xx xx xx xx-xx xx xx xx xx xx xx xx *aaaaaaaaaaaaaaaa* where offset is a six digit hexadecimal number indicating the current offset into the file, bytes are a set of 16 hexadecimal numbers which represent the next sixteen bytes of the file, and ascii is the ascii representation of the printable characters in that sixteen byte section of the file with non-printable characters represented as ".". Note that files with any of the following extensions may be viewed only in Hex Mode, ".COM", ".EXE", ".OBJ", ".BIN", ".DEV", ".LIB", ".DLL", ".ARC", and ".PKA". D. Accelerators and Aliases Certain menu functions may be accessed directly from the keyboard by use of certain accelerator keys. What follows is a table of these accelerators and their functions. Please refer to the "Menus" section for a description of the functions. Keystroke Function ========= ======== Q Exit A Repeat Last Search (same direction) \ Ignore Case Search / Exact Match Search ? Help ^N Search Next ^B Search Previous ^PgUp Previous File ^PgDn Next File Alt-H Toggle Hex/Text Mode F1 Help F3 Search Next F9 Search Previous F10 Exit Alt-I File Info Alt-R File Open Alt-X Exit Certain keystrokes are aliases (perform the exact same function) as other keystrokes. Note above that "Q", "Alt-X", and "F10" are aliases. What follows is a list of aliases. Keystroke Alias(es) ========= ========= Up Arrow ^E Down Arrow ^X Left Arrow ^S Right Arrow ^D Control Left Arrow ^A PgUp ^R PgDn ^C Home ^Q End ^Z F1 ? F3 ^N F9 ^B F10 Q, Alt-X E. The Pick List The Pick List is simply a list of files for LST to display. When LST is executed, each file that matches the filespec of specs on the command has its name added to the Pick List and the first file in the list is loaded and displayed. Each time Next File is chosen from the menu, or ^PgDn is typed the next file in the list is loaded and displayed, similarly, Prev File or ^PgUp loads and displays the previous file in the list. Choosing the "Pick List" menu items displays a dialog box that allows you to choose the next file to display. When "File Open" is selected and a new file or files specified, the new file names are added to the Pick List immediately after the current file. It is possible to have the same file name in the list multiple times. F. The LST Environment Variable If you do not like the default color scheme of LST the "-a" option on the command line provides a method for you to alter those colors. The syntax of the option is, however, neither easy to remember nor easy to type. If you wish to set any of LST's command line parameters on a semipermanent basis you may do so by setting an environment variable called "LST". When LST starts up it looks first for this variable in the environment and processes its contents as it would command line options. It then continues to process the command line so that options set in the environment may be overridden by the command line. For instance, if you want to force LST to always display 25 lines and want the main screen to be black on white, you could execute the following line from the OS/2 command prompt or from OS2INIT.CMD: set LST=-l25a70 G. Regular Expressions It is beyond the scope of this document to provide a thorough treatment of regular expressions however we will attempt to give an introduction to the topic here and to describe how this implementation should work. You may think of an OS/2 ambiguous filename as a regular expression in which the special character "?" matches any character in a filename and the special character "*" matches any string of characters. An OS/2 ambiguous filename is indeed a very restricted version of a regular expression. In the LST implementation of regular expressions, there are special characters that will match certain other characters: "?" matches any one character except the newline character "^" matches beginning of line "$" matches end of line "\" quotes a character, removes any special meaning. (or specifies as ascii character value: \9 == tab) Thus, using just these four, "^?$" would match any line that is exactly one character long, "^a?c" would match "abc" if and only if it were the first thing on a line, and "abc\$" matches only the string "abc$". The search in LST is line based so the "^" and "$" characters only make sense at the beginning and end of a pattern respectively. Other special "wildcards" are: ":a" matches any alphabetic character ":d" matches any digit ":n" matches any alphanumeric character ": " matches whitespace, the space character or the tab character And still more can be made up "on the fly" using classes. A class is a group of characters inclosed in square brackets "[]" and will match any single character which is listed in the class. "[abc]" will match "a", or "b", or "c" and [abcABC] matches "a", "A", "b", "B", "c", or "C". When the "^" character appears as the first character in a character class, it is taken to indicate negation, i.e., "[^abc]" would match any character EXCEPT lower case "a", "b", or "c". Furthermore, groups of characters may be specified using the "-" char- acter within a class designation: "[0-9]" matches any digit, "[^q-t]" matches any character except lowercase "q", "r", "s", or "t". Finally, we have the notion of closure. Any character followed by the "+" character matches one or more occurrence of that character: "fo+" will match "fo", "foo", "fooo", et cetera. Any character followed by the "@" character matches zero or more occurrences of that character, thus "fo@" matches everything that "fo+" did plus the string "f". The character "*" is shorthand for "?+". Examples: "[Gg]o@d" matches "Gd", "gd", "God", "good", "Goooooooood", etc. "[Gg]o+d" matches "God", "good", etc. ":d,:d:d:d" matches "1,000", "7,658", "9,999", etc. "^void" matches "void" if it appears as the first thing on the line. "\*/: @$" matches any line that ends with "*/" except for possible trailing white space. Exercise: What does "^[^ #\9]?@(?@): @$" match? IV. Limitations In Text Mode, the maximum number of lines in the file is limited to 65532 lines. The maximum line length is 1024 bytes and longer lines will be wrapped increasing the total number of lines in the file (in memory that is, the file itself is not altered). LST relies on OS/2's virtual memory management for loading the file itself into memory and it is conceivable that with low system memory and/or insufficient space on the swapping device, that a large file may be only partially read in even though it may have fewer than 65532 lines. In Hex Mode, each 16 byte "chunk" of the file becomes one line and is subject to the 65532 line limit thus the absolute maximum size of a file that may be completely read in Hex mode is 65532 times 16 bytes, or 1,048,512 bytes. V. Disclaimer Every care has been taken so that LST will perform as outlined in this document and that it is as error free as the author can make it. We should be aware however that no piece of software is ever totally bug free. Use of this software for any purpose whatsoever constitutes your unqualified acceptance of the following statements. The author makes no warranty or representation that the software will be error free. The author disclaims any warranties, either express or implied, including but not limited to any implied warranty of merchantability or fitness for any particular purpose. The user agrees to take full responsibility for the selection of and any use whatsoever made of the software. IN NO EVENT WILL THE AUTHOR BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION OR THE LIKE) ARISING OUT OF THE USE OF, INTERRUPTION IN THE USE OF, OR INABILITY TO USE THIS SOFTWARE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF ANY POSSIBILITY OR LIKELIHOOD OF SUCH DAMAGES. ________________________________________________________________ "IBM", "IBM PC/AT", "PS/2", "IBM OS/2" are all registered trademarks of and copyright by International Business Machines. "Microsoft", "Microsoft Windows", "MS OS/2" are all registered trademarks of and copyright by the Microsoft Corporation. ________________________________________________________________ Brady Flowers 518 Blue Earth Street Mankato MN 56001 Voice phone: 507/388-2848 Epitaph BBS: 507/243-3318 GEnie Mail address: B.FLOWERS