Lister: improving the Apple List command. Kerry Lourash.

Lister is a major rework of the Apple LIST command. It is a two-page machine language program that can be loaded and run, without modification, in any part of RAM.

The primary function of Lister is to pack as much information onto the screen as possible without compromising the legibility of the listing. This goal is accomplished in three ways. First, the cramped format of the stock listing is replaced by a full 40-column display.

The second method by which normal Apple listings are compressed requires a bit of explanation. All unnecessary spaces are eliminated when a Basic line is stored in memory. These spaces are "reconstituted" when the line is listed by printing a space before and after each keyword. This strategy saves RAM space and improves the readability of the listing, but it wastes screen space. For example, the stock LIST routine puts two spaces between adjacent keywords and between the number of a line and a keyword that follows it. Lister inserts spaces only where necessary.

Finally, Lister allows multiple ranges separated by commas, so that one Lister command does the work of many LIST commands. For example, the command -50, 140, 200 lists lines 0-50, line 140, and line 200. Syntax checking of the command string is done before the command is executed, so you do not have to deduce your mistake after the command string scrolls off the screen.

The lines listed by the last Lister command can be relisted by typing an R. Since the previous command string is stored in the stack area, it may be overwritten. In this case, the Apple will beep, and the prompt will be redisplayed.

Lister has a forward and reverse single-step option. To enter the single-step mode, hit any key while a list is in progress. Should you wish to enter this mode immediately, a short delay is provided between the time you hit the RETURN key and the start of the listing. The single-step mode options are shown in Figure 1.

Lister displays control characters as inverse characters. If a line containing an inverse character is edited with the cursor movement keys, the control character will be retained in the line. Take a Test Drive

Lister can be BLOADed into any two pages of free RAM. It might be called by inserting this line: 0 CALL (address of Lister) or by making the ampersand vector point to Lister. There is no need to include an end command in line 0, since Lister exits to Basic immediate mode.

When Lister is called, an inverse S or D (single- or double-space) prompt appears. If the first character of the command string is a space, the double-space flag will be toggled (from single-to-double-space or vice versa), although the prompt won't change until the next use of Lister. Typing R as a first or second character executes the last command string that was input. If the command string has been overwritten, the Apple will beep and redisplay the input prompt.

Legal command string characters are the digits 0-9, the dash, the comma, the space, and the letter R. A syntax error causes the Apple to beep and redisplay the input prompt.

Suppose a multiple-range command, such as -200, 900-1000 is input. When listing lines 0-200 and single-stepping through the program, you can look at lines greater than 200 by pressing the retype key. It is also possible, when listing lines 900-1000, to see the lines less than 900, even back to the start of the program. If you are listing the range -200 and wish to skip to the range (900-1000), you can type a comma. After the lines have been listed, it is possible to edit them and do a relist to be sure the lines are as expected.

Lister is compatible with the Apple Global Program Line Editor if the GPLE key buffer is turned off. When the key buffer is operational, the Lister single-step commands are stored in the buffer instead of being executed.

To get a hard copy of Lister output, it is best to type in the command string without the printer activated and exit Lister (CTRL-C) when the listing is as desired. Then do a PR#1 and use the relist option. This method sidesteps the problem of typing in a complicated command string that isn't echoed to the screen. The Key to Keywords

Two bits hold the information for the leading and trailing space of each keyword (1=yes, 0=no). The bits for four keywords are stored in one byte. A table near the start of Lister holds these bytes. Leading or trailing spaces can be changed by finding the keyword in the table and changing the corresponding two bits.

Suppose you want the keyword SPEED to have a leading space when listed. Select the byte in the table that contains the bit pair for SPEED. Isolate the bit pair, 01/00/0111, and change the first bit of the bit pair to a 1,01/10/0111. Now, put this change into the source code or calculate the hex equivalent (#$67) and put it into the Lister program in place of the original byte. How Lister Works

The ENTRY routine prints the input prompt (inverse S or D) and receives the command string. The command string is checked for a leading space (toggles double-space flag) or an R (uses previous command string) before it is stored in the stack. If a syntax error is found, the Apple beeps and Lister goes to the start of ENTRY. If the command string passes inspection, the first range in the command string is parsed. The return flag is set if there are more ranges to list.

The first step in listing a line is to output an inverse space, which facilitates finding the start of a line on the screen. If the output is sent to a printer, this space will probably be printed as a normal space.

If the character is a token, its two space bits are retrieved from the table, and a leading space is output, if indicated. The keyword corresponding to the token is output (? is output for PRINT), and a trailing space is output, if necessary.

If the character is not a token, it is output as a normal character or as an inverse letter if it is a control character. A space is added after a colon, unless it is in a PRINT statement. Warning: colons in REMS will have a space inserted after them.

When designing Lister, I was hesitant to include any printer-dependent features which might not be compatible with all printers. Features that you might want to add include:

* Select printer and send a printer setup string.

* Print control characters in lower-case or other distinctive mode.

* Indent line numbers.

* View the command string on the screen as it is typed.