Full Screen Editor This editor is a simulation of some of the features of the VM/SP system editor "XEDIT", with some changes. Initialisation The Full Screen Editor code is fully relocatable. Load it in at any address, and then call it at that address using the PRINT USR command. When the editor has started up, enter the command "new" on the command line before starting to edit. 3270 Architecture Keyboard input simulates fairly closely the IBM 3270 structure, in that 1. there are 'protected' fields and 'input' fields; the cursor may be anywhere on the screen, but typing is only allowed in input fields. 2. Typing is stored only on the screen until one of a number of keys is pressed, when all changes are obeyed. Enter and 'PF' keys are the only such keys in this simulation, together with the CLEAR key, which redraws the screen, ignoring the most recent changes. 3. Typing normally overwrites the characters under the cursor. Pressing INSERT causes an insert symbol /\ to appear at the top right of the screen and further keyboard input is inserted before the character over which is the cursor. Pressing DELETE deletes the character under the cursor and does not move the cursor. If a character is deleted from the middle of a file line which occupies many screen lines, only characters on the same screen line as the cursor are moved. A NULL is inserted at the end of the line. (This increases the speed slightly). 4. A NULL is a character which looks like a space, but which is ignored by most actions, for example a NULL in the middle of a line caused by a DELETE will be removed when the line is added to the file. A deviation from 3270 architecture is that whenever a character is typed, all NULLs immediately to its left will be changed to spaces. The keyboard implementation is as follows: PF 1-10 Extended mode 1-0 PF 11-20 Extended mode Q-P INSERT EDIT DELETE DELETE ERASE EOF Extended mode symbol shift 0 CLEAR Extended mode shift X |-->| INV VIDEO |<--| TRUE VIDEO The ERASE EOF key erases all characters under and to the right of the cursor, up to the end of the input field, and replaces them with NULLs The |-->| and |<--| keys tab to the next and previous input fields respectively. Pressing |<--| when the cursor is in the middle of an input field moves the cursor to the start of that input field. Screen Layout The top line is a message line, which normally contains the title "Full Screen Editor" and the alterat- ion count (ALT). The bottom two lines are command input lines, indicated by the arrow sign. Up to 121 characters of command may be typed there. The last character of the command input field has a red attribute, the rest being green. The rest of the screen forms the file area. There are three types of area here: the line numbers in inverse video (this is to highlight them, because this editor is likely to be used with file lines longer than a screen line) which are protected; the file line itself, and the prefix area (two underline characters) - the latter two areas are input fields (there is a protected space between each line number and its file line). The protected file lines "Top of file" and "End of file" appear at the top and bottom of the file; these also have prefix areas, but do not form part of the file itself. File lines which are longer than one screen line are displayed; they wrap around onto the next line. When typing, when the cursor gets to the end of a line, the file line is automatically extended onto the next screen line; the rest of the file moves down to make room for it. When ENTER or a PF key is pressed, information typed on the screen is processed in the following order: 1. any changes typed in the file area are stored in the file 2. prefix commands are obeyed 3. a command on the command line is obeyed After this, if a PF key was pressed, it is obeyed. Pressing ENTER when there have been no changes will alternate the cursor between the command line and the file. When the cursor is moved to the command line by pressing ENTER its position is stored, so that when it is later moved to the file by pressing ENTER it will try to move to the same position in the file. This may be a different position on the screen. If the stored position is no longer on the screen, the cursor remains on the command line. Prefix Commands A prefix command usually affects the line to the left of which it is typed. All prefix commands can be typed as single characters, and in addition some commands accept a digit (1-9 or 0 to mean 10) as a parameter (the command and the digit may be typed in either order). Some commands may affect a block rather than a single line; in this case the command is typed as a double character at the start and the end of the block. The commands are: a - add a blank line after this line. An optional digit indicates how many blank lines to insert c - copy this line (see commands f and p). A digit indicates how many lines (starting at this line) to copy. This command may be used in block form, marking both the top and the bottom of the block with cc. d - delete this line. Similarly, a digit may be added or a block may be marked. f - the destination follows this line (see commands c and m) m - move this line (see commands f and p). As with commands c and d, a digit may be added or a block may be marked. p - the destination precedes this line (see commands c and m) " - repeat this line. Adding a digit repeats this line that number of times, and marking a block repeats the whole block once. / - make this line the current (top) line. For example to move lines 110-116 to a new position between lines 104 and 105, type "mm" at line 110 and at line 116 and type "f" at line 104 (or "p" at line 105). An invalid prefix command will be replaced by a question mark on pressing ENTER; this will then disappe- ar at the next press of ENTER (or a PF key). If a delete command deletes a line containing a prefix command, then this command will be changed to a question mark and may be moved up. Prefix commands which cannot be obeyed immediately (such as f, p, c or m on its own or a single start/end block marker) are stored and will remain until either they are deleted or they can be obeyed. They remain even if they are not currently displayed on the screen. Hence a block which is larger than the screen may be copied/ moved etc. A maximum of five prefix commands can be stored pending execution, any extra are ignored and an error message is issued. The prefix area normally contains underline characte- rs, but a prefix command may be deleted by pressing delete or by typing a space as well as by replacing the underline characters. Command line Commands Some commands affect the current line. This is (in this implementation) the top line, which is white instead of green. The commands are listed below. Upper or lower case is accepted, and abbreviations are allowed for most commands. The minimum abbreviation is that part of each command which is listed in capitals. Some of the commands are assigned to PF keys. A PF key is listed after each command where applicable. Add (PF2):- If the cursor is in the middle of a line, it is moved to the end of that line. If it is to the right or left of a line then it is moved to a new blank line following the line where it was previously. Top (PF4):- The "Top of File" line is made current (and is displayed at the top of the screen with the initial portion of the file following it). Bottom (PF5):- The last portion of the file is displayed. = (PF6):- This repeats the last command issued from the command line. BAck (PF7):- This scrolls back a page. As some file lines may occupy more than one screen line it is necessary for the program to estimate how far back to go, so this command will not always go back exactly one page. Forward (PF8):- This scrolls forward one page. ? (PF10):- This retrieves the last command. For more information see Command History. SPltjoin (PF11 or PF1):- If the cursor is in the middle of a line, then the line is split - the portion of that line under and to the right of the cursor is moved into a new line immediately below. If the cursor is to the right of a line, then the following line is joined on at the cursor. Up n:- Move up n lines. The parameter may be omitted, in which case 1 is assumed. Down n:- Move down n lines. The parameter may be omitted, in which case 1 is assumed. :n :- Line number n will be made current. The star character * may be used in place of n, in which case the "End of File" line is made current. Input:- The editor is put into input mode, to input lines after the current line. A few of the lines above the cursor are displayed, and the cursor is placed in a blank line ready for input. Each time ENTER is pressed, a new blank line is created for more input, until ENTER is pressed without editing the line which is currently being input. When this happens, the blank line is removed and Input Mode is exited. Power:- This places the editor in Power Input mode. It is similar to Input mode, but is used for paragraphs rather than lines of input. Each time text is entered and ENTER is pressed, the text is formatted according to the current setting of the FORMAT variable (see SET). Pressing ENTER without typing any text exits Power Input mode. REform:- This command reformats a paragraph (accordi- ng to the current setting of the FORMAT variable - see SET) starting at the current line and continuing until the last line which starts with a non-blank character. A number may be supplied after the word REform, in which case exactly that number of lines is reformatted, starting at the current line. /string :- This command locates the given string. If the cursor is on the command line when this command is executed, the search starts at the first character of the current line, otherwise the search starts at the cursor. If the / command is typed with no string (this command is assigned to PF19) then the last string specified in a locate or change command is located. (See also the SET command with parameters CASE and VARBLANK). Change/string1/string2/n :- This will change all occurrences of string1 to string2 in the current line and continue for n lines in total. If n is the star character then all occurrences after the current line are changed. If n is omitted then only the current line is affected. The slash characters / may replaced by other separators as long as the same separator is used in each case. Note that spaces may be used for this purpose, so there must be no space between the command word and the first separator. The first string may be omitted, in which case the last string specified in a locate or change command is used. If the first string is omitted then the second string may also be omitted, in which case the last string used in this position is used. Trailing separators may be omitted. Hence the command Change on its own is allowed, and will perform the same action as in the last change command, but only in the current line. SCHange/string1/string2 :- This has the same syntax as Change, but without the number parameter. It is the same as Change, but affects only the line on which is the cursor, and on that line only the first occurrence of the target string after the cursor. The command SCHange with no parameters is assigned to PF20, where it can be used along with PF19 (locate) to do selective changing. CSave, CLoad, DSave, DLoad:- These commands are used for saving and loading to/from cassette or disk. A name should follow which conforms to the regulations for whatever medium is being used. The name should NOT be in quotes. The name should always be supplied unless loading from cassette, in which case the name may be null as in LOAD "". The CSave and CLoad commands are always passed to BASIC to interpret, which on 48K and 128K machines results in a cassette operation. On 48K Disk Basic however, this results in a disk operation. The DSave and DLoad commands are interpreted differently depending on the machine. On a +3 these commands call DOS directly and result in normal disk operations (the full filename syntax is allowed including drive names and user numbers, and the default drive may be set by specifying a drive without a name). A 48K spectrum is checked to see if the interface 1 is present, and if so it is called directly to save or load the file on microdrive (there are two interface 1 versions, both should work correctly). When saving a file to micro- drive, if the file already exists, the program asks whether or not to erase it. On 48K Disk Basic, the DLoad and DSave commands are passed to BASIC, which results in a disk operation. The default drive may be set, but the error "Nonsense in BASIC" will result after it has been set, as it does in normal BASIC when a command such as LOAD "M:" CODE is issued. CAT:- This command only works on a +3. A filename may optionally be specified (NOT in quotes) in a similar way to the BASIC CAT command. A list of files on the specified (or default) drive will appear. On other machines, the BASIC CAT command may be used. * :- When the star character is the first (non-blank) character on the command line, the rest of the command line is tokenised and passed to BASIC for interpretatio- n. For more details see the information about BASIC within the editor. BASIC x y:- This converts the file into BASIC with line numbering starting at x and continuing with step y (x and y may be omitted, in which case 10 is assumed). For more details see the information about BASIC within the editor. RUN:- This command is similar to typing BASIC and then *RUN. It converts the file to BASIC and then runs it. GET:- This command converts the current BASIC program into edit format. For more details see the information about BASIC within the editor. MOVE offset:- This command moves the editor program and the file it is editing in memory by offset bytes. The parameter offset must start with + or - and may take on any value up to a maximum depending on the relative positions of RAMTOP, the editor, the end of the file and the top of memory. If the move would involve going past RAMTOP or the top of memory then the error "Out of Memory" is issued and the move does not take place. This command is useful for making room either for a BASIC program or for a larger edit file. QUit:- If the alteration count is zero, this command leaves the editor and returns to the BASIC from which it was invoked. Otherwise a message is issued and the command is ignored. The alteration count is incremented each time the file is altered and is set to zero by save, load and new commands. QQuit:- This is a quick quit; it exits the editor even if the alteration count is not zero. NEW:- This command places an end of file marker at the start of the file and allows a new file to be edited. This command MUST be carried out before editing a new file as otherwise the file will not contain an EOF marker and unpredictable results will occur. Query, SET:- The Query command takes as a parameter any of the keywords below and displays a message about the current state of that setting. The SET command takes as parameters the keywords and their arguments as listed below, in order to change settings. PF:- The Query PF command displays all the PF keys currently set. PFn text:- The Query PFn command displays the setting for PFn. The SET PFn text command assigns text to PFn. If the text is blank then the PF key is un-defi- ned by the SET command. The text assigned to a PF key is placed in the command line whenever that PF key is pressed (after all other actions have been taken). If the text ends with a hash character # then this charact- er is not put on the command line, but the preceding text is executed as if ENTER had been pressed. Case {Mixed|Upper} {Ignore|Respect}:- (Either of the two paramters may be omitted). Mixed vs. Upper controls whether input lines are translated into upper case, and Ignore vs. Respect controls whether the Locate command respects case during comparison. CASE M I is the initial setting. Varblank ON|OFF:- The initial setting is ON, in which every Locate command may match a varying number of blanks in the file with one blank in the search string (so "that is" will match "that is"). If Varblank is OFF then spaces are treated like any other character. Format {width} {Nojustify|Justify}:- (either of the two parameters may be omitted) This controls the formatting of text by the Power and REform commands. The first parameter is a number giving the maximum characte- rs on a line, and the second parameter indicates whether or not justification of the right margin is required. The initial setting is 56 N. Text is formatted by splitting it up into lines of the required length or less, splitting up words only when deemed necessary by the program (in which case a hyphen is added). Justific- ation is achieved by adding spaces evenly between words to bring each line up to the correct length. Errors {ON|OFF} {address}:- This controls the error address (normally pointed to by ERRSP) for BASIC commands (for more details see the information about BASIC within the editor). Either of the two parameters may be omitted. If errors are OFF then a BASIC error is passed to the normal error routine (which is the same as ON H1303). If errors are ON then they are passed to the address specified (either as a decimal number or as a hex number preceded by H). This address is stored even when errors are OFF, so errors may be switched OFF and ON again without re-specifying the address. Initially, errors are usually OFF H1303, but if an extended BASIC program was active and using the machine stack when the editor was invoked then errors will be ON and set to that program's error address. Error messages Some commands produce error messages, and BASIC commands can also produce error messages. These are displayed in red at the top of the screen. If BASIC issues an error message, then it will usually appear straight away at the top of the edit screen. However if the error number is 255 (for 0 OK) then the editor pauses for a second to allow the message to be read. This is because some extended BASIC programs cancel the error number before the editor can see it. Errors issued by the editor are (with some explanations where necessa- ry): CAT not available on standard spectrum Cursor is not on a valid file line:- some commands require the cursor to be on a line of the file. If it is not on an appropriate line then this message is issued. File has been changed. Use QQUIT to quit:- This occurs when QUit is entered and the alteration count is not zero. Invalid parameter:- this occurs in many commands when an extra or incorrect parameter is given. Line number too big:- This error appears when a conversion to BASIC results in a line number more than 16383 Margin out of range:- (during SET Format) Missing parameter No room for PF key:- (during SET PFn text) No search string:- This happens when the / command is used without an argument before it is ever used with an argument. Number too big Out of Memory:- This can be issued either by BASIC or by the editor. When the editor issues this message it could mean either there is no room for changes made to the file (in which case some changes will be lost), or that there is not enough room in BASIC to convert the file to a program. The MOVE command may sometimes be used to remedy the situation. Target not found:- (in Locate and Change) Too many pending prefix commands:- This happens when more than five prefix commands are typed at once. Undefined: (label name):- This happens during conversion to BASIC when a label name is undefined. Undefined PF key:- (when a PF key is pressed) Unknown command Command History Commands are kept in a history stack which expands to 255 bytes. A command typed on the command line is put on the stack when ENTER or a PF key is pressed, unless there is an error. The = command is never put on the stack, however. Entering = (or pressing a PF key with that definition) causes the most recent command on that stack to be executed. Entering ? (or pressing a PF key with that definition) causes the most recent command to be returned to the command line. The cursor will be placed over the first character of this command. Typing a question mark over this and pressing ENTER (or again pressing a PF key defined with the ? command) retrieves the most recent command before that, and this will continue until the earliest command on the stack is reached. After this, the most recent command will again be displayed. Typing a number of question marks will skip back that many places in the command history. BASIC within the Editor The editor has special commands for working with BASIC files. A BASIC program written with the editor will be converted to BASIC (by the BASIC or RUN command) using the following rules 1. Tokenisation: A word typed in upper or lower case is tokenised if it is recognisable as a word which is not part of some other word (for example <> is always tokenised, a word such as inkey$ is always tokenised unless preceded by a letter, and a word such as print is always tokenised unless followed or preceded by a letter), with the following exceptions: a. words inside quotes or after REM tokens b. words at the starts of lines or statements (after colons) which are not commands (code 205 or less) c. the word OUT unless followed by a space (this is to allow OUT as an assembler statement which is not tokenised) 2. Line numbers: As the line number of a particular line within a file is likely to change, line numbers are not used in programs. Instead, labels are used. A label consists of the @ character followed by a sequence of alphanumeric characters. To identify a label with a line of the program (that is, to define a label), the label is placed at the beginning of the line in question, followed by a colon. At every point in the program where this label is used (whether before or after the line with which it is associated), it will be replaced during BASIC conversion with the BASIC line number of the line with which it is associated. This makes it possible to write complex GOTO and other statements which are always correct regardless of the program's line numbering system. If a BASIC or RUN command detects a syntax error in the BASIC (or if there is an error in a command line BASIC command), the message "Error in line" with the number if applicable is displayed, together with the BASIC text, in its tokenised form, with the syntax error marker at a position close to the error. The editor then waits for a keystroke before returning to the edit screen with the offending line made current (if applica- ble). The BASIC and RUN commands also issue the error message "Line number too big" if the BASIC line number of any line is more than 16383, and "Undefined: ..." if there is an undefined label. The current BASIC program may be converted into edit format by the GET command. All tokens will be expanded into upper case words and all control characters will be ignored. The line numbers of all GOTO, GOSUB, RUN, RESTORE, LIST, LLIST and SAVE ... LINE commands will be changed into labels (each consisting of the @ character followed by the line number in question) which will be defined in the usual way. In the vast majority of cases a program converted by GET will run perfectly when reconverted using BASIC. The following cases are converted correctly: a. single line number b. (line1 AND condition1)+(line2 AND condition2)+... c. line1*(condition1)+line2*(condition2)... d. LET var=lineno:...:GOTO var e. LET var=lineno:REM GOTO var Notes: 1. The GOTO in line d and e may be replaced by any word mentioned above 2. The GOTO in line e must be in token form 3. The LET in lines d and e must be at the start of the line, and the first letter of the variable must agree with that in the GOTO statement 4. Case e is used for LETs which do not have GOTOs immediately after them 5. the lineno in lines d and e may take the form of a, b or c. In the case of a possible error during conversion of line numbers, the message "Please check line" or "Unable to convert line" appears with the line number in question. These messages do not halt conversion. The Editor runs in 48K mode when entered from +3 BASIC, so that the commands SPECTRUM and PLAY are neither tokenised nor interpreted. Also, disk commands in programs will not work. The Editor supports most extended BASIC software tools which add their commands via the machine stack and also the commands added to a 48K spectrum by the Interface 1. The errors are intercepted not via the machine stack but via the input routine. This leaves the machine stack free for the extended BASIC software. The top of the machine stack usually points to the address of a routine for interpreting the extended commands; for ease of operation this should already be set when the Editor is entered (in which case the Query Errors command should reveal the error address) so that all the extended commands are accepted. It is, however, possible to set up this address on the machine stack from within the editor (provided the address is known) using the SET Errors command, so that for instance the software can be used when the editor is called from +3 BASIC. File Formats BASIC files should be saved and loaded using the BASIC commands, but the edit format files should also be saved using the editor commands. The editor files are saved as ordinary blocks of CODE. The lines of text are stored as normal ASCII codes, with a carriage return (code 13) character at the end of each. No line numbers are stored. After the carriage return which marks the end of the last file line, there is an end of file character (code 255). The code saved by the editor includes this character as the last byte. All trailing spaces should be removed by the editor, but in a blank line there is always one space. If random code is loaded into the editor, unpredicta- ble results may occur. Codes greater than 164 (graphic U) will be printed as protected characters, while codes less than 32 (except codes 0 - NULL - and 13 - carriage return) will be printed as quotes. BUGS The following are bugs which I know about at the time of writing this file, and intend to fix sometime: Input and Power input modes are fragile, and in particular sometimes crash when prefix commands are used during input. When the last line of the file is current, Up n moves only n-1 lines up. Using the spltjoin function with the cursor to the right of the last line of the file does not cause an error but joins the end of file marker to the end of the line. (spltjoin again remedies the situation). The BAck command does not appear to make very good estimates and sometimes only scrolls half a page. The / locate command when used with no parameter sometimes appears to say "No search string" incorrectly. The locate and SCHange commands do not locate the occurrence of a string immediately at the start of the line in which is the cursor. The SET Format width command (when used without the J|N parameter) sets Justify to N. When a file is loaded, the current line number is not reset. This may result in the End of File line being the top line of the display, although it is not strictly the current line. Unpredictable results may occur unless a Top or :n command is executed. The following are bugs or points to watch out for, which at the present time it is not my intention to fix: If a line is changed, part of which is off the screen, only the visible part is stored in the file at the next press of ENTER or a PF key. If a changed line is moved wholly off the screen by typing in the middle of the screen, the changes are lost. If it is moved partly off the screen, that portion which is not displayed is lost. The d prefix command does not move the cursor on the screen, so that while d prefixes are pending, it is inadvisable to use a command which depends on the position of the cursor. The formatting program occasionally breaks words over lines, adding a hyphen. This is not always desirable (especially in the case where a long word is separated from the punctuation marks which follow it). In additio- n, when a paragraph containing a hyphenated word is reformatted, the word may be moved all onto one line, but the hyphen and the space are not removed. The formatting routine has occasionally separated a sentence from the single full stop which follows it; this is because the end of line character which follows the full stop is mistaken for a non-blank character, so is deemed not to fit on the same line. The NEW, GET and Load commands do not check to see whether the file has been altered. This may possibly result in an accident. There is at present no form of the Change and Locate commands which searches for a word or sentence, recogni- sing that it must be preceded and followed by a selecti- on of possible characters (space or punctuation mark or end of line character). There is also no Change command which replaces text preserving the case structure (for example the capital letter at the start of a sentence). This must be dealt with at present by using locate to search out all occurrences of the most generalised string (for instance a word without its surrounding spaces) and using SCHange to change all those that are required (possibly doing some manual editing to restore the case structure).