LIST File Listing Utility ========================= Version 3 William P. Wood, Jr. The Institute For Cancer Research 7701 Burholme Ave. Philadelphia, Pa. 19111 (215) 728 2760 LIST File Listing Utility Page 2 LIST is a utility for examining the contents of files. It's sim- plest use is to display records at the terminal a screen at a time, however it can also search for character strings and write portions of files to other files. Any record in a file may be accessed directly by line number or by a search. This manual explains how to use LIST. 1.0 Running LIST The LIST command line has the following syntax. (Optional parts of the command line are enclosed in square brackets): LIST[/qualifiers] input_file[,...] [commands][>[>]output_file] 2.0 Qualifiers Qualifiers are placed one after the other on the command line, and apply to each source file selected by the command line. In the descriptions below, default qualifier settings are indicated by "(D)". /PROMPT /NOPROMPT Prompt with each file name selected by the command line to see if the file should be listed. By default, LIST prompts when more than one file is selected by the command line or when an indirect file is specified. (see "Input File Spec- ification") . /HEADER /NOHEADER (D) Write a header record containing each file's name and the date before listing each source file. /NUMBERS (D) /NONUMBERS Display the line number of each line selected by the "?" command. (see the "?" command, under "Commands") /TRIM /NOTRIM (D) Trim trailing blanks and tabs from the source file. By se- lecting /Trim and restricting the column range of the file to columns 1-72, Fortran files can be stripped of sequence numbers. (see the "C" command, under "Commands") /DELETE /NODELETE (D) LIST File Listing Utility Page 3 Allows the user to delete a file after listing it. When /DELETE is specified, LIST prompts with Delete? after each file selected by the command line has been list- ed. If Y is entered, then the file is deleted. 3.0 Input File Specification Each "input_file" may be a simple file name, an indirect command file name preceded by @, or in some installations, a file name con- taining SRD wild card characters and/or switches. More than one "input_file" may be entered by separating them by commas. If "input_file" is a simple file name, LIST lists the file. The default file extension is ".lst". For example, > list abc.dat lists the file abc.dat. If "input_file" is an indirect file name, LIST lists the named files in the indirect file one at a time. Each file name must appear on a line by itself and may not have wild card characters in it. The default extension for indirect file names is ".cmd". For example, > list/noprompt @files lists each file specified in files.cmd . If "input_file" contains wild card characters and/or switches, LIST lists the files which match the wild cards and/or switches. Normal SRD wild card characters and switches may be used in an SRD-type file name; however, do not use the /SE: switch, as this is the default switch. Also, only the most recent versions will be se- lected unless ;* is specified. When more than one "input_file" is specified or when "input_file" contains wild cards and/or switches or is an indirect file name, LIST prompts with each of the selected file names to see if you want them listed, unless /NOPROMPT was specified (see Qualifiers) . Responses to the prompt are: Y List the file. or N Don't list the file. G (GO) List this and remaining files with no prompting. ^Z Don't list this file and remaining files. LIST File Listing Utility Page 4 When commands are given on LIST's command line, they are executed once for each file selected by the input file specifications. When output is redirected by the command line, it remains redirected for each file selected (see Redirecting Output From LIST) . For example, > list * 1,$px >all.lst prints *.lst into the file all.lst . 3.1 Default Fields in File Names More than one file may be listed during the same LIST session by typing LIST and then a carriage-return. LIST then prompts with the "File? " prompt for one or more file name(s). After the file(s) have been listed, LIST prompts for a new file name. Whenever LIST encounters an input file name, the node, device, uic, name, and extension fields are remembered and become the de- faults, even if the field has wild card characters in it. The de- faults are used to replace missing fields of subsequent file names en- tered for listing. For example: > LIST File? lb:[22,2]list.doc When you are finished listing LB:[22,2]LIST.DOC, then to see LB:[22,2]VG3.DOC you would only have to type: File? vg3 and LIST would supply the missing fields of the file name. If LIST can't find a file after supplying the defaults, it tries the file name as entered. Initially, the defaults are "sy:" for the device and ".lst" for the extension. 4.0 Searching LIST can search backwards and forwards in the input file for lines which match a specified search pattern. A search pattern is a string of characters bracketed by slashes (/) or backwards slashes (\): /string/ causes LIST to search forward from the current line for a line which matches "string". \string\ causes LIST to search backwards from the current line - 1 for a line which matches "string". LIST File Listing Utility Page 5 Case is not significant in search patterns, eg. /X/ and /x/ match the same lines, unless the characters are inside double quotes (see below). Once specified, a pattern becomes the default pattern and may be invoked by // or \\. For example, /john doe/ searches forwards for a line with "john doe" in it in upper or lower case. There are several characters which have a special meaning when they appear inside a search pattern: " All characters within enclosing double quotes are treated li- terally, not as special characters. The case of a character is significant when it appears within double quotes. Two dou- ble quote characters in a row within enclosing double quotes are interpreted as one literal double quote. For example, /"John Doe"/ matches only lines which contain literally John Doe . ~ negation. Causes a match if the pattern does not match the line. ~ must appear at the beginning of a pattern (unless a column range is specified (see Search Column Ranges) ), other- wise it has no special meaning. For example, /~abc/ matches lines which don't contain abc. % specifies that the match must occur at the beginning of the line only. % itself must appear at the beginning of the pat- tern, otherwise it has no special meaning, unless a column range (see Search Column Ranges) or negation (~) is desired; in this case the column range and/or the negation character must appear before %. For example, /%10/ matches only lines with a 10 in the first two columns, and /~%10/ matches lines without a 10 in the first two columns. $ specifies that the match must occur at the end of the line only. $ itself must appear at the end of the pattern, other- wise it has no special meaning. For example, /%$/ matches only empty lines. LIST File Listing Utility Page 6 * is a wild card character that matches any sequence of char- acters, including the empty sequence. For example, /john*doe/ matches lines containing johndoe or john doe or johnabcdoe etc. ? is a wild card character that matches any single character. For example, /a?c/ matches lines containing abc or acc or a c etc. @ matches any one alphabetic (a-z or A-Z) character. For exam- ple, /a@c/ matches lines containing abc or acc but not a c. # matches any one numeric (0-9) character. For example, /%#/ matches lines with a number in column 1. ` accent matches a break character. Break characters are: beginning of line, end of line, and any non-alphanumeric char- acter. For example, the ? command can be used with the fol- lowing search pattern to display lines which contain the vari- able I: /`i`/? ^ causes the next character to be interpreted as a control char- acter. For example, /^z$/ matches lines containing control Z at the end of the line. | logical OR. Causes a match if the sub-pattern before it or the sub-pattern after it match the line. For example, /abc|xyz|%#/ matches lines containing abc or xyz or a number in the first column. The negation character (~) may be used at the begin- ning of a sub-pattern; for example, /~x|~y/ LIST File Listing Utility Page 7 matches lines which don't contain an x or don't contain a y. & logical AND. Causes a match if the sub-pattern before it and the sub-pattern after it match the line. For example, /x|y&abc/ matches lines containing abc and an x or a y. The negation character (~) may be used at the beginning of a sub-pattern; for example, /~x&~y/ matches lines which don't contain an x and don't contain a y. 4.1 Search Column Ranges Search patterns can restrict the range of columns in the input record in which the search is to take place. A column range is speci- fied by placing the special character "<" at the beginning of a pat- tern or subpattern, followed by two column numbers separated by a comma, followed by a ">" character. The rest of the search pattern follows the column range specification. For example, /<11,15>123/ searches for 123 in columns 11 through 15. Subpatterns can also specify a column range, for example: /<30,31>10&<40,41>20/ searches for a record with 10 in columns 30 and 31 and 20 in columns 40 and 41. The special characters ~ (negation) and % (match at beginning) should appear after a column range specification. For example, /<10,20>~abc/ searches for lines which don't contain abc in columns 10 through 20. When % or $ is used with a column range, the match must occur at the beginning or end, respectively, of the column range. For example, /<10,50>%abc*xyz$/ matches lines with abc starting at column 10 and xyz ending at column 50 (or the end of the record, whichever is shorter). The characters "<" and ">" and the other characters in a column range specification are only special at the beginning of a pattern, and may be used freely elsewhere in a pattern, for example: LIST File Listing Utility Page 8 /~<10,20>/ matches lines which don't contain <10,20>. 5.0 Numbers Numbers are used to position LIST in the file and as arguments to commands. Numbers always precede the command they affect. A number may be a simple integer, one of several special line number variables (see Line Number Variables) , or a search pattern. The numeric value of a search pattern is the number of the line that matches the pat- tern. LIST scans the command line from left to right. Whenever it en- counters a number, the current line number, dot, is set to that number. When multiple line numbers appear next to each other, LIST positions to each in turn, for example: 1/abc/ searches for abc at or after line 1. Some commands optionally take two numbers as arguments; when specifying more than one number, separate the two numbers by a comma. For example, the P command may be used to print lines 1-45: 1,45p Numbers may be added and subtracted from one another, for example: /x/-1,+2p prints three lines around the next line which contains an x. 5.1 Line Number Variables . Dot is the current line number. Whenever LIST encounters a line number, the value of dot is reset to that line number. For example, /x/,.p prints the next line containing an x. $ Dollar is the last line of the file. For example, 1,$p LIST File Listing Utility Page 9 prints the whole input file. # Sharp is the line number displayed by the most recent prompt. For example, if LIST was positioned at line 10 as indicated by the prompt "10>" then 10>1,#/x/p would print from line 1 to the next line containing an x at or after line 10. @ At-sign is the line number of the top of the last screen displayed by LIST. For example, @+1//p searches for the next line matching the current pattern after the top of the last displayed screen, and prints a screen from there. * Star is set by the "=" command and is equal to the value of dot when the "=" command was last issued. * marks a line of interest for future reference. For example, =\subroutine\,*/end/p marks the current line, then searches backwards for subrou- tine, then returns to the marked line, searches forwards for end, and finally prints the lines between the two matched lines. 6.0 Commands LIST accepts commands on it's initial command line or when it prompts with the current line number, for example: 24> Commands are single characters and are preceded by zero, one, or two numbers which are arguments to the command. More than one command may be entered on a command line; LIST scans the command line from left to right, positioning to line numbers and executing commands. There are two types of commands; those that print and those that affect LIST's state without printing. Commands that print usually print from dot (the current line number) unless two line numbers were specified, in which case printing occurs from the first line number to the second. Other commands "eat up" the number(s) that are their ar- guments; in other words, dot retains the value it had before the com- mand, with its numeric argument(s), was executed. LIST File Listing Utility Page 10 If a line number appears at the end of the command line with no command after it, the default command (P) is executed. For example, /abc/ at the end of a line of commands is equivalent to /abc/p since both cause a screen to be displayed from the next line contain- ing abc. Note: LIST usually changes most control characters to nulls before writing out a line, however when two line numbers are specified or when the G command is executed, (for example the commands "1,$P" or "100G") all characters are written out unchanged. Thus it is possible to write out portions of a file without los- ing any characters. 6.1 Commands That Print P Displays lines from the file. Dot is left at the last line printed plus 1. P is the default command, and is optional at the end of the command line. P Print as many lines as will fit within the current screen size (initially 23), starting at the current line (dot). nP Print as many lines as will fit within the current screen size starting at line n. n1,n2P Print lines n1-n2. Example: 1,10p prints lines 1 through 10. G Like "P", "G" displays lines from the file, however with zero or one arguments G only prints one line, and dot is left at the first line printed. G Print the current line. The current line is not changed. nG Position to and print line n. Dot is left at line n. LIST File Listing Utility Page 11 n1,n2G Print lines n1-n2. Dot is left at n1. Example: /subroutine/g prints the next line with the string "subroutine" in it. ? Displays lines matching the current search pattern, and their line numbers (unless /NONUMBERS is specified on LIST's command line). ? Display a screen-full of lines matching the current pattern. If the end of the file is reached, dot is left at line 1, else dot is left at the next line matching the current pattern. n? Display a screen-full of lines matching the current pattern, starting at line n. If the end of the file is reached, dot is left at line 1, else dot is left at the next line matching the current pattern. n1,n2? Display all lines matching the current pattern between lines n1 and n2. Dot is left at n1. Example: 1/xyz/,$? displays all occurrences of xyz in the input file. 6.2 Other Commands L The L command causes the last line of commands to be reexecuted. = The = command sets the line number variable, *, to dot. = marks a line for later reference. = Set * to dot. n= Set * to n. Dot is left at line n. Example: /x/= marks the next line containing an x. LIST File Listing Utility Page 12 S Sets the screen size. The value of dot is unchanged. S Reset the screen size to 23. The screen size and width help determine how many lines LIST prints per screen. nS Set the screen size to n. n1,n2S Set the screen size to (n2-n1)+1. Example: 7s sets the screen size to 7. C Sets the column range which will be read from each input record. Initially the column range is 1-513. LIST can only read up to the first 512 characters in a record, however when the column range is set to be greater than 512, then LIST reports an error when an input record is more than 512 characters long. If the column range is restricted to 512 or less then LIST does not re- port record too long errors. The value of dot is unchanged. C Reset the column range to 1-513. nC Set the column range to 1-n. n1,n2C Set the column range to n1-n2. Example: 1,10c causes LIST to read and display only columns 1-10 of each record. F Creates a "virtual file" by restricting LIST to a contiguous su- brange of the lines in the file. Dot is left at line 1. F Reset the virtual file to correspond to the actual file. nF Make a virtual file between dot and dot+n-1. Dot be- comes the new line 1 of the virtual file. n1,n2F Make a virtual file between n1 and n2. N1 becomes the new line 1 of the virtual file. Example: /subroutine/,/end/f creates a "virtual file" which contains a subroutine. Line 1 of LIST File Listing Utility Page 13 the virtual file is the first line of the subroutine, and $ is the last line of the subroutine. N Turn prompt mode on/off. When prompt mode is off, LIST does not prompt with the current line number, but leaves the cursor after the last line printed. The value of dot is unchanged. Example: 1sn sets the screen size to 1 and prompt mode off, placing LIST in line-by-line mode, in which one record is printed per carriage-return. R Resets dot to 1, the screen size to 23, the screen width to it's original value, the column range to 1-513, the virtual file to the full, actual file, and prompt mode to on. The value of dot is unchanged. X Finish listing the file. X is identical to ^Z (EOF). ' ' Space (blank) is the null command, and does nothing. It may be used to position to a line without printing and to separate com- mands on a line for readability. If a line number is given be- fore the space command, dot is left at that line number, else dot is unchanged. Example: 1,10f p creates a "virtual file" between lines 1 and 10 and prints start- ing at line 1. W Sets the screen width. The screen size and width help determine how many lines LIST prints per screen. The value of dot is un- changed. W Reset the screen width to it's original value, read from the host operating system when LIST was started. nW Set the screen width to n. Example: 132w sets the screen width to 132 columns. LIST File Listing Utility Page 14 V Routes all the following output from the command line to the printer port of the DT80 (a VT100 look-alike). The value of dot is unchanged. Example: v 1,100p turns on the printer port, prints lines 1-100 on the printer, then turns the printer port off. 6.3 Looping A sequence of commands may be repeated in a loop by placing the commands within parentheses with a repetition count in front of the left parenthesis. The commands are then executed as many times as in- dicated by the repetition count or until a search within the commands fails. In either case, after exiting the loop execution continues with the next statement after the loop. If no repetition count is specified, the loop is executed forever or until a search failure oc- curs within the loop. For example, (/`i`/+1\subroutine|function|program\,.p /end$/) loops finding all Fortran modules which contain the variable I and prints the line containing each module's name. Loops may be nested up to four levels. 6.4 The Macro LIST has a simple text replacement macro facility. A macro is a remembered set of commands. The macro is defined by enclosing the commands in square brackets ([]). When M is specified on the command line, the M is replaced by the macro text. For example, [@+1//P] defines a macro to search for the current pattern starting from the top of the last screen + 1, and print from there. To invoke the macro, type M on the command line. The text of the macro is not executed when it is defined. It is not executed until an M is typed. M may appear with other commands and line numbers on the command line; first the macro text replaces the M, then the command line is executed. M may be used more than LIST File Listing Utility Page 15 once on a command line. Initially, the macro is defined as 1SNP; this puts LIST in line-by-line mode and prints one line (see the N command) . 7.0 Redirecting Output from LIST The output from a line of LIST commands, which normally goes to the terminal, may be redirected to a file. To write a new file, put >output_file at the end of the commands; to append to an existing file, put >>output_file at the end of the commands. If "output_file" doesn't exist during an append, it will be created. The default file name for "output_file" is "list", and the de- fault extension is ".lst". If "output_file" contains asterisks in it, then each field of "output_file" with an asterisk in it is replaced by the corresponding field in the input file name. When output is redirected by the initial command line which se- lected the file(s) to be listed, it remains redirected as long as the file(s) are being listed. For example, > list/noprompt/header *.dat /xyz/,$?x >xyz lists all occurrences of the string xyz in *.dat to the file xyz.lst . However if the output file specification contains asterisks, a new output file is created for each input file listed, with the fields with asterisks in them replaced by the corresponding fields from the input file name. For example, > list/noprompt/trim [100,*]*.ftn 1,72c 1,$px >[*]*.ftn trims the sequence numbers and trailing blanks from [100,*]*.ftn and rewrites each file with a higher version number in its original UIC. When output is redirected from a command line while listing a file, redirection is only in effect while that command line is being pro- cessed. For example, 24>1,10p>t.tmp writes lines 1-10 to the file t.tmp and then closes it. The carriagecontrol type of newly created files is identical to the carriagecontrol type of the file being listed, while that of ap- pended files is the same as that of the file being appended to. Once an output file name has been specified using >output_file or >>output_file, that file name becomes the default file name for file redirection only, and need not be specified again, i.e. > or >> alone is all that is needed to redirect output to that file. The name of LIST File Listing Utility Page 16 the file is remembered as it was typed in, so that asterisk fields are replaced with the fields from the current input file. LIST File Listing Utility Page 17 8.0 Examples Hitting return prints the next screen. 45 Start printing at line 45. -5 Print from 5 lines back. - Print starting half a screen back. --- Print starting one and one-half screens back. Hitting escape prints from 2 screens back. $ Print the last line in the file. /xyz/ Locate the string xyz and print from there. // Locate the current pattern and print from there. 1/xyz/ Locate xyz at or after line 1 and print from there. /abc/-5 Print starting 5 lines before abc. 1,10 Print lines 1-10. /subr/,/end$/ Print the next subroutine. /subr/? Display lines containing subr. ? Display lines containing the current pattern. 1/`i`/,$? Print all occurences of the variable "i". 10,$>t.tmp Write lines 10 through the end of the file to t.tmp > list *.ftn /`n`/,$?x prints all occurrences of the variable N in *.ftn