Garbo

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

/ Garbo / Garbo.cdr / pc / unix / more241.zoo / more.doc < prev next >

Wrap

Text File | 1990-03-27 | 26.9 KB | 661 lines

MORE A Unix-like file browser by Fred C. Smith HISTORY In late 1984 Dr. Dobbs Journal published Allen 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.4.1) 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.4.1) 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, more.cnf, and any readme files which may be in a particular release. All files must remain unmodified. You may, of course, modify more.cnf for your own use, but when re-distributing more, please use only the original unmodified files. 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 three 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), more.cnf to your \bin directory (or other directory which is mentioned in your PATH environment variable), and MORE.DOC to the location where you keep program documentation. You should read the readme file, if it exists in this release, to learn about the enhancements or bug fixes in this release. MORE.DOC (V 2.4.1) PAGE 3 CONFIGURATION FILE At version 2.4 of more a configuration file has been added. This file supersedes the use of DOS environment variables for configuring the behavior of more. Those environment variables which were utilized by previous versions are no longer used, and you should modify your environment accordingly. The configuration file in this release is named more.cnf. It may be placed in any directory which is mentioned in the PATH environment variable, as more will search through all the directories in that variable until it finds more.cnf or until it fails. If it fails it will tell you so, and will use a reasonable set of default parameters. The contents of this file are ordinary ASCII characters. At this release there are six parameters which may be specified in more.cnf. They are: windowsize=xx screenwidth=xx tabsize=xx moremono=x use_asm=x pause_at_end=x where 'xx' represents a one or more digit decimal number, and 'x' represents a single digit value of either '1' to enable the switch, or '0' to disable it. Blank lines are acceptable, and are ignored. Any line whose first character is a '#' character is considered to be a comment, and is ignored. The meaning of each of these parameters is as follows: Windowsize=xx tells more that it is to use a value of 'xx' as the size of the default scroll (i.e., when the 'space' command is given). The default value is 20. Screenwidth=xx tells more that the maximum line length on your display is xx characters. The default is 80. This parameter should not be set to any value other than the actual screen width, as the rightmost character position is handled specially. Tabsize=xx tells more that it is to assume that each tab character in any file it processes represents tab columns each of which is 'x' characters in width. The value given in the default more.cnf is 4, while the program defaults (if no value is given in more.cnf) to 8. Moremono=x tells more how to choose video attributes for the --MORE-- prompt. If the value given here is a one, more will use the attributes that it normally uses only on monochrome displays, even if it is running on a color monitor. If the value given is a zero, then more will choose the video attributes based on whether or not you have a color monitor. In the case of a color monitor more chooses bright white on blue as the prompt. The default value is zero. Use_asm=x tells more whether or not to use the new assembly language interface to the video BIOS. A value of MORE.DOC (V 2.4.1) PAGE 4 '1' tells more to do so, while a value of '0' tells more to use the old C language interface. The default value is 1. Pause_at_end=x tells more whether or not to pause when it encounters the end of the last file in the file list. When this parameter is set to 1 more will print a diagnostic and return to the --MORE-- prompt when it reaches the end of the last file. When set to 0 the behavior will be as in previous versions, i.e., more will simply exit after displaying the end of the last file. The default value is 1. CAVEATS This version of more was compiled using Microsoft C5.1 and Microsoft QuickC 2.0 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 is known not to work properly when nnansi.sys is installed as your ANSI console driver. Nnansi.sys is a variant of nansi.sys, a public domain (??) ANSI.SYS replacement, which was modified by Tom Almy for use specifically on EGA and VGA displays. Nnansi.sys takes over INT 10 (video BIOS functions), as well as doing some other things in non-standard ways, and thereby causes several problems with programs such as more which assume a totally standard set of video BIOS functions. (Microsoft's CodeView debugger also does not work properly with nnansi.sys installed.) If you insist on using nnansi.sys you can work around its problems by rebuilding it with the following flag settings (in nnansi_d.asm): takeBIOS=FALSE fast=FALSE 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, MORE.DOC (V 2.4.1) PAGE 5 version of DOS, any TSR's present on the system, etc. Remember that more is not my full-time job, so I cannot 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 MORE.DOC (V 2.4.1) PAGE 6 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.4.1) -- Figure 1 -- Regular Expressions PAGE 7 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. See the section describing the configuration file for information on the default value. -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. See the section describing the configuration file for information on the default value. ------------------------------------------------------------ MORE.DOC (V 2.4.1) -- TABLE 1 -- COMMAND LINE OPTIONS PAGE 8 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. :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. :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 MORE.DOC (V2.4.1) -- TABLE 2 -- COMMANDS RECOGNIZED AT PROMPT PAGE 9 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 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 skip forward to the end of the current file. More will display the last screenful of the file, and the prompt will show a percentage value of 100%. 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. The prompt shows the current value. Acceptable values are non- negative and non-zero. Also see the section describing the configuration file. ! 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.4.1) -- TABLE 2 -- COMMANDS RECOGNIZED AT PROMPT PAGE 10