Garbo

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

/ Garbo / Garbo.cdr / pc / unix / morefs23.zoo / more.doc next >

Wrap

Text File | 1989-08-31 | 22.6 KB | 595 lines

MORE A Unix-like file browser by Fred C. Smith HISTORY In late 1984 Dr. Dobbs Journal published Alan Holub's version of GREP. I ported Mr. Holub's version of GREP to run on the micro-based workstation that was the environment in which I was currently working, and quickly found it to be indispensable. That, of course, just whetted my appetite for more useful programs. I was particularly interested in having a program like Unix's MORE, which is sort of a super file browser. The workstation I was using had a tool called TYPE (aren't they all?), which while much better than nothing, just wasn't as good as MORE. It did nothing more than display on the terminal one screenfull at a time of text. I kept waiting, hoping in vain that Dr. Dobbs would publish a follow-up article after GREP, giving me a version of MORE. Before too long, however, anticipation got the better of me and I decided to write my own. DESCRIPTION Although my version of more has been ported to several different environments, this document describes only the version for MS-DOS/PC-DOS. More is a file browser with a number of interesting and useful features. Besides simply displaying a file a screenfull at a time, MORE allows scrolling in half screenfulls, and a line at a time. It will display an entire list of files, one at a time, and can skip forward to the next file on the list (without completing the current file, if you choose), jump back to the beginning of the current file, the beginning of the previous file, skip a specified number of screenfulls of the current file, search through each file in the list for a specified text string. The version of MORE given here is not an exact functional copy of the Unix version. There are a couple of reasons for that. First, there is more than one version of MORE on Unix, depending on which flavor of Unix you have. Second, I did not have access to a Unix manual or a Unix system for reference at the time I was writing this program. As a consequence I first put in those features that I had found most useful in the past, then added any others that I could remember. However, most of the features found in Unix versions of more are here, as well as a few not found on Unix. MORE.DOC (V 2.3G) PAGE 1 As in the Unix versions of MORE, this version will search for a line containing a match for a specified regular expression (for details on regular expressions, see Figure 1). This allows searching for sequences of text that match some specified pattern, rather than a particular character sequence. A variance from the Unix `standard' version of MORE (that relates to searching) is that in the Unix versions that I have used, when using the 'n' command to repeat the previous search, the search begins at the first line off the bottom of the screen. In this version, the search begins at the line immediately following the line which contained the preceding match, assuming that no other operations have occurred since the search. Otherwise, the search begins at the first line off the bottom of the screen. This version of MORE has another interesting feature not seen on most Unix versions, and that is the ability to move backwards through a file a screenfull at a time. As in the Unix versions, this version pauses at the end of each window with a prompt like: --More--(79%) The percentage given is the percentage of the current input file that has so far been read. If displaying input from a pipe, the percentage figure is not displayed. This version also contains a help facility. The command "h", "H" or "?" causes MORE to print a terse help message on the screen, and then return to the prompt. Table 1 describes the command line options available in MORE. Table 2 gives a detailed explanation of each of the commands that are accepted by MORE when it is paused at the prompt. COPYRIGHT INFORMATION The regular expression parser in this program is excerpted with only minor changes from the GREP distributed by DECUS (DEC Users Society). The DECUS code is copyrighted by DECUS and may be freely distributed for noncommercial purposes only. Some of the low-level routines which access the video BIOS are derived from code published in Dr. Dobbs Journal by Allen Holub and Jeff Duntemann. The code which tests the executable file for corruption (possibly by a virus) is derived from code presented in the August 1989 PC Magazine "Languages" column. The remainder of the code which constitutes this program, as well as the program itself (and this documentation), is copyrighted (C) 1986, 1987, 1988, 1989 by Fred C. Smith. The source is not available, but the executable may be freely distributed as long as it is not in any way modified and no fee is charged either for the program or in connection with its distribution. In plain English, I intend for anyone who wants to use my program to be able to do so, and I will permit no one to charge any fee whatsoever for using or distributing it. My copyright MORE.DOC (V 2.3G) PAGE 2 banner, and all other messages (including this document) must remain as I have made them, without change. You may distribute more freely (within the constraints outlined in the preceding paragraph), but when you distribute it you MUST distribute all the files in the original package. Those files are: more.doc (this file), more.exe, and any readme files which may be in a particular release. All files must remain unmodified. IMPLEMENTATION This version of more is a new implementation, independent of any versions offered on any variety of Unix system (or, for that matter, any other offering). There is no source code in common between this and the Unix versions. The only commonality is the name and most of the functionality. USAGE more [switches] [file names] See Table 1 for description of the switches. One or more filenames may be given, and DOS wildcards may be used. If no files are specified, more will look to standard input for data to display. This allows more to handle the output of a pipe, for example: grep "^void +.+(.*)[^;]*" *.c | more In which grep will output all lines beginning with a void function definition. This output will in turn be piped into more for display one page at a time. INSTALLATION The more distribution contains two files (it may also contain one or more readme files), as mentioned above in the COPYRIGHT section. To install more on your system, you should copy more.exe into your \bin directory (or into whatever directory you keep executables of utility programs -- this directory should be mentioned in your PATH environment variable, so that DOS can find more for you), and MORE.DOC to the location where you keep program documentation. MORE.DOC (V 2.3G) PAGE 3 ENVIRONMENT VARIABLES This version of more utilizes the following list of DOS environment variables to help it determine its behavior: TABSIZE -- number of spaces represented by tabs. Default, if not set, is 8. MOREMONO -- If this variable exists and contains the string "MONO" (without the quotes) more will always use monochrome display attributes for the prompt (rather than the bright-white-on-blue which it would normally use on a color tube). The default action, if not set as described, is to perform a series of BIOS calls to determine the display adapter/CRT combination in use and to use color or monochrome attributes as is appropriate. CAVEATS This version of more was compiled using Microsoft C5.1 running on PC-DOS 3.3, and requires MS/PC-DOS version 2.0 or higher. I have not been able to test the current version on DOS prior to 3.0, but I am not aware of any DOS functions being used which would compromise this compatibility. The only hardware dependency that I know of is the BEEP sound which occurs when illegal commands are given -- this beep is produced by direct control of the output ports which control the speaker on IBM compatible hardware. More does make a number of BIOS calls for things such as keyboard input and video output. As long as you are running on a machine which is compatible at the BIOS level it should work for you (with the exception of the beep sound). I have, however, not had the opportunity to try it on non-IBM- compatible hardware, so caveat user! BUGS - More assumes it is running on an 80 column by 25 line display. In most cases it would be expected to work acceptably on a display with more lines or columns, but would still scroll in 20-line increments and limit the lines to 80 characters in length. In the event that it is run on a display with, say, 132X50 columns/lines, it will not display correctly those lines which contain exactly 80 characters. The line following will be placed immediately following with no intervening linefeed. SUGGESTIONS If you have any suggestions for improvement, or find bugs which need attention please write to me (or send electronic mail) at the address below. Be sure to describe in detail how to re-create any bugs, including the full version number and compilation date of the more you are using (type 'v' at the prompt to see this information), type of machine, version of DOS, any TSR's present on the system, etc. Remember that more is not my full-time job, so I cannot MORE.DOC (V 2.3G) PAGE 4 promise instant attention, but I DO want to know about problems so that I can correct them. I do not have the time or facilities to get into the business of mailing out diskettes, but when significant new features or bug fixes occur I will release them through bulletin boards and usenet, in the same manner as this release. My mail address is: Fred C. Smith 20 Whipple Ave. Stoneham, MA 02180 Via usenet: ulowell!cg-atla!fredex or: ginosko!cg-atla!fredex MORE.DOC (V 2.3G) PAGE 5 Regular Expressions ------------------------------------------------------------ The regular_expression defines the pattern to search for. Upper- and lower-case are distinct. Blank lines never match. The expression should be quoted to prevent file-name translation. x An ordinary character (not mentioned below) matches that character. '\' The backslash quotes any character. "\$" matches a dollar-sign. '^' A circumflex at the beginning of an expression matches the beginning of a line. '$' A dollar-sign at the end of an expression matches the end of a line. '.' A period matches any character except "new-line". ':a', ':d', ':n', ': ' A colon matches a class of characters described by the following character. ":a" matches any alphabetic, ":d" matches digits, ":n" matches alphanumerics, ": " matches spaces, tabs, and other control characters, such as new-line. '*' An expression followed by an asterisk matches zero or more occurrences of that expression: "fo*" matches "f", "fo" "foo", etc. '+' An expression followed by a plus sign matches one or more occurrences of that expression: "fo+" matches "fo", etc. '-' An expression followed by a minus sign optionally matches the expression. '[]' A string enclosed in square brackets matches any character in that string, but no others. If the first character in the string is a circumflex, the expression matches any character except "newline" and the characters in the string. For example, "[xyz]" matches "xx" and "zyx", while "[^xyz]" matches "abc" but not "axb". A range of characters may be specified by two characters separated by "-". Note that, [a-z] matches alphabetics, while [z-a] never matches. The concatenation of regular expressions is a regular expression. Two regular expressions separated by a | match either a match of the first or a match of the second. MORE.DOC (V 2.3G) -- Figure 1 -- Regular Expressions PAGE 6 Command Line Options ------------------------------------------------------------ -s(Regular Expression) The -s option specifies a regular expression to be used as a search target beginning immediately upon entry to MORE. Like specifying a search function from within MORE except that the text in the first window is also searched. -t(tabsize) Defines the width to which tabs are to be expanded when a file is being displayed. By default more uses a value of 8. See also the section on environment variables. -v This option causes more to execute an internal consistency check before displaying any files. The purpose of this check is to see if the executable file has been modified.If it has the possibility exists that it was modified by a virus program. If any modification is found more prints a warning message and exits. This check is based on a 32-bit CRC, so it should be highly reliable. (It is not, of course, proof against intentional tampering, as a tamperer could easily patch around the virus checking code and distribute the hacked version as a trojan horse of some kind.) -w(decimal number) Used to specify the window size if a size other than the default of 20 lines is desired. ------------------------------------------------------------ MORE.DOC (V 2.3G) -- TABLE 1 -- COMMAND LINE OPTIONS PAGE 7 Commands recognized at `--MORE--' prompt ------------------------------------------------------------ return Causes the display to scroll one line. d or D Causes the display to scroll 1/2 the window size, either 10 lines, if the window default of 20 lines is used, or 1/2 the value specified in the - w<number> command line option switch. space Causes the display to scroll 20 lines if the default window size of 20 is used, or the value specified in the -w<number> command line option switch. /(Regular Expression) Causes MORE to begin searching for a line containing a matching Regular Expression. The search begins at the first line off the bottom of the display. The line containing the target, if found, is positioned near the center of the screen and is displayed with the bright attribute set. (If your screen is already set to some attribute other than white on black, this line may be displayed with some contrasting attribute other than bright white on black, so that it will be easily visible.) Pressing ESC aborts a search in progress. n or N Causes MORE to resume the previously specified search. If the search was the last operation performed, searching begins at the first line following the line containing the last match found. :f or :F Causes MORE to print the current filename at the bottom of the screen. :n or :N Causes more to abandon the current file, and skip to the beginning of the next file specified in the command line. Exits if the current file is the last file. :p or :P Causes MORE to jump back to the top of the current file. If already at top of the current file, causes MORE to skip to the top of the preceding file specified in the command line. If there is no preceding file, MORE will go to the top of the current file and display the first window full. :q or :Q q or Q Causes an immediate exit from MORE. f or F Causes MORE to skip (without displaying) one window full. A window is either the default of 20 MORE.DOC (V2.3G) -- TABLE 2 -- COMMANDS RECOGNIZED AT PROMPT PAGE 8 lines, or the value used in the -w<number> command line option switch. h, H, ? Causes MORE to display a help message which briefly describes all these commands. e or E Causes MORE to prompt for a file list. If a list is entered MORE will display those files in the same way as if they had been specified on the command line. Wildcards are accepted. If a null list is entered, MORE will revert to the original list entered on the command line. t or T Causes more to prompt for a number which represents the number of spaces to use when expanding tab characters on the screen. Also see the section on environment variables. ! Execute a command in a subshell (if followed by a command), or provide a prompt in a subshell (if no command is specified). The environment variable COMSPEC is used to determine the path of the shell to exec. The current DOS switch character is used in the command-line passed to that shell. counts Commands b, B, f, F, d, D, <return>, and <spacebar> accept a preceding count, i.e., the command '3f' causes 3 windows-full to be skipped. other input All other input is in error and causes the terminal to beep. MORE.DOC (V2.3G) -- TABLE 2 -- COMMANDS RECOGNIZED AT PROMPT PAGE 9