______________________________________________________________ This is an ASCII version of a document which is designed to be printed as an A5 book. As a result, some of the typographic distinctions that are made in the book are not represented here - for example, there is no italic. The page numbers have been retained so that the contents and index can be used. ______________________________________________________________ UNIVERSITY OF CAMBRIDGE COMPUTING SERVICE SPECIFICATION OF THE NE TEXT EDITOR by Philip Hazel Computer Laboratory New Museums Site Pembroke Street Cambridge CB2 3QG United Kingdom Tel. +44 223 334600 1st edition, July 1994 Copyright (c) University of Cambridge Computing Service 1994 CONTENTS 1. Introduction 1 2. Terminology 3 3. System dependencies 4 3.1 The NE command 4 3.2 File names 4 3.3 User initialization 4 3.4 Keystrokes 5 3.5 Network delays 5 3.6 Memory usage 5 4. Screen editing 6 4.1 Getting started 6 4.2 The screen display 7 4.3 Refreshing the screen 8 4.4 Moving about the file 8 4.5 Changing data on the screen 11 4.6 Undeleting lines and characters 14 4.7 Overstriking characters 14 4.8 Editing wide lines 14 4.9 Editing non-printing characters 16 4.10 Multi-line editing 16 4.11 Cutting, pasting and block deletion 18 4.12 Text blocks 19 4.13 Rectangular blocks 21 4.14 Re-formatting paragraphs 23 4.15 Help information 24 4.16 Entering NE command lines 25 4.17 Multi-buffer editing 28 4.18 Leaving NE 29 4.19 Summary 30 5. The NE command 31 5.1 Tab support 33 5.2 Editing binary files 33 6. NE command lines 36 6.1 Format of command lines 36 6.2 Continuation of command lines 37 6.3 Format of common arguments 37 6.4 Obeying commands while screen editing 38 6.5 Long command lines while screen editing 40 6.6 Refreshing the screen 40 6.7 Summary 41 7. Context matching 42 7.1 Qualified strings 42 7.1.1 The B qualifier 43 7.1.2 The E qualifier 43 7.1.3 The H qualifier 43 7.1.4 The L qualifier 43 7.1.5 The N qualifier 43 7.1.6 The P qualifier 44 7.1.7 The R qualifier 44 7.1.8 The S qualifier 44 7.1.9 The U qualifier 44 7.1.10 The V qualifier 44 7.1.11 The W qualifier 45 7.1.12 The X qualifier 45 7.1.13 The repeat qualifier 45 7.1.14 The column qualifier 45 7.1.15 Combining qualifiers 46 7.1.16 Matched strings 46 7.1.17 Examples of qualified strings 46 7.2 Search expressions 46 7.3 Regular expressions 48 7.4 NE-style regular expressions 48 7.4.1 Wild character 49 7.4.2 Quoting character 49 7.4.3 Repetition 49 7.4.4 Character classification 50 7.4.5 Character ranges 50 7.4.6 Hexadecimal characters 50 7.4.7 Negation 51 7.4.8 Grouping 51 7.4.9 Alternation 52 7.4.10 Negated alternation 52 7.4.11 Summary 52 7.4.12 Formal syntax 53 7.5 Unix-style regular expressions 54 7.5.1 Wild character 54 7.5.2 Quoting character 54 7.5.3 Repetition 54 7.5.4 Character sets and ranges 55 7.5.5 Negation 55 7.5.6 Grouping 56 7.5.7 Alternation 56 7.5.8 Beginning and end of line 56 7.5.9 Summary 57 7.5.10 Formal syntax 57 8. Character string insertions 58 8.1 Wild replacements for regular expressions 58 8.2 Other wild replacements 60 8.3 Hexadecimal insertion strings 60 9. Procedures 61 10. Single-character commands 62 10.1 The ? command 62 10.2 The > and < commands 62 10.3 The # command 63 10.4 The $, % and ~ commands 63 10.5 Single-character commands in line mode 63 11. Search commands 65 11.1 The F command 65 11.2 The BF command 66 11.3 The DF command 67 11.4 Repeating search commands 67 12. Current point movement 68 12.1 The > and < commands 68 12.2 The BACK command 68 12.3 The M command 69 12.4 The N command 70 12.5 The P command 70 12.6 The PA and PB commands 70 12.7 The PLL and PLR commands 71 12.8 The TOPLINE command 71 13. Changing the current line 73 13.1 The A, B and E commands 73 13.2 The DTA and DTB commands 74 13.3 The LCL and UCL commands 74 14. Inserting text into the file 75 14.1 The I command 75 14.2 The ICURRENT command 75 14.3 The ILINE command 75 15. Splitting and joining lines 77 15.1 The SA and SB commands 77 15.2 The CL command 77 16. Deleting parts of the file 78 16.1 The DLINE command 78 16.2 The DREST command 78 17. Restoring deleted text 79 18. Formatting commands 80 18.1 The CENTRE command 80 18.2 The RMARGIN command 80 18.3 The FORMAT, BEGINPAR and ENDPAR commands 81 19. Global changes 83 19.1 The GA, GB, and GE commands 83 19.2 Interactive global commands 84 19.3 Non-interactive global commands 85 19.4 Continuing after a match 86 19.5 Null strings in global commands 86 19.6 Globals with margins or long lines 86 19.7 The global marker 87 20. Buffer handling 88 20.1 The TITLE command 88 20.2 The RENUMBER command 88 20.3 The DETRAIL command 88 20.4 The NEWBUFFER command 89 20.5 The MAKEBUFFER command 89 20.6 The BUFFER command 90 20.7 The NAME command 90 20.8 The DCUT command 90 20.9 The DBUFFER command 90 20.10 Copying between buffers 91 21. File operations 92 21.1 Loading a new file 92 21.2 Inserting files 92 21.3 Saving files 93 21.4 The WRITE command 93 21.5 The BACKUP command 94 22. Editing large files 95 23. Conditional commands 96 24. Looping commands 98 24.1 The WHILE and UNTIL commands 98 24.2 The REPEAT command 98 24.3 The LOOP and BREAK commands 98 25. Information displays 100 25.1 Contents of a buffer 100 25.2 Information about buffers 100 25.3 Command information 101 25.4 Keystroke information 101 25.5 Control keystrokes 102 25.6 Extra keystrokes 102 25.7 Function keystrokes 102 25.8 Keystroke actions 102 25.9 Function keystrings 103 26. Keyboard interruptions 104 26.1 Generating an interruption 104 26.2 The effect of an interruption 104 26.3 Interruptable commands 104 26.4 The ATTN command 105 27. Leaving NE 106 28. Changing default operations 109 28.1 The AUTOALIGN command 109 28.2 The CASEMATCH command 109 28.3 The CUTSTYLE command 110 28.4 The OVERSTRIKE command 111 28.5 The PROMPT command 111 28.6 The READONLY command 112 28.7 The SET command 112 28.8 The WARN command 113 28.9 The WORD command 113 29. Keystroke commands 114 29.1 The MARK command 114 29.2 The CSU and CSD commands 114 29.3 The ALIGN command 114 29.4 The CLOSEBACK and CLOSEUP commands 114 29.5 The DLEFT and DRIGHT commands 115 29.6 The DLINE command 115 29.7 The CUT and COPY commands 115 29.8 The PASTE command 115 29.9 The DMARKED command 115 29.10 The ISPACE command 116 30. Changing keystroke defaults 117 30.1 Function keystrings 118 30.2 Keystroke binding 118 31. Calling other programs 122 32. Error handling 123 33. Line-by-line editing 125 33.1 Interactive line-by-line editing 125 33.2 Non-interactive line-by-line editing 125 33.3 Verification output 125 33.4 Format of verification output 126 33.5 The T and TL commands 126 33.6 The COMMENT command 127 33.7 The C command 127 33.8 The CBUFFER and CDBUFFER commands 127 34. Unix interface 128 34.1 Using NE as a filter 128 34.2 Environment variables 128 34.3 Exit codes 129 34.4 File names 129 34.5 Emergency files 130 34.6 File backup 130 34.7 Shell commands 130 34.8 Interruptions 130 34.9 Terminal types 131 34.10 Terminal capabilities 131 34.11 Keyboard interruptions 135 34.12 xterm 135 34.13 Fawn II 136 34.14 TTP and Hydra 136 35. RISC OS interface 137 35.1 NE on the desktop 137 35.2 Taskwindows 138 35.3 File types 139 35.4 Initialization 139 35.5 Screen modes 140 35.6 File names 140 35.7 Emergency files 140 35.8 File backup 140 35.9 Return codes 140 35.10 Interruptions 141 35.11 Non-printing characters 141 35.12 Keystrokes 141 35.13 Calling other programs 143 36. MS-DOS interface 144 36.1 File handling 144 36.2 Emergency files 144 36.3 File backup 144 36.4 Automatic initialization 144 36.5 Screen display 144 36.6 Screen colours 145 36.7 Keystrokes 145 36.8 Interruptions 147 36.9 Calling other programs 147 37. Logical keystroke summary 148 38. Command summary 149 39. Argument format summary 152 39.1 String delimiters 152 39.2 String qualifiers 152 39.3 Regular expressions 152 39.3.1 NE-style regular expressions 152 39.3.2 Unix-style regular expressions 153 39.4 Regular expression replacements 153 39.5 Hexadecimal insertions 154 Index 155 1. INTRODUCTION NE is a text editor that is designed to run on a wide variety of machines, from large servers to personal workstations. Its main use is expected to be as an interactive screen editor. However, it can also function as a line-by-line editor, and it is programmable, so it can be run non-interactively as a text manipulation tool. NE is a re-implementation of a previous editor that was called E. It is to a large extent upwards compatible, though there are some features of E that are not provided in NE. On the other hand, there are some additional features of NE that are not part of E. Although NE has been in use on several systems for some time, further development is not ruled out, and changes may yet occur. This document describes version 1.00. Implementations of NE currently exist for the following oper- ating systems and computers: . Sun's SunOS4 (Solaris 1) and SunOS5 (Solaris 2) operating systems for Sun computers. . DEC's OSF1 operating system for DEC Alpha computers. . Silicon Graphics' IRIX 5 operating system for SGI computers. . Hewlett Packard's HP-UX operating system for HP9000 computers. . The Linux free Unix system for IBM PCs and compatibles. . The MS-DOS operating system for IBM PCs and compatibles. . Acorn's RISC OS 3 operating system for the Archimedes and RISC PC ranges of computers. It is expected that ports of NE to other Unix systems will be done in due course. NE is a large program with many facilities. They are described in this document grouped by function, but first there are definitions of some terminology and a description of the areas in which there are differences between the various versions of the program. The chapter which follows describes how to use the screen editing features of NE, while subsequent chapters cover the many different commands available. Then there is detailed information for each different implementation, and finally there are keystroke and command summaries. -1- In many places in the text there are cross-references to particular NE commands. These are given simply as a command name in square brackets, for example [RMARGIN]. Experience with a number of other editors influenced the design of E and NE. Similar facilities are frequently encoun- tered, and it is difficult to trace the origins of many of them. The operations on rectangles and some of the operations on single lines and groups of lines are taken from the Curlew editor implemented by the University of Newcastle-Upon-Tyne in the mid-1980s. Members of the Computer Laboratory and other computer users in Cambridge have contributed many useful ideas and criticism to the design process over a number of years. -2- 2. TERMINOLOGY Several terms which are used with particular meanings in the rest of this document are defined in this chapter. A computer screen indicates the point at which the next character will be written by a mark known as a cursor. This may be an underline-like shape or a vertical line, or it may be a solid blob. It may flash or be constant in intensity. When text is being edited on the screen, the cursor position marks the point in the text at which changes are made. This is called the current point in the file. Any references in this document to the cursor position or moving the cursor should be understood as also referring to the current point. The term current line is also used to refer to the line of text containing the current point (that is, the line on which the cursor is placed). When NE is obeying commands (as opposed to accepting screen editing operations) the current point and the current line may change without reference to an actual cursor. The word scroll is used to describe NE's action in moving text on the screen. Blocks of lines can be scrolled upwards or downwards, and also to the left or to the right. A buffer in NE is an area of main memory in which lines of text can be held for editing. A file which is to be edited is read into a buffer to be modified; subsequently the buffer's contents may be written back to a file. NE is capable of handling more than one buffer at once. A keypress is the action required to generate a single character from a keyboard. In many cases it involves pressing a single key - however, in some cases a second (and sometimes even a third) key must be held down while a 'primary' key is pressed. When such a keypress is referred to, the names of the keys are separated by a slash. For example, the keypress CTRL/A involves holding down the key marked CTRL while press- ing the key marked A. The character engraved on the key top is normally used when referring to individual keys. In one or two cases where this could be confusing (for example, backslash) the name of the character is used instead. The four keys with arrows on them that appear on many keyboards are referred to as UP, DOWN, LEFT and RIGHT. The word keystroke is used to refer to keyboard operations which are seen by NE as a single action but which may on some terminals require more than one keypress. For example, on some keyboards it is necessary to press the ESC key followed by the digit one (two keypresses) in order to generate the keystroke FUNCTION-1, whereas on other keyboards a single keypress of a function key may generate this keystroke. -3- 3. SYSTEM DEPENDENCIES Full details of the system-dependent features for each implementation of NE are given near the end of this document. This chapter describes the areas in which differences might occur. 3.1 The NE command In all current implementations it is possible to invoke NE to update a file interactively by means of the command where the file name follows the standard conventions of the system. An installation can choose any command name that it prefers, but the name NE is usually chosen. Other options may be given on the command line, for example, to move to a particular line in the file before displaying the first screen. The syntax for all current implementations requires a hyphen before keywords in the command line, for example: ne -opt "" When NE is to be used non-interactively, the file containing the NE commands to be obeyed is normally specified by the keyword -with on the command line, while the destination for error messages and verification output is specified by the keyword -ver. For example, a typical non-interactive invo- cation might be ne myfile -with edits -ver /tmp/messages 3.2 File names File names appear in some of NE's commands, but unless they contain the semicolon character or start with two backslashes, which is NE's comment indicator, they can normally be typed in the standard format used by the underlying operating system. Delimiter characters are provided for handling file names that cause trouble. 3.3 User initialization It is possible to set up a sequence of NE commands to be obeyed automatically whenever NE is entered. In Unix systems this is done by setting the environment variable NEINIT; other implementations may provide this feature in a different way, or not at all. -4- 3.4 Keystrokes NE can be used from many different types of terminal, each of which has its own specific keyboard layout. These are normally ASCII keyboards, containing a key marked CTRL and (usually) a key marked DELETE in addition to the usual printing keys. As far as is possible, the different implementations of NE make use of the same keystrokes for the same functions, but inevitably there are differences between them. As well as the keystrokes for inputting ordinary printing characters, all ASCII keyboards permit the use of the CTRL key with printing characters (though in some cases not all possible combinations are useable), and many of them contain function keys. Editing operations that are activated by pressing special keys are described in terms of logical control keystrokes, whose names are shown in capitals enclosed in curly brackets, for example, {SCROLL-UP}. The actual keys used for these keystrokes vary from keyboard to keyboard and operating system to operating system. Examples of the relationships between logical control keystrokes and actual keystrokes are often given in the main text of this manual, while complete lists are given in the system-dependent and terminal-dependent chap- ters near the end. It is possible for the user to change the relationship between actual and logical control keystrokes in many cases [KEY]. The examples given in this manual assume the standard configuration. 3.5 Network delays When NE is being run on a remote computer system, keystrokes are handled one by one by the remote machine as they are entered, and all screen updating is under the control of the remote program. Network delays manifest themselves as sluggish responses to individual keystrokes. The amount of type-ahead that is available depends on the amount of buffering in the network. 3.6 Memory usage NE operates by holding the file or files that it is editing in main memory, though a file is not necessarily all read in at once. Different systems have different amounts of memory, and this affects the amount of data that can be processed at one time. -5- 4. SCREEN EDITING This chapter describes the screen editing facilities. They are sufficient for carrying out many simple interactive editing jobs. New users of NE are recommended to try out these facilities and become familiar with them before reading the rest of this document. It is assumed that all the default options are being used. Keystroke names given in capitals enclosed in curly brackets (such as {SCROLL-UP}) refer to logical keystrokes, whose correspondence with actual keys depends on the particular keyboard and version of NE in use, and how the user has configured it. As well as those logical keystrokes that have pre-determined functions, such as {SCROLL-UP}, there are 60 logical keystrokes whose effect is to obey a string of NE commands which is stored in a function keystring [FKEYSTRING]. These logical keystrokes have names of the form {KEYSTRING-}, where is number between 1 and 60. When the keyboard contains function keys, these are usually bound to the corre- sponding logical keystroke, but they do not have to be. Function keys can be bound to pre-determined actions, and other control keys can be made to invoke function keystrings. The common default actual keystroke is normally given with the first mention of each logical keystroke. This is the keystroke that will normally be bound to the logical keystroke by default, provided the keyboard supports it. The descriptions which follow assume NE is being used in an environment where it is initiated by a typed command, and takes over the whole screen for displaying the text. One implementation of NE (for Acorn's RISC OS) also runs in a windowing desktop environment, where things are somewhat dif- ferent. Details are given in the relevant system-specific chapter. 4.1 Getting started To edit a file interactively using NE, enter the command ne There may be a short pause, especially if using a remote computer, and then the screen will be cleared and re-written with the first lines of the file, in the format described below. Any error in the command, for example, the naming of a non-existent file, provokes a system-dependent error message. If the command name is not followed by a file name, then NE is entered with no existing lines of text to edit, and the text area of the screen is empty. New text can be created using the -6- editing operations described below, and when editing is com- plete, a file name can be given for the output (see the section entitled Leaving NE below). This is one way of creating a new file using NE. Alternatively, a new file can be created by using the -to keyword on the NE command line, without naming an existing file for editing. For example: ne -to 4.2 The screen display An example of a typical screen display on entry to NE is shown below. Because of limitations of space on the page, it is shown as 40 columns wide and 10 lines deep, though most versions of NE operate with screens that are at least 80 columns wide and 24 lines deep. Characters that would appear in inverse video on the screen are shown as capital letters. ----*----1----*----2----*----3----*----| This is the first line of the file. The second line of the file is a bit loN The second line of the file is longer than the width of the screen. This is the last line of the file. END OF FILE 1 IRUA TEST ---2----*----3----*----| NE version 0.098/0.11 (22-Apr-1994) The screen display consists of four sections. The top line is an inverse video line containing indications of column num- bers. Every tenth column contains a digit indicating the decade - column 30 contains the digit 3 for example. At the halfway point in each decade there is an asterisk, while the rest of the positions are filled with minus signs. When NE is initialized, the last column in this separator line contains a vertical bar character. This marks the position of the first character beyond the right-hand margin about which more will be said later [RMARGIN]. Most of the rest of the screen is used to display lines from the file being edited. This is called the text area. For lines that are wider than the screen, only the initial part is shown, with the last character in inverse video to indicate that there are more characters in the line. The second text line in the example above is such a line. At the end of the file the text 'End of file' is displayed in inverse video, usually on a line by itself. Below the data lines there is another inverse video separator line with column indicators, but also containing additional information. At the extreme left a number is often displayed. This is the number of the line on which the cursor is resting. -7- Line numbers are counted from the start of the file when it is read; they do not change when lines are deleted or inserted into the edited text [RENUMBER]. Undisturbed lines retain their original number at all times. If the cursor is on a newly-inserted line, blanks are displayed at the beginning of the lower separator line. Three capital letters follow the line number - initially they are 'IRU'. These indicate the state of certain editing options, and are explained in detail later on. The first one indicates whether new characters will inserted into the text (I) or will overstrike it (O) [OVERSTRIKE], the second indi- cates whether portions of text that are cut out will replace what is in the cut buffer (R) or be appended to it (A) [CUTSTYLE], and the third indicates whether text searches are to be independent of case (U) or verbatim (V) [CASEMATCH]. A fourth letter (another 'A') is present if auto-alignment has been enabled [AUTOALIGN]. Following the indicator letters a file name is usually dis- played. This is the name of the file to which the edited text will be written at the end of the editing session. In the simple case it is the name of the file which is being edited. The final line of the screen is used to display messages as editing proceeds, and also for command input, as described later. Initially it contains an identification of the version of NE in use. 4.3 Refreshing the screen When using NE on a timeshared system, the screen may sometimes get overwritten by extraneous messages, such as warnings from operators. When this happens, the keystroke {REFRESH} can be used to cause NE to re-write the entire screen. By default, {REFRESH} is bound to CTRL/D. 4.4 Moving about the file When NE is entered without any options, the cursor is pos- itioned at the top left-hand corner of the text being edited. It can be moved about the screen by pressing any of the four 'arrow' keys: {UP}, {DOWN}, {LEFT} and {RIGHT}. On keyboards containing real arrow keys these keystrokes do correspond to the actual arrow keys UP, DOWN, LEFT and RIGHT; on other keyboards CTRL keystrokes are normally used. Special actions take place if an attempt is made to move outside the text display area. . Pressing {UP} at the top of the area has no effect if the top line in the display is the first line of the file. Otherwise it causes NE to move backwards in the file by one or more lines [SET AUTOVSCROLL]; the text on the -8- screen is scrolled down and new text is displayed at the top. The cursor is left on the line before the one it was previously on. . Pressing {DOWN} at the bottom of the display area causes NE to move forwards in the file by one or more lines [SET AUTOVSCROLL] unless the bottom line is the end-of-file line; the text on the screen is scrolled up and new text is displayed at the bottom. The cursor is left on the line following the one it was previously on. . Pressing {LEFT} at the left-hand edge of the screen causes the cursor to move to the end of the previous line, unless the screen has been scrolled right, in which case a leftwards scroll takes place. If this keystroke is used at the beginning of the top line on the screen, NE scrolls the screen to bring the new current line into view. . Pressing {RIGHT} at the right-hand edge of the screen causes the screen to scroll to the right, that is, the lines are displayed starting from a character other than the first, enabling characters that were previously off the right-hand end to be displayed. The arrows are not the only keystrokes for moving the current point around the file. The following additional horizontal movements are provided: . The {WORD-LEFT} keystroke moves the cursor to the start of the current word if it is in the middle of a word, or to the start of the previous word otherwise. This keystroke is not associated with an actual keystroke by default. . The {WORD-RIGHT} keystroke moves the cursor to the start of the next word. This keystroke is not associated with an actual keystroke by default. . The {TAB} keystroke moves the cursor to the next tab position to the right. If the keyboard contains a key labelled TAB, it is normally used for the {TAB} keystroke. Otherwise CTRL/I is used. Tab positions are set at every eighth column. The {TAB} keystroke does not cause the insertion of tab characters into the file. If the right-hand edge of the screen is reached, the action is the same as for the {RIGHT} keystroke. . If the {PREVIOUS-TAB} key is pressed (default SHIFT/TAB or CTRL/TAB) the cursor moves to the previous tab pos- ition. If the left-hand edge of the screen is reached, the action is as for the {LEFT} keystroke. . The keys {FIRST-CHAR} and {LAST-CHAR} (default CTRL/LEFT and CTRL/RIGHT) cause the cursor to move, within the current line, to the first printing character on the -9- screen or to just past the last printing character, respectively. If the line contains no printing charac- ters, both these keystrokes move the cursor to the left of the screen. If there is a printing character in the final column on the screen, {LAST-CHAR} puts the cursor under it, as it cannot put it beyond it. . If {SCREEN-LEFT} is pressed (default CTRL/BACKSLASH), the cursor is moved to the left-hand edge of the screen. Note that there is no difference between {FIRST-CHAR} and {SCREEN-LEFT} unless the current line begins with spaces. In this case {FIRST-CHAR} moves the cursor to just after the leading spaces, while {SCREEN-LEFT} moves it to the left-hand edge of the screen. Additional vertical movements, which in general cause the screen to be re-written, are also provided. They are as follows: . {SCROLL-UP} and {SCROLL-DOWN} (defaults SHIFT/UP and SHIFT/DOWN or CTRL/J and CTRL/K) cause NE to move up or down the file by almost one screenful of lines. If the current point is near the start or end of the file the only effect may be to move the cursor to the first or last line, as appropriate. When one of these keystrokes occurs, if the cursor is on one of the lines that is still visible on the revised screen (that is, if it was originally near the bottom for {SCROLL-DOWN} or near the top for {SCROLL-UP}) then it remains on the same text line afterwards, but on a different screen line. Otherwise the cursor stays on the same screen line. This ensures that scrolling down a file and then back up again (or vice versa) brings the cursor to the same place. The horizontal position of the cursor always remains unchanged. . {SCROLL-TOP} and {SCROLL-BOTTOM} (default CTRL/UP and CTRL/DOWN) can be used to move to the beginning or end of the file respectively. The cursor ends up either on the first line or on the end-of-file line, as appropriate. Its horizontal position is not changed. . The keystroke {KEYSTRING-8} has the same effect as {SCROLL-BOTTOM}, except that the cursor is also moved to the beginning of the end-of-file line. Similarly, the keystroke {KEYSTRING-18} moves the cursor to the start of the first line of the file. . The keystroke {KEYSTRING-58} (default CTRL/CIRCUMFLEX) causes the screen to be re-displayed with the current line as the first line on the screen. The current point in the file is not altered [TOPLINE]. . The keystroke {KEYSTRING-59} (default CTRL/UNDERLINE) causes NE to return to the region of the file where the -10- last change was made. The 20 most recent areas of change are available via this keystroke. If the file has not been changed, this keystroke has no effect [BACK]. In addition to these keystrokes, there are a number of NE commands for moving about the file; these are described later [>, <, BACK, BF, CSD, CSL, F, M, N, P, PA, PB, PLL, PLR, TOPLINE]. 4.5 Changing data on the screen Typing any of the normal printing characters (or SPACE) causes the character to be inserted into the line immediately before the cursor position. The remainder of the line is moved one position to the right, and so is the cursor [OVERSTRIKE]. This may have the effect of pushing a character off the right-hand edge of the screen, but though it is now invisible, it does not get lost. Note that, on most keyboards, holding down a key causes multiple insertions to occur. If any characters are inserted into the end-of-file line, it is converted into a data line, and a new end-of-file line is created. If a character is typed when the cursor is just beyond the right-hand margin, NE splits the current line at the nearest previous space character in the line. The position of the first character beyond the margin is indicated in the separ- ator lines by a vertical bar. Characters after the splitting point are placed on a new line, for which room is made by scrolling the screen. For example, suppose the top of the screen is as follows, with the cursor at the end of the first line, immediately following the letter 'l': ----*----1----*----2----*----3----*----| The quick brown foxes jumped over the l The slow red badgers hopped about. The next character to be typed by the user is beyond the right-hand margin. Suppose the letter 'a' is typed. The screen will then be changed to the following: ----*----1----*----2----*----3----*----| The quick brown foxes jumped over the la The slow red badgers hopped about. with the cursor after the letter 'a' on the second text line. The user can therefore type text continuously, leaving NE to split lines when they become full. This feature is known as power typing. Automatic line splitting happens only when a data character is typed immediately after the right-hand margin. If, for example, {RIGHT} is used to move the cursor further past the -11- margin to the right, then subsequent data characters are simply added to the line in the normal way. The {SPLIT-LINE} key is used to request that a line be split at the current cursor position. In all current implementations {SPLIT-LINE} is bound to the RETURN key. Normally lines below the current one are scrolled down to make room, but if the current line is near the bottom of the screen, lines above it are scrolled up instead [SET SPLITSCROLLROW]. When a line is split, either as a result of the power typing feature, or because of an explicit use of {SPLIT-LINE}, the second part of the line becomes a new line, starting in column one. It is possible to arrange that such lines are automati- cally given the same indentation as the previous line. See the description of the AUTOALIGN command in the section entitled Entering NE command lines below. The {DELETE-PREVIOUS} and {DELETE-HERE} keystrokes provide two complementary ways of deleting individual characters. {DELETE- PREVIOUS} deletes the character immediately before the cursor and moves the cursor one place to the left, while {DELETE- HERE} deletes the character at the cursor and leaves the cursor position unchanged. In both cases the line is closed up to remove the space where the character was. Holding down either of these keys causes multiple deletions. Many keyboards have a key labelled DELETE or DEL. Unfortunately, conventions as to whether this key is used for {DELETE-PREVIOUS} or {DELETE-HERE} vary from system to system. The default keystroke assignment for NE normally follows the local system convention. In Unix implementations, {DELETE-PREVIOUS} is by default bound to the DELETE or DEL key. {DELETE-HERE} is bound to CTRL/Y; some terminals provide a dedicated alternative key. If {DELETE-PREVIOUS} is pressed when the cursor is at the beginning of a line, it causes that line to be joined on to the end of the previous line. Pressing {DELETE-PREVIOUS} at the beginning of a line is in effect a different logical keystroke, and this is given its own name, {CONCATENATE}, which can be bound to a different keystroke if required. When concatenation occurs, the screen is scrolled up one line and a new line is displayed at the bottom. The cursor remains under the same character, in its new position. An erroneous {CONCATENATE} can be cancelled by pressing {SPLIT-LINE}, and an erroneous {SPLIT-LINE} can be cancelled by pressing {CONCATENATE}. For most terminals this means that the normal keystroke for immediately cancelling an erroneous data charac- ter also applies to the RETURN key, though cancellation may not be exact if the auto-alignment facility is being used [AUTOALIGN]. -12- If {CONCATENATE} is pressed on the end-of-file line, the only effect is to move the cursor to the end of the previous line. The {DELETE-LEFT} and {DELETE-RIGHT} keystokes (by default CTRL/X and CTRL/V) provide two complementary ways of deleting many characters on a line. The former deletes from the character immediately before the cursor to the start of the line, while the latter deletes from the character at the cursor to the end of the line. The {DELETE-LINE} keystroke (by default CTRL/U) deletes all the characters on the current line, both to the left and to the right of the cursor, and in addition closes up the file vertically to remove the resulting blank line. The screen is scrolled up one line and a new line displayed at the bottom. Four final keystrokes for operating on individual lines per- form more specialized actions. They are of most use when operating on several lines at once (see Multi-line editing below, where examples of their use are given), but are described here because in the simple case they act on a single line. {ALIGN-LINE} (default CTRL/A) has the effect of aligning the current line with the cursor - the line is shifted to the right by inserting spaces at its start, or to the left by removing spaces at its start, until the first non-space character in the line is at the cursor position. {ALIGN-PREVIOUS} (default CTRL/Z) has the effect of aligning the current line with the previous line - the line is shifted to the right by inserting spaces at its start, or to the left by removing spaces at its start, until the first non-space character is in the same column as the first non-space character of the previous line. The cursor is moved to the alignment point. {CLOSE-UP} (default CTRL/C) has the effect of closing up the line at the cursor position - if there are one or more space characters starting at the cursor position, these are deleted, and the remainder of the line is shifted left so that the first non-space following the cursor position is now at the cursor position. Note that {CLOSE-UP} is equivalent to {ALIGN- LINE} if the cursor is at the left-hand edge of the screen. {CLOSE-BACK} (default SHIFT/DELETE) has the effect of closing up the line leftwards, by deleting any spaces immediately before the cursor position, and shifting the remainder of the line to the left. The cursor remains on the same character as before, but moved to the left if any spaces were actually deleted. -13- 4.6 Undeleting lines and characters When characters or lines are deleted, NE does not discard the data immediately. Up to 100 deleted lines are remembered, in reverse order. Deleted characters are held in a packed form, and up to 64 consecutive ones can be held in one 'line' for this purpose. The keystroke {KEYSTRING-4} causes NE to insert the most recently deleted thing back into the file [UNDELETE]. Undeleted characters are inserted back into the text at the current point, and NE remembers whether they were deleted forwards or backwards so that a sequence of deletes followed by a sequence of undeletes should put the text back as it was. Undeleted lines are treated as text to be inserted at the current point. Note that this is not a general 'undo' feature. Text deleted with commands such as E/A//B is also added to the undelete stack, as is text cut out with the DELETE command (the CTRL/Q keystroke). Text cut or copied to the cut buffer is not added to the undelete stack. 4.7 Overstriking characters In its default configuration, NE always inserts newly-typed characters into existing text, opening up the line to make room for them. This is the safest mode of operation, because it lessens the possibility of accidentally deleting charac- ters. However, when the text that is being edited is in a fixed format, it is sometimes more convenient to operate in overstrike mode, where newly-typed characters overstrike (i.e. replace) existing characters on the screen. NE can be switched from insert mode to overstrike mode, and vice versa, by pressing {KEYSTRING-60}. This is normally bound to the keystroke CTRL/O by default. The first of the three capital letters in the bottom separator line shows which of these two modes NE is in at any one time, displaying 'I' in insert mode and 'O' in overstrike mode. 4.8 Editing wide lines If the file being edited contains lines that are wider than the screen, there are some differences in the behaviour of NE. When any such line is displayed, the last character on the screen is shown in inverse video, to indicate that it is not in fact the last character of the line. NE operates with a right-hand margin, which initially is set at one less than the screen width, and the first position beyond it is indicated in the separator lines by a vertical bar character. -14- The margin controls where the power typing feature comes into effect, but (unlike the original E editor) it does not prevent editing from taking place to the right of it. To disable automatic line splitting, the keystroke {KEYSTRING-10} is used. The vertical bar in the separator lines changes to a backslash. This indicates that the margin, while still at the same position, has been disabled. Pressing {KEYSTRING-10} a second time re-enables the margin. A number of keystrokes may cause changes of the horizontal position of the 'window' on the file. When a line is split by the {SPLIT-LINE} keystroke, there is a movement back to column one if necessary. When lines are concatenated by pressing {CONCATENATE} (usually implemented as {DELETE-PREVIOUS} when the cursor is in column one), there may be a movement to the right if the previous line is longer than the screen width. Movement to the left or right can be explicitly requested by means of the keystrokes {SCROLL-LEFT} and {SCROLL-RIGHT} (default SHIFT/LEFT or CTRL/H and SHIFT/RIGHT or CTRL/L). In these cases the cursor is left in the same text column if it is still visible in the new window. For example, if the screen is showing columns 1-80 and the cursor is in column 53, after {SCROLL-RIGHT} it is still in column 53, though this is now in column 48 of the screen. If the old text column is not visible in the new window, the cursor is placed as near to it as possible. The keystrokes {FIRST-CHAR}, {LAST-CHAR} and {SCREEN-LEFT} operate only on the text that is displayed on the screen, and never cause any movement of the viewing window. {FIRST-CHAR} moves to the first visible non-space character of the current line, while {SCREEN-LEFT} moves to the left of the screen. {LAST-CHAR} moves just past the last visible non-space charac- ter of the current line, unless there is a non-space character at the right-most column on the screen, in which case it puts the cursor under it. There are also two keystrokes which move the cursor to the true beginning or end of the line, causing a horizontal scroll if necessary. These are {START-LINE} and {END-LINE}, defined by default to be SHIFT/CTRL/LEFT and SHIFT/CTRL/RIGHT. Not all keyboards support those keystrokes, so in addition two func- tion keystrings are defined to have the same effect. These are {KEYSTRING-6} and {KEYSTRING-16}. When the line is not wider than the screen, they are synonymous with {FIRST-CHAR} and {LAST-CHAR}. Movement up and down the file by means of the arrow keys, {SCROLL-UP}, {SCROLL-DOWN}, {SCROLL-TOP}, or {SCROLL-BOTTOM} does not affect the horizontal position of the window. However, when such movement occurs as a result of a command [F, BF, M, N, P, BACK], there may be a change of window position. The function keystrokes {KEYSTRING-8} and {KEYSTRING-18} (which move to the end and the start of the -15- file respectively) operate via the command mechanism, and move the cursor to the start of the appropriate line. The right-hand margin is also used by the FORMAT command. Its value may be changed by the RMARGIN command. Details of these facilities are given later. 4.9 Editing non-printing characters Files which contain non-printing characters can be processed by NE, but the way in which such characters are displayed on the screen is system- and terminal-dependent. Commonly, how- ever, a non-printing character is displayed as a question mark. (See the ? command for a way of displaying the hex codes of non-printing characters.) Some implementations of NE allow non-printing characters to be input directly from the keyboard during screen editing, while others may not. They can, how- ever, always be inserted into the file using the A, B, E, or ILINE commands which are described later on. 4.10 Multi-line editing Certain keystrokes for editing individual lines can be made to operate (independently) on each of a sequence of lines. The following actions accomplish this: (1) Place the cursor anywhere on either the first or the last line of the sequence and press the {MARK-LINE} key (default CTRL/B). The message 'Bulk line operation started' appears in the message area at the bottom of the screen, and the character at the cursor position is displayed in inverse video [MARK LINE]. (2) Move the cursor to the line at the other end of the sequence. Then press one of the line-editing keys listed below. The operation is carried out on the current line, the line marked by {MARK-LINE}, and all the lines in between. The operations that can be performed on many lines at once in this way are as follows: . {ALIGN-LINE} (default CTRL/A): All the lines in the block are aligned horizontally with the position of the cursor when {ALIGN-LINE} is pressed. That is, spaces are added or deleted at the start of the lines as necessary, until the first non-space in each line is in the same column as the cursor [ALIGN]. . {ALIGN-PREVIOUS} (default CTRL/Z): All the lines in the block are aligned horizontally with the line that pre- cedes the block. The horizontal position of the cursor is not relevant; it gets set to the alignment position. -16- . {CLOSE-UP} (default CTRL/C): For each line in the block, if one or more spaces are present at the cursor column, they are removed and the line is closed up [CLOSEUP]. . {CLOSE-BACK} (default SHIFT/DELETE): For each line in the block, if one or more spaces precede the cursor column, they are removed, and the line is closed up [CLOSEBACK]. . {DELETE-LINE} (default CTRL/U): All the lines in the block are deleted, and the file is closed up vertically [DLINE]. . {DELETE-RIGHT} (default CTRL/V): For each line in the block, all characters at and to the right of the cursor position are deleted [DRIGHT]. . {DELETE-LEFT} (default CTRL/X or CTRL/DELETE or CTRL/BACKSPACE): For each line in the block, all charac- ters before the cursor position are deleted, and the line is closed up. The cursor ends up in column 1 and there may be a movement of the viewing window to the left [DLEFT]. When one of these operations is performed, the 'mark' which was set by pressing {MARK-LINE} is automatically deleted. Sometimes is is necessary to carry out a number of these functions on the same group of lines. In this case, {MARK- LINE} should be pressed twice before starting the operations. After the second press, the word 'operation' in the message at the bottom of the screen changes to 'operations', and the mark is no longer automatically deleted when any action is per- formed on the line group. When all the operations are done, {MARK-LINE} must be pressed a third time to remove the mark, except when the final operation is 'delete' ({DELETE-LINE}), which always automatically removes the mark. If {MARK-LINE} is pressed in error, the bulk line operation can be abandoned by pressing {MARK-LINE} twice more. As an example of the use of the multi-line editing facilities, suppose the screen contained the following lines: This is some messy unprocessed data which needs tidying up a bit. We only want to retain the second two columns, and we want them tidy. 123.45 67.98 100.00 xyz 999.00 45.87 456.78 pqr 456.86 88.23 854.67 abc To delete the four lines of text, press {MARK-LINE} with the cursor on the first line, move to the fourth line, and press {DELETE-LINE}. -17- If {MARK-LINE} is now pressed with the cursor anywhere on the new first line, and then {DELETE-LEFT} (delete to left of cursor) is pressed after moving the cursor to just after '86' on the last line, the entire first column of figures is deleted and the lines look as follows: 67.98 100.00 xyz 45.87 456.78 pqr 88.23 854.67 abc To align all the lines, press {MARK-LINE} (the cursor being still on the last line), then move to column 5, say, on the top line and press {ALIGN-LINE}. The lines become: 67.98 100.00 xyz 45.87 456.78 pqr 88.23 854.67 abc To tidy up the messy second column, press {MARK-LINE} (the cursor being now on the top line), then move to the bottom line at the start of '854' and press {CLOSE-UP}. The lines are now: 67.98 100.00 xyz 45.87 456.78 pqr 88.23 854.67 abc Finally, to remove everything except the columns of numbers, press {MARK-LINE}, then move to the top line just after '100.00' and press {DELETE-RIGHT}. The result is: 67.98 100.00 45.87 456.78 88.23 854.67 Certain types of more complicated editing operation, such as the deletion of the second column of a table, cannot be performed using the multi-line actions described in this section. For such operations rectangular blocks must be used (see below). 4.11 Cutting, pasting and block deletion It is often necessary to move text from one position in a file to another, or to make a copy of some text at a different point in the file. NE provides these facilities using a cut and paste model. Text is identified in the file, and then either cut or copied from the file into the cut buffer. The cursor is then moved to the point where insertion is to occur, and the text is pasted into the file. There is only one cut buffer, and successive cut or copy operations destroy any text that was previously in it [CUTSTYLE, DCUT]. The word 'paste' is perhaps a little misleading in this context because it has connotations of overlaying existing -18- text. In NE, a pasting operation inserts text into the file; it does not destroy any existing text, even if NE is operating in overstrike mode, as this mode applies only to newly-typed characters. If an attempt is made to leave NE while there is text in the cut buffer that has never been pasted, a warning is given, and the user is prompted for permission to proceed. A prompt is also issued if text in the cut buffer that has never been pasted is about to be overwritten by new text. The operation of deleting text from the file is provided in a similar manner to cutting or copying. However, in this case, the portion of the file that has been marked is discarded [UNDELETE]. When marking text for cutting, copying, or deletion, NE regards the end of the text as being just before the cursor position. Therefore, when indicating the beginning of a block, the cursor must be placed on the first character, but when indicating the end of a block, it must be placed after the last character. Two different views of text are supported by the cut, paste and deletion operations. It can either be considered as a stream of characters, with a notional 'newline' between lines, or it can be considered as a rectangular array. These differ- ent approaches are described separately in the following two sections. 4.12 Text blocks A text block is a piece of text viewed as a stream of characters, with notional 'newline' characters between lines. To cut, copy or delete such a block from the file being edited, the following actions are required: (1) Move the cursor to either: (a) The first character of the block; or (b) Just beyond the last character of the block. (2) Press {MARK-TEXT} (default CTRL/T). The message 'Text block started' appears in the message line at the bottom of the screen, and the character at the cursor position is displayed in inverse video. If {MARK-TEXT} is pressed in error, the text block operation can be abandoned by pressing {MARK-TEXT} again [MARK TEXT]. (3) Move the cursor to the other end of the block and press one of: (a) {CUT-DELETE} (default CTRL/W) to cut the text out of the file and place it in the cut buffer [CUT]; -19- (b) {CUT-COPY} (default CTRL/E) to make a copy of the text from the file in the cut buffer [COPY]; (c) {DELETE-MARKED} (default CTRL/Q) to delete the text from the file [DMARKED]. While moving the cursor to the other end of the block, other editing operations may be carried out. After a cut or copy operation (a copy of) the text is in the cut buffer, replacing whatever was there previously, whether it was a text block or a rectangle [CUTSTYLE]. To insert the contents of the cut buffer into the file, move the cursor to just after the insertion position and press {PASTE} (default CTRL/P) [PASTE]. The contents of the cut buffer are not destroyed by this, and therefore the same text can be inserted many times. As an example of how to use text blocks, consider the problem of moving a sentence about in a paragraph of text. Suppose the top of the screen contained the following lines: ----*----1----*----2----*----3----*----| The successful candidate will be expected to reside in Cambridge and to undertake approximately twelve hours a week of teaching. Candidates should be under the age of thirty-three on 1 October 1987. The salary will be and that it is desired to reverse the order of the first two sentences by cutting out the second and inserting it before the first. Placing the cursor under the first letter of 'Candidates' and pressing {MARK-TEXT} begins the operation. The cursor is then moved after the space at the end of the sentence (that is, to the start of 'The' at the start of the third sentence) and {CUT-DELETE} is pressed. The screen then looks as follows: ----*----1----*----2----*----3----*----| The successful candidate will be expected to reside in Cambridge and to undertake approximately twelve hours a week of teaching. The salary will be Notice that the remainder of the sixth line has been joined to the remainder of the fourth line. This is in accordance with the view of the text as a linear stream of characters containing 'newlines'. To insert (a copy of) the cut buffer, the cursor is now placed at the start of the text and {PASTE} is pressed. The screen becomes -20- ----*----1----*----2----*----3----*----| Candidates should be under the age of thirty-three on 1 October 1987. The successful candidate W expected to reside in Cambridge and to undertake approximately twelve hours a week of teaching. The salary will be The newline after 'be' is reproduced in the inserted text, but the insertion has caused the third line to become wider than the screen. Since the cursor is left under the word 'The' it is a simple matter to press {SPLIT-LINE} to split the line and obtain ----*----1----*----2----*----3----*----| Candidates should be under the age of thirty-three on 1 October 1987. The successful candidate will be expected to reside in Cambridge and to undertake approximately twelve hours a week of teaching. The salary will be Automatic tidying up of paragraphs after editing of this kind can be achieved using NE's formatting facilities, which are described in a later section [FORMAT]. The text block facility can of course be used to move, copy or delete complete lines of text. In this case, the start of the block is the first character of the first line involved, while the end of the block is the first character of the line after the last line involved. If the end of the last line is used instead, the final 'newline' is not included in the block. 4.13 Rectangular blocks For some operations it is convenient to regard a file of text as a rectangular array of characters. NE provides cutting, copying and deletion facilities for rectangles, and the ability to insert a rectangle of spaces into a file. To cut or copy a rectangular block from the file being edited, the following actions are required: (1) Move the cursor to any of the four corners of the rectangle. For left-hand corners the cursor should be on the first character inside the rectangle, while for right-hand corners it should be after the last character in the rectangle. (2) Press {MARK-RECTANGLE} (default CTRL/R). The message 'Rectangular block started' appears in the message line at the bottom of the screen, and the character at the cursor position is displayed in inverse video. If {MARK- RECTANGLE} is pressed in error, the rectangular block -21- operation can be abandoned by pressing {MARK-RECTANGLE} again [MARK RECTANGLE]. (3) Move the cursor to the opposite corner of the rectangle and press one of: (a) {CUT-DELETE} to cut the rectangle out of the file and into the cut buffer [CUT]; (b) {CUT-COPY} to make a copy of the rectangle in the cut buffer [COPY]; (c) {DELETE-MARKED} to delete the rectangle from the file [DMARKED]. While moving the cursor to the other corner of the rectangle, other editing operations may be carried out. When a rectangle is cut or deleted from a file, all the lines involved are closed up by an equal amount. After a cut or copy operation (a copy of) the rectangle is in the cut buffer, replacing whatever was there previously, whether it was a rectangle or a text block [CUTSTYLE]. To insert the contents of the cut buffer into the file, move the cursor to where the top left-hand corner of the rectangle is to be positioned, and press {PASTE}. The contents of the cut buffer are not destroyed by this, and therefore the same rectangle can be inserted many times. The insertion of a rectangle affects the current line and a number of lines below it, depending on the number of lines in the rectangular block. Each of the relevant lines is 'opened up' at the insertion point by the width of the rectangle, and the appropriate line of the rectangle is then inserted. As an example of the use of rectangles, consider the problem of re-arranging the columns in a table. Suppose the lines on the screen are: ----*----1----*----2----*----3----*----| First Second Third 123.45 76.99 88.23 999.00 8.4 45.06 2.33 - - To interchange the second and third columns, the cursor is placed on the 'S' of 'Second' and {MARK-RECTANGLE} pressed. Then the cursor is moved to the start of 'Third' and down to the fourth line, and {CUT-DELETE} is pressed. The second column is cut out and the screen looks as follows: -22- ----*----1----*----2----*----3----*----| First Third 123.45 88.23 999.00 45.06 2.33 - Now the cursor is moved to the top line, several columns past the word 'Third', and {PASTE} is pressed. The result is: ----*----1----*----2----*----3----*----| First Third Second 123.45 88.23 76.99 999.00 45.06 8.4 2.33 - - {MARK-RECTANGLE} may be followed by {RECTANGLE-SPACES} (default CTRL/S) instead of {CUT-DELETE}, {CUT-COPY} or {DELETE-MARKED}. This has the effect of inserting a rectangle of spaces into the file. The operation is carried out by placing the cursor at one corner and pressing {MARK- RECTANGLE}, then moving to the opposite corner and pressing {RECTANGLE-SPACES}. The effect is to insert the same number of spaces into each line at the column marked by the left-hand side of the rectangle so that the character that was previ- ously in that column is now in the first column to the right of the marked rectangle. Suppose that the lines in the above example were to be indented by five characters. {ALIGN-LINE} cannot be used because it would mis-align the third line of numbers. The cursor is placed at the start of the first line, and {MARK- RECTANGLE} is pressed. Then the cursor is moved to column six on the last line and {RECTANGLE-SPACES} is pressed. The result is as follows: ----*----1----*----2----*----3----*----| First Third Second 123.45 88.23 76.99 999.00 45.06 8.4 2.33 - - 4.14 Re-formatting paragraphs When a paragraph of text is edited it often becomes untidy, in the sense that the lengths of the lines are very variable, and some lines may have become longer than the screen width. Re- formatting, so that each line contains the maximum number of words, is achieved by pressing {KEYSTRING-20}, having previ- ously placed the cursor on the first line to be affected. This need not necessarily be the first line of the paragraph [FORMAT]. Effectively, the lines from the current line to the end of the paragraph are joined into one long line, and the result is then split up so that no line exceeds the right-hand margin -23- [RMARGIN]. Splitting always takes place just after a space character, unless there are no preceding spaces in the line, in which case the split happens exactly at the margin. Disabling the right-hand margin ({KEYSTRING-10}) does not affect formatting; the same margin value is still used. A blank line or a line beginning with a space marks the end of a paragraph and the cursor is left at the beginning of the line following the paragraph that has been formatted. Thus {KEYSTRING-20} can be pressed several times in succession in order to format several paragraphs. If the current line is empty when {KEYSTRING-20} is pressed, the only effect is to move the cursor to the start of the following line. Only non-empty lines are recognized as being part of a paragraph, and so blank lines are preserved by the formatting process. It is possible to change the rules for the recognition of the beginnings and ends of paragraphs [BEGINPAR, ENDPAR]. This can be useful when editing text that contains, for example, control statements for a text formatting program. 4.15 Help information Some information about the various keystrokes used by NE is available from within an NE session. Pressing {KEYSTRING-9} (normally implemented as function key 9 on any keyboard that has function keys) generates a display which lists the current actions of the keystrokes [SHOW KEYS]. The display is in three parts: (1) The 'control' keystrokes. These are those that are usu- ally generated by holding down the CTRL key and pressing another key with it. (2) The 'extra' keystrokes. These are those that are usually generated by dedicated keys on the keyboard, such as the DELETE key. (3) The function keystrokes. These keystrokes are those that are normally generated by function keys on the keyboard, but in some cases are generated by pressing the ESC key followed by another key. Pressing {KEYSTRING-19} gener- ates a display which lists the actions of the various 'function' keystrokes only. Control and function keystrokes that are unset are omit- ted from the displays. When either {KEYSTRING-9} or {KEYSTRING-19} is pressed, the bottom separator line is moved up, and the display appears at the bottom of the screen. For {KEYSTRING-9}, the total display is too long to fit on a typical screen. NE therefore pauses between parts and outputs the message: -24- Press RETURN to continue The default actions of the function keystrokes are in fact to obey particular NE commands, that is, they are associated with appropriate function keystrings. The use of commands is described later, but many of the oper- ations shown (such as 'format') should be understandable by someone who has read only this far. At the end of the display there is a line containing NE> This is a command prompt from NE - the use of commands is covered in the next section. Pressing {ENTER} at this point causes the information display to disappear and the previous contents of the screen to be restored. On all current versions, {ENTER} is implemented as the RETURN key. 4.16 Entering NE command lines The keystroke {READ-COMMAND} (default CTRL/G) is a request to enter a line of NE commands. The character at the cursor position is re-written in inverse video, and the cursor moves out of the text display area and into the command entry line at the bottom of the screen, where the prompt 'NE>' is shown. The user must now type a line of commands, terminated by {ENTER} (normally the RETURN key). If the line is empty, NE simply reverts to screen editing. If mistakes are made while entering commands, the line can be edited using the cursor keys, {DELETE-PREVIOUS}, {DELETE-HERE}, {DELETE-LEFT}, {DELETE-RIGHT}, and {DELETE-LINE}, before pressing {ENTER} to cause it to be obeyed. If a mistake is detected by NE, an error message is given and another prompt is issued. The previous line of commands can be recalled for editing by means of the {SCROLL-UP} key. The following subset of commands may prove useful to users who are just starting to learn how to use NE. For more details, and for a fuller description of the complete set of commands, see the chapters which follow. Note that the case of letters in command names is not significant. . F // causes NE to search forwards through the file from the current position until it finds the given character string, which should not contain the character '/'. If the string contains any letters, it does not matter whether they are in upper or lower case (capital or small); NE treats different versions of the same letter as identical in simple searches such as this. Once an F command has been obeyed, the same search can be repeated simply by pressing the {KEYSTRING-7} key. NE can be made to search backwards by using the BF command -25- instead of F; this is repeated by means of the {KEYSTRING-17} key. If NE fails to find the string it is searching for, the current position is unchanged. . GE // // is a request to globally exchange the first string for the second. NE searches forwards in the file until it finds the string, exactly as for the F command. When it finds an occurrence, it updates the screen to show the text which was found, in inverse video, and outputs the prompt Change, Skip, Once, Last, All, Finish, Quit or Error? The user must type the initial letter of one of the displayed words, followed by {ENTER}. 'C' (change) causes NE to make the change, then move on to the next occur- rence of the string, while 'S' (skip) causes it not to make the change, but still to move on to the next occurrence. 'O' (once) and 'L' (last) both make the change, then terminate the command; the difference between them is that 'O' restores the current point to where it was at the start of the command, while 'L' leaves it after the final change. 'A' (all) makes the change, and then continues through the file, changing all occurrences without further prompting. 'F' (finish), 'Q' (quit) and 'E' (error) all terminate the command without making the change. The difference between them is that 'E' forces an error, which causes NE to abandon any further commands and prompt for a new command line, while after 'F' or 'E', the current point is restored to where it was at the start of the command, but after 'Q' it remains at the point of last match. A number of successive replies to the prompt can be given all at once as a string of letters. For example, a reply of ccsccc specifies that the current and next occurence of the sought-for string are to be changed, then one occurrence is to be skipped, and then the next three are to be changed. Digits can be used within the string to save typing. The following is an equivalent reply: 2cs3c In addition to the GE command, which exchanges one string for another, there are also commands called GA and GB which operate in the same way, but which cause the second string to be inserted after or before occurrences of the first string, respectively. -26- NE contains facilities for more complicated kinds of change, including the use of 'wild card' characters in strings. The chapters entitled Context matching, Character string insertions, and Global changes contain further details. . LOAD causes NE to load a new file for editing. If the old file has been changed but not saved (see below), the following is output: The contents of buffer 0 have not been saved. Continue with LOAD (Y/N)? A reply of Y or YES causes the current editing text to be lost; a reply of N or NO indicates that a mistake has been made. In this case, NE issues a further command prompt. . M causes NE to make the line with the given number the current line (M is an abbreviation of 'move'). For example, m1234 makes line 1234 the current line. Remember that lines are counted as they are read from the original file, and the numbers do not change as lines are edited [RENUMBER]. If the specified line has been deleted, an error occurs and the current line does not change. A line number of zero is taken to mean the start of the file, and an asterisk may be given instead of a line number to move to the end of the file. . N causes NE to advance through the file by the given number of lines (N stands for 'next'). For example, after obeying 300N the current line is 300 lines further into the file than before. . P causes NE to move backwards through the file by the given number of lines (P stands for 'previous'). . RMARGIN specifies a new right-hand margin value. For example, if text is being input and the maximum line length that is wanted is 60 characters, then rmargin 60 is appropriate. After this command has been obeyed, the separator lines show a vertical bar in column 61, and any character typed in this column causes the power typing feature to come into effect. In addition, the formatting -27- keystroke ({KEYSTRING-20}) now makes paragraphs whose maximum width is 60 characters. . SAVE causes the current text that is being edited to be written back to the disc file. Before actually writing to the file, NE outputs the prompt Write to (Y/N/TO filename)? to ask for confirmation. A reply of Y or YES allows the writing to go ahead; a reply of N or NO indicates that a mistake has been made, and NE issues a new command prompt. A reply consisting of the word 'to' followed by further text is taken as supplying an alternative file name. When a new name is given, it becomes the default name for future SAVE operations and for writing the file at the end of editing. If the reply is not in one of the above forms, NE outputs an error message and displays the prompting line again. SAVE is one way of taking safety copies of a file during a long editing session. It can also be used in conjunc- tion with LOAD to finish editing one file and start on another without leaving NE. . SHOW WORDCOUNT causes NE to display information about the text it is editing. The numbers of lines, words, and characters are displayed; words in this context are sequences of characters separated by spaces or the ends of lines. The information is displayed at the bottom of the screen, which scrolls up to accommodate it, and a further command prompt is then given. Pressing the RETURN key at this point returns to screen editing. . SHOW COMMANDS causes NE to display a list of all its command words. . STOP causes NE to cease processing immediately, and exit. Any changes to the file being edited are lost. An error code is passed to the operating system. If a command line (other than one containing STOP) is success- fully obeyed, NE returns immediately to screen editing without any further action from the user. If, on the other hand, an error message is output, NE issues a prompt for a further line of commands. 4.17 Multi-buffer editing It is possible in NE to edit more than one file at once, switching between two or more buffers as necessary. Details of this facility is given in the chapter entitled Buffer Handling. -28- 4.18 Leaving NE When editing of the file is complete, {KEYSTRING-3} should be pressed [W]. The first thing that NE does when preparing to end an editing session is to check whether any text has been cut into the cut buffer, but never actually pasted into the file. If this is the case then the prompt The contents of the cut buffer have not been pasted. Continue with W command (Y/N)? is output as a warning. (The reference to the W command occurs because the {KEYSTRING-3} key works by issuing that command.) If the user replies Y or YES then NE proceeds, and the contents of the cut buffer are lost. If the reply is N or NO then NE stops what it is doing and issues its standard command line prompt, 'NE>'. Pressing {ENTER} at this point returns NE to screen editing. Next, NE considers the file that has been edited. If no changes have been made to it, NE outputs the message No changes made to and exits. Otherwise, it outputs the prompt line Write to ? (Y/N/TO filename/Discard/STOP) The user must give one of the five possible replies - a null or erroneous reply causes an error message to be output, followed by a repeat of the prompt. The effects of the replies are as follows: . A reply of Y or YES causes NE to write the edited text to the file whose name is shown, and then to exit. . A reply of N or NO indicates that the user has made a mistake. NE outputs its prompt line ('NE>') so that the user can tell it what to do next. Some possible responses to this are described below. . A reply of the form TO is a request to write the contents of the buffer to an alternative file. NE attempts to open this file and write the text to it instead of to the file named in the prompt. . A reply of D or DISCARD causes NE not to write the text to the file, but to carry on as if it had. In the simple case of editing only one file, it exits without error. . A reply of STOP (no abbreviation) causes NE to stop processing immediately, without doing anything further. It exits with an error code. -29- If there is an error while attempting to open or write to the file, or if the user replies N to the prompt, NE does not exit, but prompts for a line of user commands. Full details of NE's commands are given in later chapters, but a short list of possible responses is given here for the benefit of new users of NE. The command line should be terminated by {ENTER}. . To exit from NE (with an error code), type the command STOP. The edited text which NE is holding in main memory is then abandoned. . To attempt to output the edited text again (for example, if a file name was mis-spelled previously, causing an error to occur), type the command W (windup). NE then issues the 'Write to' prompt again. . Entering an empty command line causes NE to restart screen editing. 4.19 Summary This chapter has described the screen editing facilities of NE, and a subset of the more common commands, using all the default option settings. The facilities covered are sufficient for many straightforward editing jobs. The chapters which follow cover NE's command system in detail. This extends the power of the editor for more complicated situations. Note that there is a summary of the logical keystrokes near the end of this document, and that details of the correspondences between logical control keystrokes and actual keypresses are given in the device-specific chapters. -30- 5. THE NE COMMAND The full NE command takes the following form: ne [[-from] ] [-to ] [-ver ] [-with ] [-opt ] [-stream []] [] where square brackets indicate optional items. A command with no arguments at all is valid. The are: -b[inary] -errorlog -line -noinit -notabs -r[eadonly] -tabs -tabin -tabout -h[elp] -id none of which take any additional parameters. -binary or -b invokes the special facility for editing binary files which is described in section 5.2 below. -errorlog causes all error messages to be written to the crash log file; this is a debugging feature. -line requests that ne operate in line-by-line mode (as opposed to screen mode). -noinit suppresses the use of any initializing commands that might be set up by means of an operating system variable - see the various system-specific chapters for details. -notabs suppresses the use of an operating system variable to specify the default tab-handling setting. See section 5.1 for further details. -readonly or -r causes the first file that is being edited to be loaded into a read-only buffer [READONLY]. Any attempt to alter the contents is faulted. -tabs, -tabin, and -tabout control the handling of tab charac- ters in files that are being edited. Details are given in section 5.1. -help or -h requests a display of the syntax of the NE command, while -id requests a display of the current version number of NE. When either of the these two arguments is present, the main part of NE is not entered. -31- The keyed items may occur in any order. It is necessary to quote the command strings which form the arguments for -opt if they contain spaces or any other characters which are interpreted specially by the command interpreter (shell). the -stream option is concerned with the editing of files that are too large to fit into main memory, and its use is described in chapter 22 (Editing large files). If only a single input file name is given, then that file is edited and written back to a file of the same name. If a file name is given following the -to keyword, then the result of editing the first file is written to the -to file at the end of editing. (These are defaults; the file name can be changed from within NE by appropriate commands.) In fact, up to nine input file names may be given; each is loaded into a separate editing buffer. See chapter 20 (Buffer handling) for further details of multiple buffers. The -to option, if present, applies to the first named input file only. The default for the other files is to update them in place. If the first file named does not exist, NE generates an error message and exits. It does not create a new file under these circumstances. To create a new file, a command such as ne -to can be used. Alternatively, the NE command can be given with no file names at all. This enters NE and sets up an empty editing buffer; a file name can be supplied when the buffer is to be written out. the -ver keyword can be used to direct verification and error messages to a specific file. If it is not specified, such messages are sent to the standard output (except when filter- ing - see the system-specific chapters). the -with keyword can be used to specify the input file containing editing commands. If it is not specified, commands are read from the standard input (except when filtering - see the system-specific chapters). NE is initialized in interactive mode, unless the -with or -ver keywords are given or (in systems which support it) NE is being run as a filter. In interactive mode, if the terminal is suitable for screen editing, then screen mode is also selected, unless -line is present. Otherwise interactive line- by-line mode is selected. The above rule makes it possible to use NE in scripts with inline editing commands. For example: -32- ne -line foobar < End In non-interactive mode, NE stops if any error occurs, with a non-zero return code. When NE is run interactively, it issues a non-zero return code only when the STOP or ABANDON command is obeyed. Normal termination always results in a return code of zero, even if there have been errors in the run. The -opt keyword on the NE command line is used to supply one or more commands to be obeyed at the start of editing. This can be useful, for example, for moving to a particular point in the file before displaying a screenful of data over a slow communications line. It can also be used to supply a short 'script' of non-interactive editing commands without using file to store them in. 5.1 Tab support There are three command line options which control the way NE processes tab characters. If none of them is given, then the ASCII tab character is not treated specially; it is displayed on the screen as a non-printing character. The options are: . -tabs: if this option is present, tabs are expanded when input lines are read, assuming tab stops every eight characters. Lines in which tabs have been expanded are marked as such, and when they are output, NE puts back as many tabs as it can, except that it does not use a tab where a single space will do. Note that this does not guarantee that unchanged output lines will be identical to the input lines. . -tabin: if this option is present, tabs are expanded on input, but no action is taken when lines are output. . -tabout: if this option is present, all lines have as many tabs as possible inserted when they are output. The latter two options can usefully be combined. Other combi- nations are accepted but provide no additional facilities. In most operating systems, there is a system variable that can be set to specify the default tab processing option. Details are given in the system-specific chapters. The command line option -notabs can be used to override such a default. 5.2 Editing binary files Many personal computers have a 'dump' command or similar which displays files in hexadecimal and characters in the following sort of layout: -33- 00A0 68 74 20 28 ... 55 6E 69 76 65 * ht (c) Unive * 00AC 72 73 69 74 ... 66 20 43 61 6D * rsity of Cam * Some have programs which allow the user to scroll around such a display, and possibly change its contents. These facilities are useful when working with files containing binary data. NE contains some simple facilities that allow it to provide a similar function. This feature is currently experimental, and may change or be withdrawn in future versions. It works as follows: if the keyword -binary (abbreviation -b) is present on the NE command line, NE operates in 'binary mode'. For example, ne prog.o -b This applies to the whole NE session and to all buffers. It is not possible to have some buffers in binary mode and some in text mode. If NE is entered in binary mode and it is also running in screen mode, screen handling is initialized in overstrike rather than replace mode. When NE is in binary mode, it reads input files 16 bytes at a time. Each group of 16 bytes is converted into a textual input line in the following format: aaaaaa dd dd dd dd ... dd dd * cccccccccccccccc * where aaaaaa is the hexadecimal address within the file of the first byte of the 16, the dd's are the hexadecimal represen- tations of the characters, and the cccc's are the character representations, with non-printing characters shown as full stops. The final 'line' of a file may represent fewer than 16 bytes. The majority of the code of NE has no knowledge of binary mode, and it processes these constructed lines as if they were ordinary text lines. The lines may be modified by using any of NE's repertoire of commands or screen editing facilities. There is some special knowledge in the screen driver such that, if the hexadecimal data in a line is changed, the character portion of the line is changed to match, and vice versa. If the file is to be written out again successfully, the format must be preserved sufficiently to satisfy the following algorithm: Whenever NE is required to output a line in binary mode, it ignores all characters before the first space and also the first asterisk and all characters that follow it. The remain- der of the line must consist of pairs of hexadecimal digits, optionally separated by spaces. Each pair of hexadecimal digits is converted into a single byte, which is then written to the file. -34- Note that the spaces, if present, must fall between pairs of digits, not between the first and second digit of a pair. There may be more or less than 16 pairs, and the letters may be in upper or lower case. If the format of any line is incorrect, an error message is output which shows the line at error. The data written to the file for that line will contain some bytes of rubbish. A number of error messages may be produced from a single writing operation. If the writing is the result of a W command, and there have been errors, NE does not exit. -35- 6. NE COMMAND LINES NE command lines can be obeyed while screen editing as well as when editing line by line. In most implementations an initial line of NE commands can be included in the operating system command which invokes NE, and there is often a way of specifying default commands to be obeyed automatically every time that NE is entered. Before describing the individual commands in detail, some general discussion of the syntax is given. 6.1 Format of command lines An NE command line consists of any number of NE commands, separated by semicolons except in one special circumstance (see below). Each command consists of a command name, possibly followed by additional data known as arguments. Command names are either a sequence of letters (for example, RMARGIN) or they consist of a single special character (for example, #). In the latter case there are never any arguments, and the commands are self-terminating, that is, a semicolon is not needed after such commands. The letters in a command name can be entered in either upper or lower case. When a command whose name consists of letters is followed by an argument, a space is necessary following the command name if the argument begins with a letter. In other cases, spaces between the command name and the first argument are optional. A command may be repeated by preceding it by a decimal number. It does not always make sense to repeat commands, but NE does not forbid it. An example of a sensible repetition is 132n which has the effect of obeying the N command 132 times. A group of one or more commands may be repeated by enclosing it in round brackets and preceding it by a decimal number, for example 3(f/abc/; n) Such command groups may be nested up to about 150 deep. They are used in other contexts as well as for repetition. If two successive backslash characters are encountered in a command line, other than inside a delimited string or a file name, they signifies that the rest of the line is a comment which is to be ignored. NE behaves as if the line ends immediately before the backslash characters. The maximum length of a command line is 512 characters. -36- 6.2 Continuation of command lines Command lines may be continued onto as many input lines as necessary, provided that the line breaks occur inside brackets and at the end of a command. For example, (ge/s//t/; ga/a//b/) Brackets can be used solely for the purpose of introducing line breaks; they need not be preceded by a repetition count. If NE is running interactively when a command line is con- tinued, it prompts with the text 'NE+' for the second and subsequent lines, instead of the normal 'NE>'. 6.3 Format of common arguments There are several common kinds of argument that are used in more than one command. They are as follows: . A decimal number, often simply called a number, is a sequence of decimal digits. It is terminated by the first non-digit encountered. . A word is a sequence of letters, terminated by the first non-letter. Upper and lower case letters are synonymous in words. . A string is a sequence of characters enclosed in delimiter characters. For any particular string, the delimiter character may not itself appear in the string. Only certain characters may be used as delimiters; they are ' " ! . , : + - * / These are the standard English punctuation characters (with the exception of semicolon and question mark) together with the characters normally associated with the four arithmetic operators in programming languages. Some examples of strings follow: /elephant/ .rhinoceros. :3.14159: "The quick brown fox" !mighty atom! +e = mc**2+ When a string is the very last thing on a command line, the final delimiter may be omitted. . A qualified string is a string preceded by certain qualifier characters. Details are given in the next chapter. -37- . A search expression is either a single qualified string, or several such strings connected by boolean operators. Details are given in the next chapter. . A file name is the name of a file in the local filing system. The format of file names is system-dependent, and details are given in the system-dependent chapters later on. Provided that the file name does not contain any semicolon characters or start with two backslash charac- ters, it can be entered straightforwardly. If one or more semicolons are present, or if the first two characters are backslashes, the file name must be entered as a string. The set of allowable delimiter characters for file names is a subset of the full set listed above. In most operating systems, those characters that may legally be part of a file name are excluded from the set of allowed delimiters for file names. 6.4 Obeying commands while screen editing There are two ways in which commands can be obeyed while screen editing. The keystroke {READ-COMMAND} is a request to enter a line of commands from the keyboard. The cursor is moved to the last line of the screen, and the prompt 'NE>' is output. The current position in the text being edited (that is, where the cursor was when {READ-COMMAND} was pressed) is displayed in inverse video. A line of commands can now be constructed by typing in the normal way. If an error is noticed, the arrow keys can be used to move the cursor back along the line, and correction can be carried out using the normal screen editing facilities. When the command line is complete, pressing {ENTER} causes NE to analyse it and, if there are no syntax errors, to obey it. If a syntax error is found, none of the commands are obeyed. The second way of causing commands to be obeyed is to execute a keystroke which has been bound to one of the logical keystrokes {KEYSTRING-1} to {KEYSTRING-60}. These cause the appropriate function keystring to be obeyed as a line of commands, just as if it had been typed by the user in response to the 'NE>' prompt. If a keyboard has function keys, these are normally set up by default to cause the keystrings of the same numbers to be obeyed. In addition, other keys are often bound to function keystrings, for example CTRL/CIRCUMFLEX and CTRL/UNDERLINE are bound by default to {KEYSTRING-58} and {KEYSTRING-59}. The contents of all the non-empty function keystrings can be seen by obeying the command show keystrings -38- and the relationships between actual keystrokes and keystrings can be seen by obeying show keys which shows the current bindings of the 'control-type', 'extra', and 'function-type' keystrokes [SHOW]. Keystrokes that execute function keystrings can also be used when the command prompt ('NE>'), or indeed any other prompt, has been output during screen editing. Any characters typed by the user before pressing the key which activates a function keystring are ignored. For example, if a context search in the forward direction fails, causing an error message to be output and leaving NE waiting for a new line of commands, pressing {KEYSTRING-17} causes a BF command to be obeyed; this searches backwards for the same context. The user can alter the function keystrings [FKEYSTRING]. It is also possible to change the relationship between keystrokes and keystrings [KEY]. 'Function-type' keys can be set up to perform built-in operations (for example, to delete a line) and 'control-type' keys can be associated with function keystrings. That is why there are more function keystrings available than 'function-type' keystrokes. When a line of commands is obeyed as a result of pressing a key which activates a function keystring, it is displayed at the bottom of the screen exactly as if it had been typed interactively by the user. If the command line executes successfully, this line is deleted. If, however, there is an error, the area at the bottom of the screen expands, leaving the command line still visible. NE keeps a stack of up to twenty previous command lines. A command line is added to the stack only if it is different to the previous command line. Lines on the stack can be recalled (one by one) by pressing {CURSOR-UP} or {CURSOR-DOWN} when the command prompt is displayed. {CURSOR-DOWN} cycles through the lines in historical order, starting from the oldest one on the stack, while {CURSOR-UP} cycles through them in the reverse order, starting from the most recently obeyed line. A recalled line can be edited in the usual way before pressing {ENTER} to cause it to be analysed and obeyed. At the start of an editing session the stack contains the text passed to NE via any automatic initialization and the OPT argument in its command line. After obeying a command line which produces no output, NE reverts immediately to screen editing. NE arranges that any output generated as a result of analysing or obeying a command line (of which error messages are a special case) is not wiped off the screen before the user has a chance to read it. If the output is an error message, or if -39- it was caused by the last command on the line, NE outputs a further command prompt. This has the effect of keeping the cursor in the expanded area at the bottom of the screen. Simply pressing {ENTER} causes NE to revert to screen editing and to re-write the screen. If non-error output is generated by a command which is not the last on a line, NE pauses after this command is finished, and outputs the message Press RETURN to continue When {ENTER} is pressed, processing of the command line proceeds. Any characters that the user may have typed before {ENTER} are ignored. 6.5 Long command lines while screen editing If, while screen editing, a command line is entered which is too long to fit on the screen, NE scrolls the command input area to the left as necessary. When a command line has been scrolled horizontally, the {SCROLL-LEFT} and {SCROLL-RIGHT} keystrokes can be used to view different parts of it, and further scrolling to the left or right happens automatically if an attempt is made to move the cursor past the edge of the screen. The {ENTER} keystroke which terminates command entry can be typed at any time, wherever the cursor is placed. It does not have to be at the end of the line. When a previous long command line is recalled for re-use, the last portion is displayed, with the cursor at the end of the line. It can be scrolled for editing in the normal way. 6.6 Refreshing the screen NE does not normally update the screen display while a line of commands is being obeyed. Once the commands are finished, it inspects the current contents of the buffer and updates the screen as necessary. (An exception to this rule occurs during the processing of interactive global commands, when the screen is automatically updated if the user is to be prompted.) Sometimes it is necessary to be able to force NE to make the screen display up-to-date in the middle of a line of commands. The command refresh has this effect. (It is ignored if screen editing is not in operation.) REFRESH does not cause NE to re-draw the screen completely. It simply causes the updating that would have occurred had there been no further commands on the line. -40- 6.7 Summary Command lines are available while screen editing as well as while editing line by line. They can be entered from the keyboard or stored in function keystrings and obeyed by a single keystroke. Many commands can be entered on one line, separated (in general) by semicolons. Commands may be grouped, and both groups and individual commands may be preceded by a repeat count. -41- 7. CONTEXT MATCHING Searching a file for a particular context is a very common operation when editing. NE provides the means for performing very complicated kinds of search based on search expressions and qualified strings. These are used in a number of different commands, so they are described separately in this chapter. The searching mechanism is based on the concept of matching a search argument against a line of text. The result of a matching operation is either a failure to match, or two character positions defining the start and the end of that part of the line which has matched the search argument. 7.1 Qualified strings The simplest kind of search argument is a qualified string, and the simplest kind of qualified string is just a sequence of characters enclosed in delimiters. When such an argument is matched against a line, the match succeeds if the line contains the given sequence of characters. However, if any of the characters involved are letters, the upper and lower case forms are treated as synonymous. Thus, for example, if the search string is /Milton Keynes/ then all the following lines match it: The town of Milton Keynes is the town of milton keynes is THE TOWN OF MILTON KEYNES IS tHe tOWn Of MiLToN keYnes is The automatic equating of the upper and lower case forms of the same letter can be disabled, either by a qualifier, for a single qualified string (see below), or by a command [CASEMATCH] which changes the default. Frequently it is useful to apply additional constraints to search arguments. For example, occurrences of the string at the beginning of a line may be the only ones of interest. Such constraints are specified by means of qualifiers which precede the string. Most of the available qualifiers take the form of single letters (in either upper or lower case); one qualifier is a number, and one is a number pair. No spaces are necessary between individual qualifiers if more than one is present on a single string. They may be given in any order. Examples of qualified strings are given after the descriptions of all the qualifiers. -42- 7.1.1 The B qualifier The B qualifier specifies that the string is to be matched at the beginning of the line only. Occurrences of the string other than at the beginning of the line do not match. If a column qualifier (see below) is also present, it changes the effect of the B qualifier so that the string matches only at the beginning of the specified column, rather than at the beginning of the whole line. 7.1.2 The E qualifier The E qualifier specifies that the string is to be matched at the end of the line only. Occurrences of the string other than at the end of the line do not match. If a column qualifier (see below) is also present, it changes the effect of the E qualifier so that the string matches only at the end of the specified column, rather than at the end of the whole line. 7.1.3 The H qualifier The H qualifier specifies that the string is to be matched at the current cursor position ('here') only. This facility is intended mainly for use with conditional commands such as IF and WHILE. H can be combined with P in order to test the rest of the line from the current cursor position (see below). 7.1.4 The L qualifier The L qualifier specifies that the search for the string in the line is to proceed in the reverse direction to normal, that is, from right to left instead of left to right. This means that, if a match occurs, it is the last occurrence on the line that is found. If a column qualifier (see below) is also present, it changes the effect of the L qualifier so that, if a match occurs, it is the last occurrence in the column, rather than the line, which is found. 7.1.5 The N qualifier The N qualifier negates the result of the string match. If, taking into account all the other qualifiers, the result of the match is a failure (that is, the line does not contain the string) then the N qualifier converts it into a success, yielding the beginning and end of the line as pointers to a string that does not contain the one searched for. If, on the other hand, the string is found in the line, the N qualifier converts the result into a failure. -43- 7.1.6 The P qualifier If the P qualifier is present, the string match succeeds if the line contains precisely the given string, that is, the line consists only of the string, with no other characters before or after it. If a column qualifier (see below) is also present, it changes the effect of the P qualifier so that it is the characters within the column which must match the given string precisely. P can be used with a null string to match blank lines, or with a null string and a column qualifier to search for lines longer than a particular length. It can also be used with the H qualifier to cause the given string to be compared with the rest of the line, starting from the current cursor position. This facility can be used to check whether the cursor is at the end of a line by specifying a null string. 7.1.7 The R qualifier The R qualifier specifies that the characters in the string are not to be used for a literal match against the line, but instead are to be interpreted as a regular expression. Regular expressions are a powerful way of expressing complicated matching conditions; they are described in section 7.3. 7.1.8 The S qualifier The S qualifier causes NE to ignore leading and trailing spaces when matching strings at the beginnings or ends of lines. The letter 's' is an abbrevation for 'significant'. This qualifier is normally used in conjunction with the B, E, or P qualifiers. 7.1.9 The U qualifier The U qualifier causes NE to match letters in an un-cased manner - that is, upper and lower case versions of the same letter are treated as the same letter. This is, of course, the default action of NE. However, the default can be changed [CASEMATCH], and this qualifier is provided to override the alternative default. 7.1.10 The V qualifier The V qualifier causes NE to match letters in a verbatim manner - that is, upper and lower case versions of the same letter are not treated as the same letter. -44- 7.1.11 The W qualifier The W qualifier causes NE to match the string as a word, in the following sense: if the string is found in the line, the preceding and following characters are examined, if there are any. If either character exists and is found to belong to the set of characters that are permitted in words, then the match at that point in the line is cancelled, and NE carries on searching for another occurrence of the string. The default set of characters for words is the set of letters and digits; this can be changed by means of the WORD command (see Changing default operations). 7.1.12 The X qualifier If the X qualifier is present, the string is interpreted as a sequence of pairs of hexadecimal digits representing the characters to be searched for. The characters specified by the hex pairs are always matched in a verbatim manner, independent of the presence of the U qualifier or the setting of the case matching default. 7.1.13 The repeat qualifier A decimal number may appear as a qualifier. It specifies the number of times the string must be found in a line for the match to succeed. For example, 3/elephant/ matches a line containing at least three occurrences of the string 'elephant', and yields pointers to the third occurrence. 7.1.14 The column qualifier The search for the string can be restricted to certain column positions in the line. The columns in a line are numbered from one. Two numbers, giving the inclusive starting and ending columns, may be given in square brackets, the numbers being separated by a comma. Either number may be omitted. If only one number is given, only a single column is searched. If one number followed by a comma is present, the search continues to the end of the line. If the first number is omitted but the comma is present, the starting column is the beginning of the line. The presence of this qualifier affects the behaviour of the B, E, L, and P qualifiers. -45- 7.1.15 Combining qualifiers Qualifiers may be combined in any sensible combination; non- sensical combinations are forbidden and provoke an error message, as do repeated occurrences of the same qualifier. Only one of B, E, L or P may appear on any one qualified string. 7.1.16 Matched strings When a qualified string matches a line, it normally identifies a portion of the line which matches the string. However, if the N qualifier is present, it is the whole line which is considered to have been matched. 7.1.17 Examples of qualified strings Some examples of qualified strings are shown below, together with a description of the characteristics of lines that they match: /abcd/ contains 'abcd' 3/abcd/ contains 3 occurrences of 'abcd' [4,20]/abcd/ contains 'abcd' in columns 4-20 b/abcd/ begins with 'abcd' e/xyz/ ends with 'xyz' n/spqr/ does not contain 'spqr' nb/spqr/ does not begin with 'spqr' n3/spqr/ contains fewer than 3 occurrences of 'spqr' p// is an empty line [73,]np// contains characters after column 72 sb/abcd/ begins with optional spaces, then 'abcd' v/Milton/ contains 'Milton', as capitalized w/cat/ contains the word 'cat' x/7E4D/ contains the two characters specified in hex 7.2 Search expressions The simplest kind of search expression is a single qualified string, but more complicated search expressions can be formed by combining qualified strings using the boolean operators 'and' and 'or'. Such a search expression is always enclosed in round brackets, and if it succeeds, it is the whole line which is considered to have been matched. Within the brackets there are a number of search expressions, separated by one of the characters '&' or '|', meaning 'and' and 'or' respectively. For example, (/cat/ & /dog/) matches a line that contains both the strings 'cat' and 'dog'. Note that the order of the strings inside the brackets does -46- not imply that the strings in the line are in the same order. The 'or' operation is inclusive, so that (/mouse/ | /elephant/) matches a line that contains either or both of the strings 'mouse' or 'elephant'. It is also permitted to have just a single qualified string inside brackets, and this behaves differently from the unbracketed case. The results of matching /xxx/ and (/xxx/) (for example) are not the same. The first matches part of a line; the second matches a whole line. Because the items inside the brackets are search expressions in their own right, they can themselves be enclosed in brackets. Brackets are often necessary when both operators are used, to specify the order of combining the expressions. By default, the 'and' operator is more strongly binding that the 'or' operator, so that an expression such as (/abcd/ & /spqr/ | /xyz/) is equivalent to ((/abcd/ & /spqr/) | /xyz/) and it matches a line that either contains both 'abcd' and 'spqr' or contains 'xyz' (or all three, since the 'or' operation is not exclusive). Some of the qualifiers used in qualified strings can also be applied to complete search expressions by placing them immedi- ately before the opening bracket. The qualifiers that are permitted in this position are: N negation of match result U un-cased matching V verbatim matching W word matching When used in this way the U and V qualifiers apply to any enclosed qualified strings that do not themselves have a U or V qualifier. The following examples show equivalent search expressions: n(/cat/ & /dog/) = (n/cat/ | n/dog/) uw(/cat/ | v/dog/) = (uw/cat/ | vw/dog/) Search expressions permit quite complicated matching con- ditions to be expressed, but because they impose no order on the different items in the line, there are certain kinds of search for which they cannot be used. -47- 7.3 Regular expressions Regular expressions permit the expression of complicated kinds of matching condition which are not possible with search expressions using ordinary qualified strings. A regular expression is essentially a pattern or template which is matched to the line. Since a regular expression is itself a kind of qualified string, it can form a component of a search expression if necessary. The mechanisms for dealing with regular expressions are fairly complicated, because of the generality that is possible. For this reason, regular expressions should only be used when necessary; if the required matching condition can be expressed without their use, fewer resources will be consumed by NE. When a regular expression is used in a command which searches for a string and replaces it or inserts another string alongside it (for example, the GE command), the replacement string can also be subject to special interpretation. Details are given in the next chapter. The R qualifier, when present on a qualified string, causes NE to interpret the given string as a pattern for a regular expression instead of an ordinary text string. Other quali- fiers may also be present, and have their usual effect. Within the pattern, certain characters take on a special meaning, and these are called meta-characters. If there are no meta-characters in the string, the effect is as though the R qualifier were not present - except that NE consumes more resources. When matching a regular expression to a line, NE always tries to find the longest matching portion of the line that it can. NE supports two different syntaxes for expressing regular expressions. The default is its own syntax, which is compat- ible with the previous Cambridge editors E and Zed. However, an alternative syntax which is compatible with the syntax used for regular expressions in Unix systems is also available. If the UNIXREGEXP command is obeyed, regular expressions in subsequent commands are assumed to be in the Unix style. The next two sections describe each form of regular expression separately. 7.4 NE-style regular expressions In this section, it is assumed that NE's default interpret- ation of regular expressions is in force. -48- 7.4.1 Wild character The meta-character '?' is a wild character in a regular expression. It matches any single character whatsoever in the line being checked. Thus, for example, r/advis?r/ matches 'advisor' and 'adviser' (as well as 'advisur', 'advis!r', and so on). There may of course be more than one such character in the pattern. 7.4.2 Quoting character If a question mark, or any other meta-character, is needed as part of the data in the string, it must be preceded by a double-quote character. This is a meta-character which has the effect of ensuring that the character that follows it is not treated as a meta-character. Thus, rv/Wh??"?/ matches the strings 'What?' and 'When?' (but not 'Who?', because two characters are needed between 'Wh' and the ques- tion mark). To include a double-quote itself in the data, simply double it. A double-quote may appear before any charac- ter, whether it is a meta-character or not; in all cases it ensures that the following character is taken as data. 7.4.3 Repetition A question mark matches a single character; if a wild sequence of characters is required, the meta-character '#' can be used as well. It has the effect of causing the next item in the regular expression to be matchable any number of times (including not at all). Therefore, an expression such as r/a#?b/ matches any sequence of characters beginning with 'a' and ending with 'b', including 'ab' itself. Repetition can apply to ordinary characters as well as to wild characters. The expression r/1#34/ matches the strings '14', '134', '1334', '13334', etc. There is a second meta-character which causes repetition, namely '^'. It differs from '#' only in that it matches one or more (instead of zero or more) occurrences of the following item. For example, r/emba^rassing/ -49- matches 'embarassing' and 'embarrassing' (and also 'embarrrassing', of course), but not 'embaassing'. 7.4.4 Character classification It is possible to specify that the next character in the pattern must match a character of a particular type, for example, any digit or any letter. This is achieved by using the meta-character '$' followed by a single letter, in upper or lower case, which indicates the type of character required. The following are available: $A any alphanumeric character (letter or digit) $D any decimal digit $L any letter $P any punctuation character (not a letter or digit) $S white space - a space or tab character $W any character from a 'word' The last one matches the set of characters that NE uses for the purposes of implementing the W string qualifier. The set can be changed by means of the WORD command. When the search is a verbatim one, that is, when upper and lower case letters are not being treated as synonymous, the case of '$A' and '$L' matters. They match only those letters which appear in the line in the appropriate case. In these circumstances, the negation of '$P' can be used as a case- insensitive way of matching an alphanumeric character. 7.4.5 Character ranges A character can be constrained to lie within a particular range of letters or digits by using a minus sign between the ends of the range. For example r/g-m/ matches any letter in the range g-m inclusive. When this syntax is used, the two limits must both be upper case letters, lower case letters, or digits. This rule is imposed to keep this feature of NE independent of the underlying character set of the machine on which it is running. 7.4.6 Hexadecimal characters It is possible to specify a single character in a regular expression pattern as a pair of hexadecimal digits. This is done by prefacing the two digits with '$h'. It is also possible to use the X qualifier for regular expressions. In this case the string must consist only of pairs of hexadecimal digits and meta-characters. -50- Ranges of characters can also be expressed in hexadecimal using '$h'; it is used just once rather than before each character. For example, r/$h20-60/ Such a search includes all characters with values in the given range, and is of course dependent on the character set of the machine on which NE is running (unless the data is binary). Characters specified in hexadecimal are always matched in a verbatim manner, independent of the presence of the U quali- fier or the setting of the case matching default. 7.4.7 Negation A regular expression can specify that the next character to be matched is not a particular character, or not in a given class of characters, or not in a given range. This is done by using the meta-character '~' (tilde). For example, r/ing~$L/ matches occurrences of the string 'ing' which are followed by a non-letter - it would match the ends of many words, but not match on 'ingle', for example. (However, it would not match 'ing' if it occurred at the end of a line.) Note that the negation meta-character can only be used to invert the effect of attempting to match a single character; it cannot be used in front of the repetition meta-characters, nor (in general) in front of more complicated structures which are described in the next two sections. However, repetition can be used before negation, as in r/^~$L/ which matches an arbitrarily long sequence of non-letters. 7.4.8 Grouping Round brackets are used in regular expressions to group parts of the expression. A group can be preceded by one of the repetition meta-characters. For example, r/1234#(5678)/ matches '1234', '12345678', '123456785678', etc. Note that the negation meta-character may not in general be used before a group. (See below for one special case.) Within a group there is the possibility of alternation. -51- 7.4.9 Alternation If a vertical bar appears in a regular expression, it specifies alternation, that is, it divides the expression (or sub-expression within brackets) into two alternative patterns to be matched against the line. The alternatives are matched in parallel, so that if both patterns match, the earlier matching string is found. A simple example is r/cat|dog/ This differs from the search expression (/cat/ | /dog/) in that it guarantees to find whichever of the two strings comes first in the line, should they both be present. If this is not important, the search expression should be used in preference, as it is more efficient. Much more complicated alternations are possible, and of course there can be more than two alternatives. A null alternative is permitted. The expression r/cat(|er(pillar|er))/ matches 'cat' or 'caterpillar' or 'caterer'. 7.4.10 Negated alternation In general, the negation meta-character may not appear immedi- ately before a group, since its effect is confined to the testing of a single character. However, there is one special case where it is permitted. This is when each alternative in the group defines precisely one character and does not itself contain a negation. For example, ~(a|e|i|o|u) matches any character that is not a vowel ~($p|$d|a|e|i|o|u) matches any letter that is not a vowel ~(a-f|A-F|0-9) matches any non-hex-digit Null alternatives and nested brackets are not permitted. A negated alternation may be preceded by either of the rep- etition meta-characters. 7.4.11 Summary The characters of a qualified string are interpreted as a regular expression if the R qualifier is present. Within such a string, when interpreted using NE's default syntax, the following meta-characters have special meaning: -52- ? wild character " quote character # zero or more repetitions ^ one or more repetitions $ introduces character type or hex - character range ~ negation ( start of group ) end of group | alternation The possible letters that may follow '$', and their meanings, are A alphanumeric character D decimal digit H hex character or range L letter P punctuation - not letter or digit S white space - a space or tab W word character $A and $L are case-sensitive when verbatim matching is in effect. 7.4.12 Formal syntax The formal syntax of an NE-style regular expression is as follows: ::= [*] ['|' [*]] ::= () | # | ^ | ::= ? | | ::= | - | $ | $H | $H- ::= ~ | ~( ['|' ]*) ::= A | a | D | d | L | l | P | p | S | s | W | w ::= " | or ::= (when the X qualifier is present) ::= The delimiters of the string are not considered to be part of the regular expression and, as usual, the delimiter characters may not themselves be part of the string. -53- 7.5 Unix-style regular expressions In this section, it is assumed that the UNIXREGEXP command has been obeyed, causing regular expressions to be interpreted using the syntax common in Unix systems. In fact, such expressions are translated internally into NE's own syntax before being interpreted. 7.5.1 Wild character The meta-character '.' is a wild character in a regular expression. It matches any single character whatsoever in the line being checked. Thus, for example, r/advis.r/ matches 'advisor' and 'adviser' (as well as 'advisur', 'advis!r', and so on). There may of course be more than one such character in the pattern. 7.5.2 Quoting character If a full stop, or any other meta-character, is needed as part of the data in the string, it must be preceded by a backslash character. This is a meta-character which has the effect of ensuring that the character that follows it is not treated as a meta-character. Thus, r/wh...\./ matches the strings 'whine.' and 'white.' (but not 'whip.', because three characters are needed between 'wh' and the full stop). To include a backslash itself in the data, simply double it. A backslash may appear before any character, whether it is a meta-character or not; in all cases it ensures that the following character is taken as data. 7.5.3 Repetition A full stop matches a single character; if a wild sequence of characters is required, the meta-character '*' can be used as well. It has the effect of causing the previous item in the regular expression to be matchable any number of times (including not at all). Therefore, an expression such as r/a.*b/ matches any sequence of characters beginning with 'a' and ending with 'b', including 'ab' itself. Repetition can apply to ordinary characters as well as to wild characters. The expression r/13*4/ -54- matches the strings '14', '134', '1334', '13334', etc. There is a second meta-character which causes repetition, namely '+'. It differs from '*' only in that it matches one or more (instead of zero or more) occurrences of the previous item. For example, r/embar+assing/ matches 'embarassing' and 'embarrassing' (and also 'embarrrassing', of course), but not 'embaassing'. A third repetition meta-character is '?', which matches zero or one occurrences of the previous item. 7.5.4 Character sets and ranges A non-empty string in square brackets matches any one charac- ter in the string, unless the first character in the string is a circumflex, in which case it matches any character not in the string (see below). If a closing square bracket is required in the string, it must come first, immediately after the opening square bracket. A character can be constrained to lie within a particular range of letters or digits by using a minus sign between the ends of the range, within a character set item. For example r/[g-m]/ matches any letter in the range g-m inclusive. When this syntax is used, the two limits must both be upper case letters, lower case letters, or digits. This rule is imposed to keep this feature of NE independent of the underlying character set of the machine on which it is running. 7.5.5 Negation A regular expression can specify that the next character to be matched is not a particular character, or not in a given set of characters, or not in a given range. This is done by using the meta-character '^' (circumflex) as the first character after the opening square bracket of a character set item. For example, r/ing[^a-z]/ matches occurrences of the string 'ing' which are followed by a non-letter - it would match the ends of many words, but not match on 'ingle', for example. (However, it would not match 'ing' if it occurred at the end of a line.) -55- 7.5.6 Grouping Round brackets are used in regular expressions to group parts of the expression. A group can be followed by one of the repetition meta-characters. For example, r/1234(5678)*/ matches '1234', '12345678', '123456785678', etc. Within a group there is the possibility of alternation. 7.5.7 Alternation If a vertical bar appears in a regular expression, it specifies alternation, that is, it divides the expression (or sub-expression within brackets) into two alternative patterns to be matched against the line. The alternatives are matched in parallel, so that if both patterns match, the earlier matching string is found. A simple example is r/cat|dog/ This differs from the search expression (/cat/ | /dog/) in that it guarantees to find whichever of the two strings comes first in the line, should they both be present. If this is not important, the search expression should be used in preference, as it is more efficient. Much more complicated alternations are possible, and of course there can be more than two alternatives. A null alternative is permitted. The expression r/cat(|er(pillar|er))/ matches 'cat' or 'caterpillar' or 'caterer'. 7.5.8 Beginning and end of line If a regular expression (in Unix style) begins with a circum- flex character, then it will match only at the beginning of a line. This is exactly equivalent to using the B qualifier on the qualified string. If a regular expression (in Unix style) ends with a dollar character, then it will match only at the end of a line. This is exactly equivalent to using the E qualifier on the quali- fied string. If a regular expression (in Unix style) begins with a circum- flex character and ends with a dollar character, it will match only if the entire line matches the expression. This is -56- exactly equivalent to using the P qualifier on the qualified string. 7.5.9 Summary The characters of a qualified string are interpreted as a regular expression if the R qualifier is present. Within such a string, when interpreted using the Unix-like syntax, the following meta-characters have special meaning: . wild character \ quote character * zero or more repetitions + one or more repetitions ? zero or one repetitions [] character set - character range within set ( start of group ) end of group | alternation ^ if first, start of line $ if last, end if line 7.5.10 Formal syntax The formal syntax of a Unix-style regular expression in NE is as follows: ::= [*] ['|' [*]] ::= () | '*' | '+' | '?' | ::= '.' | | ::= '[' [^] * ']' ::= - | ::= '\' | or ::= (when the X qualifier is present) ::= The delimiters of the string are not considered to be part of the regular expression and, as usual, the delimiter characters may not themselves be part of the string. -57- 8. CHARACTER STRING INSERTIONS A number of NE commands cause the insertion of a character string into a line. Such an insertion may replace an existing part of the line, or it may spread the line out to make room for the new material. When part of a line is being replaced, there is no requirement for the new material to contain the same number of characters. Replacement by a null string is one way of removing characters from a line. In most cases, the characters of the insertion string are not interpreted in any way. However, there are three circumstances where this is not so. In all cases the special treatment of the string must be explicitly requested by means of a string qualifier. 8.1 Wild replacements for regular expressions When a string insertion forms part of a command which first matches a search expression against the line (for example, the E or GE commands), and the search expression consists of a single regular expression, then the appearance of the quali- fier R on the insertion string causes it not to be taken as a literal string, but instead to be interpreted specially. The character '%' is a meta-character in the insertion string. It is the only such character. The character following '%' is treated specially, as follows: . If the character following '%' is the digit '0', then the entire matched string is copied into the insertion string at that point, replacing '%0'. . If the character following '%' is any other digit, then the th 'wild string' is copied into the insertion string at that point. . If the character following '%' is not a digit, then the '%' is simply removed from the insertion string, and the following character is not interpreted. In particular, the string '%%' is replaced by '%'. A precise definition of what constitutes a wild string is given below, but first here are some examples to show what can be done using this facility. The regular expressions are given in NE-style syntax. ge r/0#$d/ r/(%0)/ This command encloses in brackets any sequence of digits beginning with zero. Thus 0223 would become (0223) and 081 would become (081). ge r/[???]/ r/[%3%2%1]/ -58- This command reverses the order of any three characters that appear in square brackets. ge r/proc ^$a"(^$a")/ r/proc %1(%2,ierror)/ This command adds an extra argument, 'ierror', to procedure definitions (in some programming language) that have only one argument. The rules for the correspondence between the regular expression and the 'wild string' numbers are as follows: . If any part of the regular expression is enclosed in meta-brackets (normally used for alternatives) then that part corresponds to one wild string, whatever it con- tains. If the opening bracket is preceded (or repeated, for Unix-style regular expressions) by a repeat meta- character, the whole item still corresponds to one wild string. . In the parts of the regular expression that are not inside brackets, any repeated item corresponds to one wild string. For a 'zero or more occurrences' type of repeat, the resulting string may be null. . Any item that is not an explicit character, in the non- bracketed portion of the regular expression, corresponds to one wild string. In other words, a question mark (single wild character), character range, or character type specifier such as '$A' each correspond to one wild string. The length of such strings is always one. A negated character is a wild character. Note that meta-brackets can be used to combine a number of single-character wild strings into one, even if no alterna- tives are being used. For example, r/???/ results in three wild strings when it matches, whereas r/(???)/ results in only one. Here is a rather artificial regular expression that illustrates the rules for wild string numbering: r/>#A??(C|^DE(1|2)|Z?)BCA-NE~G$D is For example, proc .moan is comment /There's a problem here!/ proc .next is (f/something/; 5<; 5#; b// /body/) proc .uc is until h/ / do % The syntax for calling a procedure is simply to type its name. For example, unless /moon/ do .moan 5.next bf/capital/; .uc Procedures may be called recursively; that is, a procedure may call itself, or a number of procedures may be mutually recursive. A nesting limit of 150 is imposed, to catch runaway cases. A procedure definition can be cancelled by obeying the command cproc This is necessary before the procedure name can be re-used. -61- 10. SINGLE-CHARACTER COMMANDS This chapter contains descriptions of all those NE commands which consist of a single special character. With one excep- tion (the '?' command) they are all concerned with operating on the character at the current point. 10.1 The ? command The ? command is a request to NE to verify the current line. Two lines of output are always generated; a third and fourth may be present if the cursor is not at the start of the line, and if the line contains non-printing characters. The first line of output contains the line's number. If it has no number because it is an inserted line, four asterisks are output. The second line of output contains the text of the line. If the line contains only printing characters, it is output in the normal way. If, however, there are any non-printing characters in the line, then two lines of output are gener- ated. The first contains any printing characters, together with the first hexadecimal digits of the codes of any non- printing characters. The second line contains spaces in the positions of printing characters, and the second hexadecimal digits of the codes of any non-printing character. If the cursor is not at the start of the line, an additional line of output is produced, containing the character '>' in the position before the cursor. Thus, in the following example, 451. first 0 second 1 third 5 F > The current line is number 451, and it contains two non- printing characters whose codes are 05 and 1F in hexadecimal. The cursor is positioned at the second of these characters. Although the ? command is mostly used when operating in line- by-line mode with automatic verification suppressed [VERIFY], it can be useful in screen mode for displaying the hexadecimal values of any non-printing characters that a line may contain. 10.2 The > and < commands These two commands move the current position one character to the right or left in the current line respectively. They never cause another line to become current. If < is obeyed at the start of a line, it has no effect. If > is obeyed at the end -62- of a line it has the effect of moving the current point beyond the end of the line. Neither of these commands is affected by the margin value. They are both faulted if obeyed when the end-of-file pseudo-line is current. 10.3 The # command The # command has the effect of deleting the character at the cursor position and closing up the rest of the line by moving the remaining characters one place to the left. The cursor position is not moved. A second # command therefore deletes the next character. If a known number of characters are to be deleted, the standard repetition count mechanism can be used, for example 25# Such repetition is optimised and is more efficient than obeying the equivalent number of successive # commands. 10.4 The $, % and ~ commands These commands operate on the case of the character at the cursor position, provided that it is a letter. (Note that the case of whole lines can be forced by the UCL and LCL commands.) The single-character commands act as follows: $ force lower case (small letter) - Dollar for Down % force upper case (capital letter) - Percent for uP ~ change to the opposite case If the current character is not a letter, no change is made to it. The cursor is always moved one character position to the right after each of these commands, whether or not the current character was a letter; a second occurrence therefore affects the following character. If a known number of characters are to have their case changed, the standard repetition count mechanism can be used, for example 25$ Such repetition is optimised and is more efficient than obeying the equivalent number of successive $, % or ~ commands. 10.5 Single-character commands in line mode When NE is being used as a line-by-line editor, the single- character commands can conveniently be placed under the veri- fication of the line they are to affect. The following example shows a line's verification followed by a line of single- character commands, and then the verification of the changed line. -63- 99. the quoick BROWN ffox ~>>>>>#>>>>$$$$$># 99. The quick brown fox > The cursor is left immediately following the '>' character, so subsequent single character commands may be entered immedi- ately. It is in order to make this kind of editing possible that NE does not output its normal 'NE>' prompt in addition to line verification when operating line-by-line. -64- 11. SEARCH COMMANDS Two commands are provided for searching forwards and backwards in the file. The command names are F and BF, and they take a single search expression as an argument. A third command, DF, acts like F, but deletes the lines between the starting point and the found line. For example, f/mousetrap/ f bs/subroutine/ bf (/if/ | /unless/ | /while/ | /until/) bf (rv/A#$dZ/ | p//) df/endproc/ 11.1 The F command For the F command, the search begins at the current point (including the character at the cursor position) unless one of the following conditions holds: . The cursor is past the last character in the line. . The cursor is not at the start of a line and the search expression is a qualified string containing the B or P qualifiers. . The cursor is not at the start of a line and the search is a line search. A line search is one which, if successful, results in the identification of a complete line, rather than a string within a line. If the argument to the F command is a search expression in brackets or a qualified string containing the N qualifier, the search is a line search. In all of these cases, the search begins at the first character of the line which follows the current line. If the search expression is a qualified string containing the H qualifier, the search begins at the cursor position. If the initial match fails, subsequent tests are applied at the start of each successive line only. In other words, the H qualifier has the same effect as the B qualifier except on the first line that is searched. If the end of the file is reached without a match being found, an error message is generated and the current point is not altered. When a match is found, the current point is moved to just beyond the string or line which has been identified. For a line search, therefore, the current point ends up just past the end of the line, while for a string search (one that finds a string within a line) it is left just after the string. For example, suppose the file contains the following line: -65- The quick brown fox jumps over the lazy dog. Then the command f /fox/ leaves the cursor on the space character after 'fox', but if the command f n/kangaroo/ matches this line (because previous lines do contain 'kanga- roo') then the cursor is left after the final full stop. 11.2 The BF command The BF command operates exactly as the F command, but in the opposite direction. That is, it searches backwards from the current point. The search begins at the character preceding the current point unless one of the following conditions holds: . The cursor is at the first character in the line. . The cursor is not past the end of a line and the search is a line search. In both of these cases, the search begins at the last character of the line before the current line. If the start of the file is reached without a match being found, an error message is generated and the current point is not altered. When a match is found, the current point is moved to the start of the string or line which has been identified. For a line search, therefore, the current point ends up at the beginning of the line, while for a string search it is left on the first character of the string. For example, suppose the file con- tains the following line: The quick brown fox jumps over the lazy dog. Then the command bf /fox/ leaves the cursor on the first character of 'fox', but if the command bf n/kangaroo/ matches this line then the cursor is left at the beginning of the line. -66- 11.3 The DF command The DF command operates exactly like the F command, except that all lines from the starting line (inclusive) until the line before the new current line are deleted. If DF fails to match, then no lines are deleted. 11.4 Repeating search commands An F, BF, or a DF command can be given without an argument, in which case it repeats the most recent search (which may have been an F, BF, or a DF command) in the appropriate direction. When screen editing, the {KEYSTRING-7} and {KEYSTRING-17} keystrokes (in their default settings) cause such an F or BF command to be obeyed, respectively. If a successful F command is immediately followed by BF without an argument (or vice versa) the effect is to move the current point to the other end of the string or line which has just been found. The general command repetition facility can also usefully be used with the F and BF commands. A command such as 4f/white rabbits/ finds the fourth occurrence of the string 'white rabbits', starting from the current position. -67- 12. CURRENT POINT MOVEMENT There are, in addition to the search commands, a number of other commands which move the current point about the file, and they are described in this chapter. 12.1 The > and < commands These single-character commands for moving the current point within the current line have already been described in chapter 10. 12.2 The BACK command NE keeps a record of the twenty most recent regions of each buffer where modifications have taken place. Roughly speaking, a 'region' corresponds to a screenful of lines. The command BACK returns to the most recent region. By default, the keystroke {KEYSTRING-59} (default CTRL/UNDERLINE) obeys a BACK command. The following actions cause NE to start a new region: . Any of the keystrokes {SCROLL-UP}, {SCROLL-DOWN}, {SCROLL-TOP}, or {SCROLL-BOTTOM}. . Scrolling caused by moving the cursor off the top or bottom of the screen; . Obeying any of the commands F, BF, DF, I, M, N, or P. If a new region is selected, but no changes are then made to the file, then that region is not remembered. In this state, obeying BACK once returns to the most recently changed region, and pressing it a second time returns to the region before that. A succession of BACK commands (with no intervening changes to the file) then cycles round the twenty most recently changed regions. Once changes have been made in a region, it becomes eligible for remembering. If BACK is obeyed in this state, the current region is remembered, and the cursor is moved to the previous region. Obeying BACK a second time returns to the region where it was first pressed. A succession of BACK commands (with no intervening changes to the file) then cycles round the changed regions. Special action occurs when the I command is obeyed, either to insert a file or to insert lines directly from the command input. Both the top and bottom of the inserted material are remembered as separate regions. The cursor is left at the bottom of the inserted material; obeying BACK moves it to the top of the inserted material. A second BACK moves to the -68- bottom again, and subsequent BACK commands then move to previously remembered regions. Special action also occurs after a global command (GA, GB or GE), when BACK has the effect of moving to the last position in the file that was altered by the global command. Previously altered positions are not remembered. The following types of use are envisaged for BACK: . While making changes at one point in a file, other parts of the file are often consulted. A single keystroke brings the cursor back to the original area of editing. . While editing a file, if {SCROLL-TOP} or {SCROLL-BOTTOM} is pressed accidentally (which is quite easy to do on some keyboards) simply pressing {KEYSTRING-59} is enough to return to the point of editing. . A part of a file can be cut out, moved elsewhere, and then editing resumed at the cutting point. . While writing a program, it is easy to switch between the head of a procedure (for declarations) and its body. 12.3 The M command The M command is used to move to a particular line by reference to its line number. When the file that is to be edited is read, the lines are counted, and each line is allocated the appropriate line number. Lines retain these numbers for the duration of the editing session, unless the RENUMBER command is obeyed. Deleting a line does not result in a re-numbering of the subsequent lines, as happens in some other editors. New lines that are inserted into the file are un-numbered, and cannot become current via the M command (unless the whole set of lines is subsequently renumbered with the RENUMBER com- mand). Lines which are moved about in the file by cut-and- paste operations lose their numbers and behave as inserted lines. A single argument is required for the M command. It is either a string of decimal digits, or the single character *, which is used conventionally to refer to the end of the file. There need not be a space between the command and its argument. For example, m1234 m9 m* m0 -69- The lines in the file are numbered starting from one. However, the number zero is permitted as an argument to the M command. It causes NE to move to the first line in the buffer, without regard to its line number. If an M command succeeds, the current position is moved to the first character of the appropriate line; if it fails, the current position is not changed. When screen editing, the keystrokes {KEYSTRING-8} and {KEYSTRING-18} are set up to obey the commands M* and M0 respectively. The keystrokes {SCROLL-BOTTOM} and {SCROLL-TOP} perform the same functions, except that they do not alter the horizontal position of the current point. However, not all keyboards have dedicated keys that can be bound to these functions. 12.4 The N command The N command moves the current position to the first charac- ter of the next line in the file. It can be used with a repeat count to move forwards by a given number of lines, for example 150n If it is obeyed when the current line is the last in the file, the current point is moved to the start of the end-of-file pseudo-line. This line becomes a real line only if characters are inserted into it (at which point it ceases to be the end- of-file line). If N is obeyed while the end-of-file line is current, an error is caused. 12.5 The P command The P command moves the current position to the first charac- ter of the previous line in the file. It can be used with a repeat count to move backwards by a given number of lines, for example 150p If it is obeyed when the current line is the first in the file, an error is caused. 12.6 The PA and PB commands The PA and PB commands move the cursor by context within the current line. The names of the commands are abbreviations for 'point before' and 'point after'. Each takes a search expression as an argument. The current line, starting from the current point, is matched against the search expression. If there is no match, an error occurs. Otherwise the current point is moved to the first character that matched (PB) or -70- just after the last character that matched (PA). For example, if the current line is Scherzo in G Op. 6 then the command pa/zo/ places the cursor just after the word 'Scherzo'. 12.7 The PLL and PLR commands These two commands, which take no arguments, move the cursor to the extreme left or extreme right of the current line, respectively. The command names are abbreviations for 'pointer to line left' and 'pointer to line right', respectively. The keystrokes {KEYSTRING-6} and {KEYSTRING-16} are set up by default to obey PLL and PLR. When the current line is not wider than the screen, these commands are synonymous with the {FIRST-CHAR} and {LAST-CHAR} keystrokes respectively. When editing long lines, however, they move to the true beginning and end of the line respect- ively, causing a horizontal scroll if necessary. 12.8 The TOPLINE command The TOPLINE command has no effect unless NE is in screen editing mode. When this is the case, TOPLINE causes the screen to be re-displayed with the current line at the top. The position of the current point is not altered. The keystroke {KEYSTRING-58} (default CTRL/CIRCUMFLEX) is set up to call TOPLINE by default. Placing the cursor on a particular line and pressing {KEYSTRING-58} therefore has the effect of moving the line where the cursor is to the top of the screen. TOPLINE can also be useful in command lines such as F/procedure/;topline If TOPLINE appears in the middle of a command line, and subsequent commands on the same line change which line is current, then the effect of TOPLINE may be lost. What happens when TOPLINE is obeyed is that NE remembers the line which is current at that time. When the screen is subsequently re- drawn, if the current line (which might have been changed as the result of other commands) will be visible with the remembered line at the top of the screen, then the screen is written like that. Otherwise, the information saved by TOPLINE is ignored. Thus, the following two command lines are not equivalent: -71- m23; topline; p m23; p; topline For this reason, TOPLINE should normally be the last command in a line. -72- 13. CHANGING THE CURRENT LINE This chapter describes a number of commands for making changes to the current line. In addition, there are a number of single-character commands which affect the contents of the current line. These are described in chapter 10. 13.1 The A, B and E commands These three commands make contextual changes to the current line. Each takes two arguments: a search expression that defines which part of the current line is to be altered, and an insertion string to be put into the line. The difference between the commands is that . The A command inserts the string after the text which matches the search expression; . The B command inserts the string before the text which matches the search expression; . The E command exchanges the text which matches the search expression for the insertion string. The search for the given context in the current line starts at the cursor position. After the command is obeyed, the cursor is moved so that it follows the last affected character in the line. For example, if the current line is In describing the experiences of the with the cursor at the start of the line, then after obeying the command a/describing/ / briefly/ the line becomes In describing briefly the experiences of the and the cursor is left following the word 'briefly'. If the commands b/experiences/ /novel /; e/the/ /a/ are now obeyed, the line becomes In describing briefly the novel experiences of a Note that is is the second occurrence of the word 'the' which is changed, because the cursor is left after 'experiences' by the B command. -73- If an A, B or E command has a first argument which specifies a line search, that is, it contains the N qualifier or is enclosed in brackets, then the current position must be at the start of a line. If this is not the case, an error occurs. The A, B and E commands can be given without any arguments, in which case they operate by re-using the arguments for the most recent such command. 13.2 The DTA and DTB commands These two commands delete characters from the line, starting at the cursor position, and ending either after or before a matched qualified string, respectively. For example, dta w/foxes/ There is an error if the qualified string does not match on the current line. 13.3 The LCL and UCL commands These two commands have the effect of converting any letters in the current line at and following the cursor position to lower case or upper case respectively. The cursor is moved to just beyond the end of the line, unless it was already further to the right. -74- 14. INSERTING TEXT INTO THE FILE There are a number of ways of inserting text into a file. The cut and paste facilities are described in the chapter on screen editing, and the equivalent commands are described in the chapter entitled Keystroke commands. The use of the I command for inserting whole files is described in the chapter entitled File operations. The remaining commands are described here. 14.1 The I command The I command can be used to insert a whole file into the text, and this is described in the chapter on file operations. It can also be used to insert lines of text from the command stream. If I is obeyed with no argument, it causes successive lines of command input to be inserted into the edited file before the current line, until a line containing only the letter 'z' (in upper or lower case) is encountered. This line serves to terminate the insertion; it is not itself inserted into the file. For example, to insert some lines before line 345: m345; i Here are some inserted lines to go before line 345. z The cursor position is not changed by the I command. This form of the I command is normally used when editing line-by-line, but it can be used while screen editing, in which case the input takes place in the command area at the bottom of the screen. If NE is running interactively, it prompts for each successive line of insertion only if screen editing is in progress. The prompt text is the string 'NE<' instead of the normal command prompt 'NE>'. No prompts are given in line-by-line mode. 14.2 The ICURRENT command The ICURRENT command has no arguments. It has the effect of inserting a copy of the current line immediately before the current line. The cursor position is not changed. The command repetition facility can be used with ICURRENT to replicate a line any number of times. 14.3 The ILINE command The ILINE command can be used to insert a single line of text before the current line. It takes a delimited string as an argument - this is the text of the line to be inserted. The -75- cursor position is not changed. The argument of ILINE may be given with the X qualifier, in order to specify a new line as a string of hexadecimal pairs representing the characters of the line. -76- 15. SPLITTING AND JOINING LINES When screen editing, lines can be split and joined using the {SPLIT-LINE} and {CONCATENATE} keystrokes, as described in chapter 4 above. There are also the following commands for performing these operations. 15.1 The SA and SB commands These commands split the current line after or before a given context, respectively. They take a single search expression as an argument. For example, if the current line is The cow jumped over the moon then the command sa/jumped/ turns it into the following two lines: The cow jumped over the moon The search for the given context takes place in the current line only, starting from the cursor position. By default, the second part of a split line is made into a new line with its first character in column one. It is, however, possible to arrange that this line is given the same indent as the previous one, by using the AUTOALIGN command to set autoalign mode. For details, see the chapter entitled Changing default operations below. 15.2 The CL command The CL command concatenates the current line with the follow- ing line. It may be followed by an optional string argument, which defines a string of characters to be inserted between the two lines. The cursor is left at the start of what was the second line. If the cursor is beyond the end of a line when CL is obeyed, spaces are added to the line to lengthen it to the cursor position before the second line is joined on. -77- 16. DELETING PARTS OF THE FILE Several ways of deleting text exist. The DMARKED command is an exact analogue of the screen editing keystroke {DELETE- MARKED}, and is described in the chapter entitled Keystroke commands. The DF command is described in the section 11.3. 16.1 The DLINE command The DLINE command, which takes no arguments, deletes the current line from the file and moves the cursor to the first character of the following line. The normal command repetition facilities can be used to delete a number of lines. For example 23dline deletes twenty-three lines, starting from the current line. 16.2 The DREST command The DREST command, which takes no arguments, deletes the current line and the remainder of the file which follows it. The use of DREST speeds up NE's processing, because it does not need to read from the disc those lines which it has not yet got in main memory. -78- 17. RESTORING DELETED TEXT The UNDELETE command, which by default is bound to {KEYSTRING-4}, retrieves deleted characters and lines. Up to 100 deleted lines are remembered, in reverse order. Deleted characters are held in a packed form, and up to 64 consecutive characters can be held in one 'line' for this purpose. Undeleted characters are inserted back into the text at the current point, and NE remembers whether they were deleted forwards or backwards, so that a sequence of character deletes followed by a sequence of undeletes should put the text back as it was. Undeleted lines are treated as text to be inserted at the current point. Text deleted with commands such as E/A//B is also added to the undelete stack, as is text cut out with the DELETE command (the CTRL/Q keystroke). Text cut or copied to the cut buffer is not added to the undelete stack. Note that this does not provide a general 'undo' facility. -79- 18. FORMATTING COMMANDS When new text is being entered into the file while screen editing, the position of the right-hand margin controls the maximum width of line that can be entered without special action. The user can type input continuously, without ever pressing the {SPLIT-LINE} (i.e. RETURN) key - this is known as power typing. When the right-hand margin is passed, the line is automatically split at the previous space character, which is itself deleted from the text. If there is no previous space character on the line, it is split immediately after the character in the right-hand margin position, leaving a line that is full right up to the margin. The second half of a split line is made into a new line with its first character in column one. It is possible, however, to arrange for it to have the same indent as the previous line, by using the AUTOALIGN command. For details, see the chapter entitled Changing default operations below. 18.1 The CENTRE command The CENTRE command centres the current line, ignoring leading spaces, within the current margin value. 18.2 The RMARGIN command The default margin value is one less than the width of the screen (typically 79). If NE is being run from a window-based terminal emulator such as XTERM, then the width of the window is used. The margin can be altered by means of the RMARGIN command, which takes three forms: . If given without an argument, it disables the margin without forgetting its position or, if the margin is already disabled, it enables it at the previously- remembered position. This form of the RMARGIN command is used by the {KEYSTRING-10} keystroke. On the screen display, the position of the first character beyond the maximum line width is shown by a vertical bar or a backslash in the separator lines, depending on whether the margin is enabled or disabled. When the margin is disabled, no automatic line splitting takes place. . RMARGIN can also be followed by one of the words ON or OFF which have the effect of enabling or disabling the margin, respectively, without changing its position. . If RMARGIN is followed by a number, it sets the margin position and enables the margin, whatever its previous state. The margin position need not coincide with the edge of the screen. The number specifies the maximum line width required. -80- The margin value affects only two features of NE: (1) It always controls the width of lines produced by the FORMAT command, whether it is enabled or not. (2) When it is enabled, it defines the column at which a data character causes automatic line splitting (the 'power typing' column). Characters typed beyond the margin do not cause line splitting. 18.3 The FORMAT, BEGINPAR and ENDPAR commands As well as controlling the length of input lines on the screen, the right-hand margin interacts with the FORMAT com- mand. This command, which has no arguments, causes the rest of the current paragraph of text to be reformatted so that its lines are of maximum length within the current margin. (The {KEYSTRING-20} keystroke issues a FORMAT command.) Disabling the right-hand margin does not affect the operation of the FORMAT command; it still uses the current margin setting. If the current line is the end-of-file line when FORMAT is obeyed, no action is taken. Otherwise the current line is checked to see whether it is valid as the start of a paragraph. By default, any line that is not completely empty starts a paragraph. The BEGINPAR command is used to specify an alternative defi- nition of the beginning of a paragraph. It takes a single search expression as its argument; lines which match the search expression are valid paragraph beginnings. The default state is equivalent to beginpar nps// That is, a line must contain a character other than a space to be recognized as the start of a paragraph, unless BEGINPAR has been used to specify otherwise. If FORMAT is obeyed when the current line does not match the beginning of paragraph search expression, the only action taken is to move the cursor to the start of the following line. When the current line does match, the re-formatting operation begins with the current line, and ends with the line preceding the next 'end of paragraph' line (which is defined below). The effect is as if the entire paragraph is made into one long line and then split up again so as to fit the maximum number of words into each resulting line, none of which can be longer than the margin value. A word, in this context, is any sequence of characters not including a space. -81- When two lines are joined together, a single space is inserted between them, unless there is already a space at the end of the first line or the beginning of the second, or unless either line is empty. When lines are split, space characters at the splitting position are removed. Apart from this, no changes are made to the paragraph. Sequences of multiple spaces, for example, remain. After FORMAT has been obeyed, the current point is left at the start of the line following the re-formatted paragraph. The definition of the end of a paragraph can be specified by the user by means of the ENDPAR command. This command takes a search expression as an argument, which is remembered for use by the FORMAT command. Any lines that match the search expression are taken by FORMAT as being 'end of paragraph' lines; the preceding paragraph is terminated when such a line is reached. The default state is equivalent to the command endpar (p// | b/ /) That is, a completely empty line or a line beginning with a space terminates a paragraph unless ENDPAR has been used to specify otherwise. As an example of the use of BEGINPAR and ENDPAR, consider the editing of a file that is input to the SGCAL formatting program. Changes to the text may result in lines that contain only a few words, or lines that are longer than the width of the screen, and it is often convenient to reformat paragraphs while editing, even though this is not strictly necessary. However, lines which begin with a full stop are not part of the text, and should never be re-formatted. The commands beginpar (nps// & nb/./); endpar (p// | b/ / | b/./) are therefore appropriate in these circumstances. Because FORMAT leaves the current point on the line following the paragraph, a number of paragraphs can be formatted at once by a command such as 10format or by pressing {KEYSTRING-20} a number of times in succession while screen editing. Note that the count must allow for any blank lines between paragraphs. -82- 19. GLOBAL CHANGES It is often necessary to make systematic changes in a file, for example to change the spelling or capitalization of a particular word. Three commands which operate in a similar way are provided for this purpose. 19.1 The GA, GB, and GE commands Each command takes two arguments, a search expression and an insertion string. The only difference between the commands is the way in which each change is made: . The GA command inserts the string after each occurrence of text which matches the search expression; . The GB command inserts the string before each occurrence of text which matches the search expression; . The GE command exchanges the text which matches the search expression for the insertion string. For example, to change the word 'bit' to the word 'piece' throughout a file, the command ge w/bit/ /piece/ would be used. The qualifier 'w' (word) ensures that words such as 'bite' do not get changed to 'piecee'. If a search expression enclosed in brackets is used as the first argument, it is a complete line which is matched. The command ga (np// & n/ /) / **/ adds two asterisks to any line that is not empty, but contains no spaces. If a regular expression is used as the first argument, then the second argument (the insertion string) can be interpreted specially, by use of the R qualifier. In this case the character '%' is used to trigger the insertion of wild strings encountered during the matching process. The insertion string may also be given in hexadecimal, if the X qualifier is used. Details of both these facilities are given in chapter 8. A global command can be given with no arguments, in which case it re-uses the arguments of the most recent global command. A global command searches forwards in the file from the current point until the end of the file or the global marker (see below) is reached. The search is carried out in exactly the same way as for the F command. When a global command -83- finishes normally, the current point is restored to what it was at the start. Therefore, a repeated global command or a number of global commands on the same command line all act from the same point in the file. If no match is found, an error occurs if editing is interac- tive. When NE is running non-interactively, the absence of any matches is not an error. The file is unchanged and the current position unaltered. When a match is found, the subsequent action depends on whether NE is running interactively or not. 19.2 Interactive global commands When NE is running interactively, the global commands interact with the user, making it possible to change some of the matched strings and not others. When a match is found, NE behaves as follows: If screen editing is taking place, the screen is updated to show the new current position, with the characters which matched shown in inverse video. When it is necessary to re- draw the screen to do this, the line containing the matched characters is placed near the top, in an attempt to minimize the amount of screen updating during the global command. In line-by-line mode the line which matched is verified. Then the prompt Change, Skip, Once, Last, All, Finish, Quit or Error? is displayed, and NE waits for the user to reply. The reply must be the first letter of one of the words in the prompt string, followed by {ENTER}; the possible actions are as follows: . Change: the line is changed, and NE searches for the next match, starting from the character following the matched or inserted text, whichever is the rightmost in the line. . Skip: the line is not changed; NE searches for the next occurrence of the search expression starting from the character following the matched text. . Once: the line is changed, and the global command then terminates. The current point is put back to where it was at the start of the command. . Last: the line is changed, and the global command then terminates. The current point remains immediately after the last change. . All: the line is changed, and NE searches for the next match. All subsequent matching strings are changed with- out prompting. When the end of file (or global marker - -84- see below) is reached, the command terminates and the current point is put back to where it was at the start. . Finish: the line is not changed, but the global command terminates. The current point is put back to where it was at the start. . Quit: the line is not changed, but the global command terminates. The current point is not put back to where it was at the start. . Error: the line is not changed, but the global command terminates abnormally (though no error message is given). This means that any further commands that were given on the same command line are not obeyed, and NE awaits a new line of commands. The current point is put back to where it was at the start of the global command. It is possible to give several responses in a single reply to a global interaction prompt. For example, cccssc means 'change three occurrences, skip two, then change one more'. Furthermore, repeat counts can be embedded in the string. The following response has the same meaning: 3c2sc Spaces are allowed in the reply string and are ignored. If the response string contains anything other than spaces, digits, or the allowed response letters, it is rejected before any action is taken, and the prompt is re-issued. After one prompt has been given, reaching the end of the file or the global marker is no longer an error. If it happens, the message 'no more' is output, and the command terminates. At the end of an interactive global command, NE displays the number of matches and the number of changes made at the bottom of the screen, and the cursor is reset to where it was before the command began executing, except when either the 'q' or 'l' response was used to terminate it. This happens whether or not the command was successful. 19.3 Non-interactive global commands When NE is running non-interactively, a global command always affects all occurences of any text which matches the search expression, between the current point and the end of the file or the global marker. If no occurrence is found, however, no error occurs. At the end of the command the cursor is reset to where it was before the command began executing. -85- If a GA, GB or GE command is obeyed from inside a command file called by the C, CBUFFER, or CDBUFFER commands, it behaves in non-interactive fashion, and does not prompt for confirmation before making changes. 19.4 Continuing after a match When a global command resumes searching the file after a match, it starts at the first character beyond the string that it has just matched. This avoids any problems with accidental recursion. However, it can sometimes lead to unexpected results. For example, the following command might be expected to replace all occurrences of a double space between words by a single space: ge r/$l $l/ r/%1 %2/ However, if a word consisting of only one letter has double spaces on either side of it, this command changes only the first pair of spaces. If it is required, as in this example, to re-scan previous text, then combinations of other NE commands must be used instead of a global command. 19.5 Null strings in global commands The use of a null string as the first argument in a global command is forbidden, unless one of the qualifiers B, E or P appears. For example, gb b// /*/ ga e// / !!/ When such a global is obeyed in screen mode, and a prompt is issued, a single character is displayed in inverse video to indicate the position of the null string. It is the character following the string's position. 19.6 Globals with margins or long lines The right-hand margin setting does not affect the operation of the global commands; the entire text of each line is searched, as for the F command. The margin is automatically disabled for the duration of each global command. Automatic scrolling of the window to left or right occurs as necessary to show the matched text. For a GA command the window is adjusted so as to show the end of the text; for the other commands it is the beginning of the text which is always shown. -86- 19.7 The global marker Global commands normally operate from the current point to the end of the file. However, an endpoint can be set earlier in the file. This takes the form of a marker similar to those used for block and multi-line operations. It is set and unset when screen editing by the keystroke {MARK-GLOBAL}, (default CTRL/N) exactly like the other marks, and the message Global limit set appears at the bottom of the screen when it is set [MARK]. Only one kind of mark can be set at one time. The global limit marks the end of the search for a match when a global command is being obeyed. If the current point is past the global mark when the search is started, the limit has no effect. Global commands always work forwards through the file. -87- 20. BUFFER HANDLING An NE buffer is a separate area of memory which can hold text for editing. As well as its contents (lines of text), a buffer has an associated file name, a title, and a right-hand margin. The title is by default the same as the file name, and is displayed in the bottom separator line when screen editing. Each buffer has a number, starting from zero. Buffer zero is automatically created when NE is entered. Other buffers may also be created during initialization if more than one input file name is given on the command line. As well as the numbered buffers, there is one special buffer known as the cut buffer which is used for holding text which has been cut or copied from the file. Its use is described in section 4.11 (Cutting, pasting and block deletion). The description of NE so far has assumed that a single file is being edited at any one time. In fact, NE makes it possible to edit more than one file at once, and to move material between files as necessary. 20.1 The TITLE command The TITLE command can be used to change a buffer's title string. The title is the string which is used in all displays and prompts to identify the buffer. By default it is the same as the name of the file associated with the buffer; the MAKEBUFFER, NEWBUFFER, LOAD, and NAME commands, which set up new file names, also set the title to be the same as the file name. The SAVE command does the same when it changes a buffer's file name. The argument to TITLE is in the same format as a file name, that is, it can be an undelimited string, terminated only by end of line or semicolon. However, the standard file name delimiters can be used if required, and are necessary if the string contains a semicolon or begins with a backslash. 20.2 The RENUMBER command The RENUMBER command causes all the lines in the current buffer to be renumbered, starting from one. Whichever line is current remains current after the renumbering, though its number may be changed. 20.3 The DETRAIL command NE normally takes no special action over trailing spaces in text lines. They are treated like any other character. However, the DETRAIL command is provided to vary this action. It can be used in two ways: -88- . If DETRAIL appears with no arguments, it causes all trailing spaces in the current buffer to be deleted. . If DETRAIL appears followed by the word 'output', then trailing spaces are removed from each line when it is output. 20.4 The NEWBUFFER command The NEWBUFFER command is used to create additional buffers. There is no limit to the number which may exist, other than that imposed by the amount of available memory. If NEWBUFFER is obeyed without an argument, it creates an empty buffer, with no associated file name. If the command name is followed by a file name, that name becomes associated with the new buffer and the contents of the file are read into the new buffer for editing. The title of the new buffer is set to the file name. If the name of a non-existent file is given, some operating systems may create an empty file (possibly only if an appropriate option is given); others may force an error. The right-hand margin is copied from the current buffer for newly-created buffers. If the current buffer is marked read-only, then the newly- created buffer is also so marked. When a NEWBUFFER command is successfully obeyed, NE automati- cally selects the new buffer as the current editing buffer. In the screen display, an additional item appears in the bottom separator line when more than one buffer exists. It is the number of the displayed buffer, enclosed in square brackets, following the file name. Any commands which follow NEWBUFFER on the same line are applied to the new buffer; for example newbuffer another.file; f/something/ creates a new buffer, reads the file another.file into it, and searches for the word 'something' in the new file. 20.5 The MAKEBUFFER command This command operates like NEWBUFFER, but allows (indeed, requires) the user to specify the number of the buffer which is being created, for example: makebuffer 19 somefile If a buffer of that number already exists, an error occurs. The newly-created buffer is not made the current buffer, in contrast to the behaviour of NEWBUFFER. This command is useful in NE command files where the number of the buffer is needed for use in other commands. -89- 20.6 The BUFFER command The BUFFER command is used to switch between existing buffers. If given without an argument, it cycles round the buffers in reverse order of creation. However, an explicit buffer number can be given as an argument if required. The {KEYSTRING-1} keystroke is set up by default to obey a BUFFER command with no argument. 20.7 The NAME command The NAME command is used to change the file name associated with a buffer (or to give a name to a buffer that was created without one); it takes a file name as an argument. This command also sets the title of the buffer to the new file name. Changing the file name of a buffer has the effect of marking the buffer 'changed', so that when the NE run ends normally, the contents of the buffer are written to the named file (subject to user confirmation if interactive). 20.8 The DCUT command The DCUT command deletes the contents of the cut buffer. This command is only necessary when the cutting style is set to 'append' [CUTSTYLE], as otherwise each cutting operation over- writes what is already in the buffer. The DCUT command does not prompt if the cut buffer has not been pasted; it can therefore sometimes be of use in command sequences as a means of suppressing this prompt. 20.9 The DBUFFER command The DBUFFER command deletes all the lines in a buffer, closes any associated files, and then deletes the buffer itself, unless it is the only buffer. DBUFFER can take a buffer number as an argument, or can be given on its own, in which case it refers to the current buffer. If the object of DBUFFER is the current buffer and there are no other buffers, then the effect is simply to delete all the lines in the buffer and close any associated files. If there are other buffers, then the effect is as if a BUFFER command had been obeyed first (i.e. the previous buffer is selected), and then the object buffer is completely destroyed. If the contents of the object buffer have not been saved, NE prompts and asks for confirmation before proceeding with a DBUFFER command when running interactively, unless prompting has been suppressed by means of the PROMPT or WARN commands. -90- 20.10 Copying between buffers Copying or moving data between buffers can be carried out using the standard cut-and-paste operations. There is only one cut buffer, so the process is as follows when editing on the screen: . The source buffer is selected, and the text or rectangle is cut or copied to the cut buffer in the usual way, using the keystrokes {MARK-TEXT}, {MARK-RECTANGLE}, {CUT- COPY} and {CUT-DELETE} as appropriate. . The destination buffer is selected, the cursor is moved to the insertion position, and the text or rectangle pasted in using the keystroke {PASTE}. When using one buffer solely as a source of text for insertion in another, it is better to use the {CUT-COPY} keystroke rather than {CUT-DELETE} because this avoids marking the source buffer as 'changed'. An alternative way of inserting a complete file is to use the I command, which is described in the next chapter. -91- 21. FILE OPERATIONS This chapter contains descriptions of those NE commands that operate on whole files. The format of file names is system- dependent, and details are given in the chapters describing each system's interface. 21.1 Loading a new file The LOAD command takes a file name as an argument. It causes all the lines in the current buffer to be deleted and any associated files to be closed. The named file is then opened for input, and its contents read into the current buffer. The title of the buffer is set to the file name. If the contents of the current buffer have not been saved, NE prompts and asks for confirmation before proceeding with a LOAD command when running interactively, unless prompting has been disabled by means of the PROMPT or WARN commands. 21.2 Inserting files To insert the entire contents of a file into the text which is being edited, the I command is used, taking as its argument the name of the file to be inserted. The I command can be used in another form for inserting in-line material; this is described in chapter 14 above. An example of the use of I for inserting a whole file is i myfile The lines of the file are inserted immediately prior to the current line. The actual position of the current point in the current line is not relevant, but it is not altered. If a BACK command is obeyed immediately after an I command, it moves the current point to the top of the inserted material. The newly inserted lines do not have line numbers, as they are not part of the original file which is being edited. It is therefore not possible to move around in the new text by means of the M command, unless all the lines in the buffer are renumbered [RENUMBER]. An alternative way of merging files is to use a second editing buffer and cut-and-paste operations. In this case it is possible to use the M command to move around the second file. -92- 21.3 Saving files The SAVE command is used to cause the contents of the current buffer to be written to a file, without leaving NE. The command can be given with or without a file name as an argument. If SAVE is given without an argument, the file name associated with the current buffer is used by default. (The NAME command can be used to change the file name associated with the current buffer.) If NE is running interactively when SAVE is obeyed without an argument, it issues the prompt Write to ? (Y/N/TO filename) unless there is no name associated with the buffer, in which case the prompt is Write? (N/TO filename) If prompting for the buffer has been disabled by means of the PROMPT command, then a prompt is issued only when there is no associated file name. When a prompt is issued, if the reply is Y or YES, the contents of the current buffer are written to the file whose name is displayed. The buffer is marked 'not changed' so that if no further changes are made to the contents, NE will not attempt to write them again when it is finishing. The Y response is only valid for the first form of the prompt. If the reply is N or NO it is assumed that a mistake has been made; NE abandons the current line of commands and issues its standard prompt for another command line. A reply of the form TO is a request to write the contents of the buffer to an alternative file. NE attempts to open this file and write the text to it instead of to the file named in the prompt. Provided the file is successfully opened, the buffer is marked 'not changed' and its name and title are changed to the new file name. If the SAVE command is given with a file name as an argument there is no prompting; the effect the same as when a new file name is given in response to the prompt. 21.4 The WRITE command The WRITE command is used to write the contents of the current buffer to a file, without changing the name of the buffer (cf SAVE). It is always followed by a file name as an argument. If a line mark has been set (by means of {MARK-LINE} on the screen, or via the MARK command) then only those lines between the marked line and the current line, inclusive, are written -93- to the file. Otherwise the entire contents of the current buffer are written. The mark may precede, follow, or be on the current line. It is automatically removed by the WRITE command unless it has been 'held' by pressing {MARK-LINE} twice. 21.5 The BACKUP command NE does not at present contain any facilities for automati- cally backup up the state of the editing session. In some operating systems there is an established convention for renaming files which are about to be over-written. If the command backup files on is obeyed, then NE adopts the operating system's convention. When an output file is to be opened for the first time in an editing session, any existing file of that name is renamed first. The system-specific chapters at the end of this manual give details of the renaming process. The word 'on' can be replaced by 'off' to turn this facility off during an editing session. If the command is given with neither 'on' nor 'off', then the state of the option is inverted. -94- 22. EDITING LARGE FILES Normally, NE loads complete files into main memory for edit- ing, making it possible to move to any point in the file at will. On some systems the amount of main memory is limited, and so large files cannot be edited in this manner. NE contains some simple support for handling such files. A buffer can be marked as a stream buffer, in which case it is permitted to contain no more than a certain number of lines. When the number of lines exceeds the maximum, earlier lines are written to the output file. There is no support for rewinding; this is a one-pass scheme. A command of the form ne -to -stream [] is used to edit a file in stream mode. The -to option is mandatory if -stream is given. The number after -stream is the maximum number of lines to be held in the buffer at any one time. If omitted, it defaults to 1000. The minimum permitted value is 500. From within NE, an existing non-stream buffer can be converted to a stream buffer by the command stream This sets up the output file for the stream, and writes out any initial lines if the buffer is already over the limit. A stream buffer cannot be turned back into a normal buffer. The STREAMMAX command can be used to change the line number limit on an existing stream buffer. It also sets the limit for any buffers that are subsequently made into stream buffers. The SHOW BUFFERS command outputs 'stream' instead of giving a line count for stream buffers. A number of commands are not permitted in stream buffers (for example, RENMUMBER). The SAVE command is permitted with no argument; it writes the rest of the file to the output, and then deletes the buffer. This makes it possible to load and process files in stream mode without exiting from NE. When the -stream option is used on the command line, the output file is opened early, before any commands have been obeyed. Therefore the use of the BACKUP command in an initialization string or the -opt option does not affect it. If it is desired to apply the BACKUP FILES option to a stream output file, the STREAM command should be used instead of the -stream option. -95- 23. CONDITIONAL COMMANDS The commands IF and UNLESS can be used to control whether other commands are obeyed according to the result of certain tests. The syntax is if then [[;] else ] unless do [[;] else ] where is either a single NE command or a group of commands enclosed in round brackets. The command or command group may be empty. The ELSE part of these commands is optional, and may optionally be preceded by a semicolon. The keywords THEN and DO are synonymous, and can be used interchangeably. The conditional commands can be continued over several lines of input, provided that the line breaks occur within round brackets, and between commands. If the entire command is enclosed in round brackets, or if it is being read from a non- interactive source of input, then a line break immediately before ELSE is also permitted. The can take one of the following forms: . If is a search expression, then this is tested against the current line. If it matches, then is 'true'; otherwise it is 'false'. . If is the word EOF then is 'true' if the current line is the end-of-file line. . If is the word SOF then is 'true' if the current line is the first line of the file, and the cursor is at its start. . If is the word SOL then is 'true' if the cursor is at the start of the current line. . If is the word EOL then is 'true' if the cursor is at the end of the current line. . If is the word MARK then is 'true' if the current line is marked by the line ({MARK- LINE}) mark. . If is of the form prompt and NE is running interactively, the user is prompted with the given string, and must reply with YES, Y, NO or N. If the answer is affirmative, then is 'true'; otherwise it is 'false'. If NE is not running interactively, is always 'true'. -96- When is 'true' the THEN part of an IF command is obeyed; when it is 'false' the ELSE part, if any, is obeyed. For an UNLESS command, the opposite occurs. Here are some examples of conditional commands: if mark then break; if eof then (comment/Reached EOF/; stop) if /cat/ then ( comment/It's a cat/ ) else ( comment/It's not a cat/ ) unless (/pig/ & n/brown/) do dline (if prompt/Shall I?/ then e/something//other thing/ else comment/OK, I haven't/) The brackets surrounding the final example would be needed only if it were typed in interactively, to prevent the entire IF comment being terminated by the line break before ELSE. In non-interactive input, these brackets could be omitted, because NE looks ahead to check for ELSE before terminating an IF command at the end of a line. Note that if more than one command is to be conditionally obeyed, they must be enclosed in round brackets. If the brackets were omitted in the second example above, then the STOP command would always be obeyed as it would not be part of the IF command. -97- 24. LOOPING COMMANDS NE contains several commands which can be used to generate loops and change the flow of control within them. 24.1 The WHILE and UNTIL commands These two commands set up a loop which is obeyed while or until a given condition is true, respectively. Their syntax is while do until do where and take exactly the same form as for the conditional commands are described in the previous chapter, except that may not be empty. Because it is such a common case, the pseudo-command UTEOF is provided as an abbreviation for until eof do Thus the following two commands are equivalent: until eof do (f/cat/; b///tle/) uteof (f/cat/; b///tle) When a loop has EOF as its ending condition, the loop ends when the current line is the end-of-file line at the testing point (that is, when control is at the first or only command), or when an attempt is made to move beyond the end-of-file line by means of the F, DF, N or CL commands, or if one of the commands <, >, #, $, %, ~, A, B, or E is attempted on the end- of-file line. In the examples immediately above, for instance, the end of file is reached during the processing of the F command. When this happens, the loop terminates normally, without error. 24.2 The REPEAT command The REPEAT command takes a single command or a command group as its argument. This is repeatedly obeyed until an error occurs or the loop is explicitly terminated by a LOOP or BREAK command. 24.3 The LOOP and BREAK commands The LOOP command causes a jump to the repeat point of the textually enclosing looping command. The BREAK command causes a jump to just beyond the end of the textually enclosing looping command. For example, -98- repeat (n; if /last/ then break; if /skip/ then loop; t1) when applied to a file containing the lines The quick brown fox of literary repute was skipping over the trees when last seen. causes the following output to be generated: of literary repute over the trees Both the LOOP and the BREAK commands can be followed by a numerical argument which specifies the number of nested loops to be considered. Thus break 2 jumps out of two nested loops, for example, while loop 3 resumes execution at the repeat point of the third textually enclosing loop. Supplying no argument to either of these commands is equivalent to supplying the argument 1. -99- 25. INFORMATION DISPLAYS The SHOW command in NE is provided for the purpose of displaying information about the current state of the editor. It must be followed by a word indicating the information required. During screen editing, the output appears in the expanded message area at the bottom of the screen. In order to give the user time to read it, NE does not immediately return to screen editing, but outputs either a command prompt, if the command was the last on a command line, or the prompt Press RETURN to continue otherwise. In the latter case, pressing {ENTER} causes NE to proceed to the next command on the line. 25.1 Contents of a buffer The command show wordcount displays a line count, word count, and character count for the current buffer. A word in this context is any sequence of characters delimited by one or more spaces or the end of a line. The character count does not include the line separator characters (carriage return and/or linefeed) which are used on some systems to separate lines in files. The same file should produce the same output on all implementations. 25.2 Information about buffers The command show buffers causes a summary of the current contents of NE's editing buffers to be output. For each non-stream buffer a line of the form Buffer lines [(modified)] is output, where <n> is the buffer number, <m> is the number of lines in the buffer, and <title> is the title attached to the buffer, which defaults to the file name. The text '(modi- fied)' is included if the contents of the buffer have been changed since it was last saved. Otherwise spaces appear in this position. If there is no name attached to the buffer, the text '<unnamed>' is output in the title position. If the number of lines is followed by a plus sign, as for example in -100- Buffer 0 22+ lines (modified) &t it means that not all of the file has yet been read into main storage. The number given is the number of lines read so far. For stream buffers, the information given is Buffer <n> stream [(modified)] <title> since the total number of lines is not known because only part of the file is held in main memory at any time. If the cut buffer is not empty, a line of information about it is also output in the format Cut buffer <n> lines [(pasted)] <type> where <n> is the number of lines and <type> is one of the strings '<text>' or '<rectangle>'. The text '(pasted)' is included if the cut buffer has been pasted at least once. Otherwise blanks appear in this field. 25.3 Command information The command show commands causes a multi-column list of NE's command names to be output. 25.4 Keystroke information The command show keys which is obeyed when {KEYSTRING-9} is pressed, causes NE to display the definitions of three sets of keystrokes: control keys, extra keys, and function keys. It is equivalent to the three commands show ckeys show xkeys show fkeys which are described below. Because the amount of information is typically too great to fit on the screen, NE pauses between each set and outputs the message Press RETURN to continue to give the user a chance to read the output. -101- 25.5 Control keystrokes The command show ckeys causes NE to display the definitions of all the 'control-type' keystrokes that have any effect. (See Changing keystroke defaults for how to change the definitions of certain keystrokes.) These are the keystrokes that are implemented by means of the CTRL key in many cases. In the default state, a short phrase describing the action of each keystroke is given. 25.6 Extra keystrokes The command show xkeys causes NE to display details of usable keystrokes that are neither 'control-type' nor 'function-type'. Some of these (for example, the DELETE keystroke) may be configurable by the user, while others may be fixed in meaning, depending on the particular implementation of NE. 25.7 Function keystrokes The command show fkeys which is obeyed when {KEYSTRING-19} is pressed, causes NE to display the definitions of all the 'function-type' keystrokes that have any effect. These are the keystrokes that are implemented by function keys in many cases. In the default state, each function keystroke with a number no greater than 20 causes the corresponding function keystring to be obeyed as a line of commands. These strings are shown in double-quote marks in the output of this command. 25.8 Keystroke actions The command show keyactions causes NE to display a list of action abbreviations which can be bound to keystrokes by means of the KEY command. A short description is given with each one. -102- 25.9 Function keystrings The command show keystrings causes NE to display the definitions of all the function keystrings that are set. Function keystrings should not be confused with 'function-type' keystrokes - they are explained in detail in the chapter entitled Changing keystroke defaults. -103- 26. KEYBOARD INTERRUPTIONS Whether NE is being run on a workstation or in a time-sharing session on a larger computer, it can normally be interrupted from the keyboard during its operation. 26.1 Generating an interruption The precise keystrokes for generating an interruption vary from system to system, and there is usually a difference between screen and line-by-line editing in this respect. The logical keystroke name {INTERRUPT} is used as a general name for whatever is needed to generate an interruption. 26.2 The effect of an interruption If NE is running non-interactively, a keyboard interruption causes the NE run to be abandoned with an error return code. If NE is accepting screen-editing keystrokes the interruption has no effect. If NE is in the middle of reading a logical line of interac- tive commands which consists of several lines of input (using round brackets to indicate a continuation), a keyboard inter- ruption can be used to abandon the entire logical line, once the first actual line has been read. Before the first line is complete, the usual keystrokes for cancelling an input line can be used to abandon it. If NE is obeying a line of commands, it interrupts its processing at the end of the current command and outputs the message ** Keyboard interrupt It then waits for a new line of commands to be typed in. 26.3 Interruptable commands Normally, NE completes the current command before checking for a keyboard interruption. However, there are some commands which can be interrupted in the middle of their processing. They are f bf df ga gb ge i repeat t tl until while The looping commands stop as soon as one of the commands in the argument group is halted by an interruption. The others stop after a complete cycle of their action. For an interac- tive I command, a keyboard interruption is equivalent to a -104- terminator line. After an interrupted F, DF, or BF command, the current point in the file is unchanged. The behaviour of NE in regard to keyboard interruptions when it is running another program as a result of a command line beginning with * is system-dependent. However, it is normally the case that unless the called program deals with the interruption itself, it is aborted, and control returns to NE. 26.4 The ATTN command When setting up procedures or sequences of commands to be obeyed in an NE session it is sometimes desirable to inhibit the taking of interruptions throughout a particular group of commands. For example, if there is a command sequence which updates two files, it may not be desirable for it to be aborted when only one file has been updated. The NE command ATTN OFF suppresses NE's checks for keyboard interruptions until cancelled by the command ATTN ON. ('Attn' is an abbreviation for 'attention'.) If an interruption occurs in the disabled state it is not forgotten, and will be taken immediately the next ATTN ON command is obeyed. Thus, 'criti- cal sections' of NE commands should be bracketed with ATTN commands: attn off <update first file> <update second file> attn on However, to give a means of escape from erroneous command sequences, NE always notices a second interruption, even when ATTN OFF has been obeyed. -105- 27. LEAVING NE The STOP command causes an immediate abandonment of the NE session. No files are written, and the contents of all the editing buffers are lost. A return code indicating an error exit is passed back to the operating system. It is easy to forget that you are editing more than one thing at once, and using STOP to give up on one file can have the effect of losing data from another. For this reason, when STOP is obeyed interactively, a check is made to see if any buffers other than the current one have been modified but not saved. If one such buffer is found, a message of the form Buffer <n> (<title>) has been modified but not saved. is output, while if more than one is found, the message is Some buffers have been modified but not saved. This is followed by the prompt Continue with STOP command (Y/N)? This check is disabled if the WARN command has been used to disable warnings. In addition, there is a second command, ABANDON, which acts like STOP, but which bypasses the checks and never prompts. The W (windup) command is the normal way to terminate NE. (The {KEYSTRING-3} keystroke causes a W command to be obeyed.) It causes NE to scan through the editing buffers in turn, checking for any that are marked 'changed'. Each such buffer is a candidate for being written back to its associated file. However, if NE is running interactively, a prompt is output and the user is given an opportunity to prevent this writing back, or to specify an alternate file name. Before scanning the buffers, NE checks to see whether there is text in the cut buffer that has never been pasted. If such unpasted text is found, the message The contents of the cut buffer have not been pasted. is output, followed by up to three lines from the start of the cut buffer. If NE is running interactively, this is followed by the prompt Continue with W command (Y/N)? If the user's reply is Y or YES, the W command proceeds and the contents of the cut buffer are lost. If the reply is N or NO, the W command is abandoned, and NE issues a new command prompt. -106- When NE is running non-interactively, the warning message is output, but of course there is no opportunity of saving the contents of the cut buffer. The current buffer is considered first. If it has been changed (since the last SAVE command) and NE is running interactively, the prompt Write [buffer <n>] to <buffer title>? (Y/N/TO filename/Discard/STOP) is output, where <buffer title> is the title associated with the buffer (defaulting to the file name). The text 'buffer <n>' is omitted if only one buffer exists and its number is zero (the very simplest case). If there is no file name associated with the buffer, the prompt takes the form Write [buffer <n>]? (N/TO filename/Discard/STOP) The user must give one of the five possible replies, termin- ated by {ENTER}. If an empty or erroneous line is entered, an error message is output, and the prompt is repeated. If the reply is Y or YES then the contents of the buffer are written to the named file. This reply is only valid for the first form of the prompt. If the reply is N or NO, a mistake is assumed to have occurred. NE abandons the W command at this point, and issues a prompt for a new line of commands. A reply of the form TO <filename> is a request to write the contents of the buffer to an alternative file. NE attempts to open this file and write the contents of the buffer to it instead of to the file named in the prompt. If the file is successfully opened, it becomes the associated file for the buffer. This is only relevant, of course, if there is a subsequent error that prevents the W command from completing. If the reply is D or DISCARD then the contents of the buffer are not written, but no error occurs. NE proceeds normally to consider the next buffer, if any. If the reply is STOP NE does not write the current buffer. It abandons the W command, and obeys a STOP command instead (see the description of STOP above). The prompting sequence that has just been described can be suppressed by obeying the command PROMPT OFF while the buffer is current. In this case, provided there is a file name associated with the buffer, its contents are always written out without comment (assuming they have changed, of course). However, if the buffer has no file name, prompting always takes place. -107- If the current buffer is not marked 'changed', then one of the following messages is output, as appropriate: No changes made to <buffer title> No changes made to <buffer title> since last SAVE If the buffer has no title, then the text 'buffer <number>' is used instead. NE then considers all the other editing buffers, in turn. For any that are marked 'changed', the prompt Write buffer <n> to <buffer title>? (Y/N/TO filename/Discard/STOP) is output, and the responses are as described above. If there is no file name associated with the buffer, the prompt is changed in the same manner as for the current buffer. No output is produced for any buffers that are not marked 'changed'. If NE completes its scan of all the editing buffers without any error or negative responses to the prompts, it returns control to the operating system with a return code indicating a successful run. If there is an error while attempting to open or write to a file, or if the user replies NO to any prompt, NE does not exit, but prompts for a line of user commands. At this point, the buffer which was being considered at the time of the error has become the current buffer. Any NE commands can be entered; in particular, if the error was due to a mis-spelled file name, the W command can be retried. Prompting restarts with the new current buffer; any buffers that were successfully written out before the error are no longer marked 'changed' and so do not appear in this second prompt sequence. -108- 28. CHANGING DEFAULT OPERATIONS A number of commands are provided for changing the way in which NE performs certain operations. 28.1 The AUTOALIGN command The AUTOALIGN command is used to specify how split lines are to be aligned. autoalign on specifies that whenever a line is split (whether by means of the SA or SB commands, or by the {SPLIT-LINE} keystroke, or as a result of power typing), the newly created line must be aligned with the previous line. For example, if the line pack my box with five dozen liquor jugs is split after the word 'five', the result is pack my box with five dozen liquor jugs In the default state, which can be restored by the command autoalign off the result of such a splitting would be pack my box with five dozen liquor jugs AUTOALIGN may also appear without an argument, in which case NE switches to the opposite state to that which is current. When automatic alignment is enabled, the letter 'A' is added to the three mode letters that are displayed in the lower separator line on the screen. 28.2 The CASEMATCH command By default NE performs character comparison operations in a case-independent manner when matching a qualified string to a line. That is, upper-case (capital) letters are considered to be equal to their lower-case (small) equivalents. This action can be overridden by the use of the V (verbatim) qualifier on an individual qualified string, but it is also possible to change the default by means of the CASEMATCH command. casematch on specifies that the cases of letters must be identical for a match to take place, while -109- casematch off restores the initial situation. The current state of the case matching switch is displayed in the lower separator line on an NE screen, as one of the letters 'U' or 'V'. CASEMATCH without an argument switches to the other state from whatever state is current. When case matching has been selected, it is possible to overrule it for an individual qualified string by the use of the U (uncased) qualifier. The V or U qualifier can always be used to specify exactly what is wanted for a particular matching operation, overriding whichever default is selected by CASEMATCH. Neither the case matching default, nor the V or U qualifiers have any effect on characters that are specified in hexadeci- mal, whether by means of the X qualifier or by the use of $H in a regular expression. 28.3 The CUTSTYLE command When a portion of text or a rectangle is cut or copied to the cut buffer (see Cutting and pasting) it normally replaces any previous data in the buffer. Sometimes it is convenient to arrange for the new data to be added to the end of the cut buffer instead. This is specified by the command cutstyle append When this option is in effect, there is no warning when additional material is added to an unpasted cut buffer. The default action can be restored by the command cutstyle replace CUTSTYLE without an argument selects the opposite action from whatever is currently selected. The current state of this switch is displayed in the lower separator line on an NE screen, as one of the letters 'A' or 'R'. When new data is being appended, an explicit command, DCUT, must be obeyed in order to empty the cut buffer. This command can also be obeyed in the replacement state, though it is not normally necessary. If several rectangles are joined together by cutting them when in the appending state, they are placed one below the other, and the resulting rectangle has the width of the widest of its constituents. Its depth is the sum of the depths of the constituents. When text blocks and rectangles are joined together, the type of the result is the type of the last item cut or copied. If, for example, a rectangle is appended to a text block, any -110- subsequent paste operation pastes the data as though it were a rectangle. The width is the greater of the width of the rectangle and the longest line in the text. 28.4 The OVERSTRIKE command NE normally operates in 'insert mode' when screen editing is taking place. This means that any character typed by the user is inserted into the current line at the cursor position, and the remainder of the characters in the line are moved to the right by one position for each character so inserted. Occasionally it is useful to be able to operate in 'overstrike mode', where characters typed by the user replace whatever is already in the line at the cursor position. The OVERSTRIKE command is used to select this state; its argument can be one of the words ON or OFF, or it can be given without an argument, in which case it changes to the opposite state. The current state is displayed in the separator line at the bottom of the screen as one of the letters 'I' (for insert) or 'O' (for overstrike). The keystroke CTRL/O is by default set up to obey the OVERSTRIKE command, via function keystring 60, in most implementations of NE. Pressing this key has the effect of swapping between insert and overstrike modes. When operating in overstrike mode, all control keystrokes have their usual effects - {SPLIT-LINE} still splits the line, {DELETE-HERE} still closes up the line, and so on. 28.5 The PROMPT command The PROMPT command sets and resets a flag in the current buffer which causes the prompting that normally happens when a DBUFFER, LOAD, SAVE or W command is obeyed to be suppressed. It takes as its argument one of the words 'on' or 'off'. When prompting is switched off, the buffer is always written out as if an affirmative reply to the prompt had been given. In the case of the SAVE and W commands, if the current buffer does not have an associated file name then prompting is not suppressed, even if PROMPT OFF has been obeyed. This facility is useful when constructing command procedures which use NE as a data input mechanism. It is tedious for the user to have to reply to NE's request to write to some temporary file (used internally by the procedure, and there- fore not of significance to the user) as well as to the command procedure's own prompt. If there is any error while attempting to write the buffer to a file (non-existent file, overlong lines, etc.) then the -111- prompting flag is automatically turned on so that prompting will occur if an attempt is made to write the file again. 28.6 The READONLY command The READONLY command sets and resets a flag in the current buffer which prevents any updating of the buffer. It takes as its argument one of the words 'on' or 'off'; if called without an argument the state of the flag is inverted. Any new buffer that is created when a read-only buffer is current is also marked read-only. The -readonly command line option can be used to set the read-only flag for the first buffer. When NE is operating as a screen editor, the first status letter in the lower separator line is set to 'R' for read-only buffers (as opposed to 'I' for insert mode or 'O' for overstrike mode). 28.7 The SET command The SET command is used to change the values of parameters that control the way NE behaves. The following are available: SET AUTOVSCROLL <n> sets the number of lines of vertical scrolling that occur when the cursor hits the top or bottom of the screen. The default value is system-dependent, but is normally one. SET SPLITSCROLLROW <n> controls NE's behaviour when splitting lines on the screen. When a line is split as a result of user input, there is a choice between scrolling the upper part of the screen upwards, or the lower part downwards. By default, NE always scrolls downwards except when the cursor is within five lines of the bottom of the screen. The argument <n> is a number which specifies the number of lines from the bottom of the screen at which the change of scrolling is to take place. The default is equivalent to set splitscrollrow 5 The argument cannot be less than one, and it if is greater than the number of lines on the screen, the change takes place on the second row. SET OLDCOMMENTSTYLE causes NE to recognize a single backslash character as introducing comments in command lines, as did its prececessor, the E editor. SET NEWCOMMENTSTYLE restores the default, which requires two successive backslashes. Changing the style does not take effect until the following line of commands is read. -112- 28.8 The WARN command The WARN command disables and enables various NE warning messages. It can be followed by one of the words ON or OFF; if it appears with no argument it causes NE to change to the opposite state. By default, warnings are enabled. WARN OFF suppresses warnings that are otherwise given in the following circumstances: . When a CUT operation is attempted and there is unpasted material in the cut buffer. . When termination of NE is attempted and there is unpasted material in the cut buffer. . When a LOAD command is obeyed and the contents of the current buffer have been changed and not yet saved. . When a DBUFFER command is obeyed and the contents of the current buffer have been changed and not yet saved. With respect to buffers, WARN OFF acts as a global PROMPT OFF command. Wherever NE would have prompted for confirmation (e.g. before saving a file or before obeying STOP with some unsaved buffers), it behaves as if an affirmative response to the prompt has been given. 28.9 The WORD command The WORD command allows the user to change the definition of what constitutes a 'word', as used in qualified strings via the W qualifier and by the {WORD-LEFT} and {WORD-RIGHT} keystrokes. It takes a single string as an argument. The string contains those characters that are to be considered as forming 'words'. Ranges of letters or digits can be specified by using the hyphen character. If a hyphen itself is required in a word, then the character must be preceded by a double quote character in the string. This rule also applies to the double quote character itself. The default state is equival- ent to word /a-zA-Z0-9/ Note that it is necessary to specify upper and lower case letters explicitly. -113- 29. KEYSTROKE COMMANDS There are a number of commands which perform the same actions as the keystrokes that are available when screen editing. The commands are provided for use when editing non-interactively, or for building up complicated sequences in function keystrings or procedures. Full details of the actions of the associated keystrokes are given in chapter 4, and are not repeated here. 29.1 The MARK command The MARK command must be followed by one of the words LIMIT, LINE (or LINES), TEXT, RECTANGLE or UNSET. It has the effect of setting the appropriate mark (LIMIT sets the 'global mark') at the current position, or unsetting it if UNSET is given. However, if a mark of any sort is already set, an error occurs. After MARK LINE the word HOLD can appear. This sets the line mark in such a way that it is not automatically deleted after being used in a bulk line operation other than 'delete line'. It is equivalent to pressing {MARK-LINE} twice while screen editing. 29.2 The CSU and CSD commands These commands have the effect of moving the current point (cursor) up or down one line, respectively, without changing its horizontal position in the line. 29.3 The ALIGN command This command operates on the current line, and has exactly the same effect as the equivalent keystroke; it aligns the line so that the first printing character is at the position of the current point. If a line mark is set, the command operates on the sequence of lines delimited by the mark and the current line, inclusive. 29.4 The CLOSEBACK and CLOSEUP commands These commands operate on the current line, and have exactly the same effect as the equivalent keystrokes: . CLOSEBACK closes up the line by removing spaces immedi- ately prior to the current point. . CLOSEUP closes up the line by removing spaces at the current point. -114- If a line mark is set, these commands operate on the sequence of lines delimited by the mark and the current line, inclusive. 29.5 The DLEFT and DRIGHT commands These commands operate on the current line, and have exactly the same effect as the equivalent keystrokes: . DLEFT deletes all characters in the line to the left of the current point. . DRIGHT deletes the character at the current point and all those to the right of it in the current line. If a line mark is set, these commands operate on the sequence of lines delimited by the mark and the current line, inclusive. 29.6 The DLINE command This command deletes the current line, or a sequence of lines from the line mark to the current line. The current point is left at the start of the line following the last deleted line. In this respect it differs from the {DELETE-LINE} keystroke. 29.7 The CUT and COPY commands These commands perform the same operations as the equivalent keystrokes. 29.8 The PASTE command When given without an argument, this command performs the same operation as the {PASTE} keystroke, that is, the contents of the cut buffer are pasted into the current buffer at the cursor position. However, PASTE may optionally be followed by a buffer number, in which case the insertion of the data takes place in the buffer of that number instead of the current buffer. 29.9 The DMARKED command This command deletes the text or rectangle delimited by the text or rectangular block marker and the current point. -115- 29.10 The ISPACE command This command inserts a rectangle of spaces into the text. The rectangle is defined by the rectangular mark and the current point. -116- 30. CHANGING KEYSTROKE DEFAULTS The screen editing operations of NE have been described in terms of logical keystrokes such as {DELETE-PREVIOUS} and {SCROLL-BOTTOM}. The relationship between these keystrokes and actual keypresses is a two-stage one. The main part of NE, which is independent of any particular terminal or operating system, relates the logical keystrokes to idealized 'actual control keystrokes'. These are divided into three groups: (1) 'Control-type' keystrokes are those that are commonly produced with the aid of the CTRL key; there are 31 of these, named CONTROL-A to CONTROL-Z, CONTROL-[, CONTROL-\, CONTROL-], CONTROL-^, and CONTROL-_. (2) 'Function-type' keystrokes are those that are commonly produced with the aid of function keys. (3) The remaining 'actual control keystrokes' are produced by dedicated keys or are artifacts of the terminal handlers. (An example of the latter is a 'keystroke' that is manufactured if a character is typed at the right-hand margin.) The relationship between 'actual control keystrokes' and keypresses on the terminal's keyboard is a function of the particular terminal driver which is being used. The terminal- specific chapters of this document give details for the many different cases. The relationships between 'actual control keystrokes' and logical keystrokes are not all fixed within NE, and most of them can be changed by the user to taste. Two different kinds of action can be specified for an individual 'actual control keystroke'. . A single, primitive editing action, which is built into NE, may be performed. Examples are moving the cursor to the left of the screen, or deleting a line. This occurs when the 'actual control keystroke' is bound to a logical keystroke other than {KEYSTRING-1} - {KEYSTRING-60}. . An arbitrary line of NE commands may be obeyed. This is achieved by binding to one of {KEYSTRING-1} - {KEYSTRING-60}, and thereby associating the 'actual con- trol keystroke' with one of sixty function keystrings that are stored by NE. -117- 30.1 Function keystrings The contents of any of the function keystrings strings can be changed by the command fkeystring <n> <string> where <n> is a number between 1 and 60 inclusive. Because this command is frequently used in initialization sequences for NE, which are limited in length by some operating systems, the abbreviation FKS is provided. For example, to set up keystring 15 to create a new editing buffer, the command fkeystring 15 "newbuffer" could be used. If no text string is supplied, the keystring becomes unset. The default contents of the function keystrings are shown in the following table. Those that are not listed are empty. 1 "buffer" 16 "plr" 3 "w" 17 "bf" 4 "undelete" 18 "m0" 6 "pll" 19 "show fkeys" 7 "f" 20 "format" 8 "m*" 58 "topline" 9 "show keys" 59 "back" 10 "rmargin" 60 "overstrike" The command show keystrings can be used to display the contents of those function keystrings that are set. The line of commands for each keystring is displayed inside quotes. 30.2 Keystroke binding The KEY command is used to specify keystroke bindings, that is, to determine the relationship between 'actual control keystrokes' and logical control keystrokes. The command is followed by one or more definitions, separated by commas. Each definition consists of a key identification and a key definition, separated by an equals sign. The key identification is either (1) A number in the range 1-30, signifying one of the function-type keystrokes. (2) A single letter or one of the characters '^', '\', ']' or '_', signifying one of the control-type keystrokes. -118- (3) One of the following names, signifying the corresponding special keystroke: up up arrow key down down arrow key left left arrow key right right arrow key delete delete (or del) key del delete (or del) key backspace backspace key bsp backspace key return return key ret return key tab tab key insert insert key ins insert key home home key pageup page up key pup page up key pagedown page down key pdown page down key end end key copy copy key (4) One of the above names preceded by either or both of 's/' (signifying 'shift') or 'c/' (signifying 'ctrl'), for example s/up up arrow key with SHIFT s/c/ins insert key with SHIFT and CTRL Only a subset of the special key names is available in any given implementation of NE, depending on the terminal driver which is being used. In particular, some systems do not recognize the use of SHIFT and CTRL in conjunction with the arrow keys. These key names refer to keys that are available in addition to the keys on the keyboard used with CTRL. In some versions of NE, for example, RETURN cannot be distinguished from CTRL/M, and in these cases the key names 'ret' and 'return' are not available. Changing the meaning of the RETURN key, either as a synonym of CTRL/M or as a separate key, applies only while editing the main text window on the screen. When a line of NE commands is being entered, RETURN always terminates it, that is, it acts as the logical {ENTER} key. The second part of each definition, which defines which logical keystroke is to be bound, is either (1) A number in the range 1-60, signifying the corresponding {KEYSTRING-N} logical keystroke; or -119- (2) One of the following mnemonics, signifying the corre- sponding logical keystroke. mnemonic logical key action al {ALIGN-LINE} align with cursor alp {ALIGN-PREVIOUS} align with previous line cat {CONCATENATE} concatenate with previous line cl {CLOSE-UP} close up to the right clb {CLOSE-BACK} close up to the left co {CUT-COPY} copy to cut buffer csd {CURSOR-DOWN} cursor down csl {CURSOR-LEFT} cursor left csle {END-LINE} cursor to true line end csls {START-LINE} cursor to true line start csnl {NEWLINE} cursor to next line (start) csr {CURSOR-RIGHT} cursor right cssbr {BOTTOM-RIGHT} cursor to screen bottom right cssl {SCREEN-LEFT} cursor to screen left csstl {TOP-LEFT} cursor to screen top left csptb {PREVIOUS-TAB} cursor to previous tab stop cstb {NEXT-TAB} cursor to next tab stop cstl {FIRST-CHAR} cursor to text left on screen cstr {LAST-CHAR} cursor to text right on screen csu {CURSOR-UP} cursor up cswl {WORD-LEFT} cursor move left by a word cswr {WORD-RIGHT} cursor move right by a word cu {CUT-DELETE} cut to cut buffer dal {DELETE-LEFT} delete all chars to left dar {DELETE-RIGHT} delete all chars to right dc {DELETE-HERE} delete character de {DELETE-MARKED} delete marked text dl {DELETE-LINE} delete line dp {DELETE-PREVIOUS} delete previous character gm {MARK-GLOBAL} global mark lb {MARK-LINE} line(s) begin (mark lines) pa {PASTE} paste rb {MARK-RECTANGLE} rectangle begin rc {READ-COMMAND} read command line rf {REFRESH} refresh screen rs {RECTANGLE-SPACES} rectangle space insert sb {SCROLL-BOTTOM} scroll to bottom of file sd {SCROLL-DOWN} scroll down sl {SCROLL-LEFT} scroll left sp {SPLIT-LINE} split line sr {SCROLL-RIGHT} scroll right st {SCROLL-TOP} scroll to top of file su {SCROLL-UP} scroll up tb {MARK-TEXT} text begin (mark text) The CSWL and CSWR actions (move left or right by one word) make use of the user-settable definition of a 'word' [WORD]. The 'concatenate' action causes the current line to be joined on to the previous line, and places the cursor at the first character after the join. This action is not normally bound to -120- anything, since the same action is obtained by pressing {DELETE-PREVIOUS} when the cursor is at the start of a line. Some examples of changing keystroke functions are now given. The command key a=dl,c=dc,p=cssl sets up CONTROL-A as {DELETE-LINE}, CONTROL-C as {DELETE- HERE}, and CONTROL-P as {SCREEN-LEFT}. The previous actions of these keystrokes become unavailable. However, if any other keystroke was set up with one of these actions, it retains its setting. That is, it is possible to have the same action performed by more than one keystroke. The next example, key f=7,g=17 causes the keystrokes CONTROL-F and CONTROL-G to result in NE's obeying the function keystrings 7 and 17 respectively, so with the default setting for these, CONTROL-F would perform the 'find next' operation and CONTROL-G the 'find previous' operation. Some users prefer to use the RETURN key to move to the start of the next line instead of splitting the current line, and others are used to systems where the DELETE key deletes the character at the cursor, instead of the one before it. The next example shows how these requirements can be accomodated: key m=csnl,del=dc,h=dp,4=sp sets CONTROL-M (equivalent to RETURN on many terminals) to {NEWLINE}, the DELETE key to {DELETE-HERE}, CONTROL-H (BACKSPACE on many terminals) to {DELETE-PREVIOUS}, and func- tion key 4 to {SPLIT-LINE}. The current definitions of the control-type keystrokes, any 'extra' keystrokes, and the function-type keystrokes can be displayed by the commands show ckeys show xkeys show fkeys There is also a composite command show keys which is equivalent to obeying each of the previous three in turn. Primitive actions are displayed as short descriptive phrases, while lines of NE commands are displayed in double quotes. When a control-type key is bound to a function keystring, or when a function-type key is bound to a function keystring of a different number, the number of the keystring is shown in brackets before its contents. -121- 31. CALLING OTHER PROGRAMS When NE is running interactively, it is possible to call other programs without leaving NE. A command line beginning with an asterisk indicates that the remainder of the line is to be handed to a system-dependent routine for interpretation as an operating system command where possible. If screen editing is in progress, line-by-line mode is temporarily selected while the command is being obeyed, and the command line is reflected if necessary. When control returns to NE, the standard command prompt, 'NE>' is output if editing is interactive and automatic verification is not on. Otherwise the current line is verified in the normal way. Any line of NE commands, or a further system command line (beginning with an asterisk) may now be entered. An empty line causes NE to revert to normal running, and to re-display the screen if screen editing was in progress before the first system command line was entered. However, if NE is in the middle of obeying a command file as a result of obeying a C, CBUFFER, or CDBUFFER command when the system command is encountered, the prompt Press RETURN to continue is issued instead of a command prompt. Pressing RETURN causes execution of the command file to continue. When screen editing is in progress, a command line consisting of an asterisk only (that is, a null system command) has the effect of putting NE temporarily into line-by-line mode, whereupon it issues its standard 'NE>' prompt. In systems where a 'scrolling screen' is preserved over a screen-editing session, this is an easy way of referring back to the scrolling screen. Simply pressing RETURN returns NE to screen editing. -122- 32. ERROR HANDLING Most errors are detected while NE is interpreting or obeying a command. Typical examples are a mis-spelt command name or the failure to find a match for a search command. NE reads an entire command line and converts it into an internal format before obeying it. Therefore, if there is a syntax error in any command in the line, none of its commands are obeyed. When diagnosing a syntax error, NE indicates the point it has reached in scanning the line by printing a > character underneath the line of commands. If an error in a command line is detected during screen editing, the error message appears in the message area at the bottom of the screen, which expands to accommodate it, thus leaving the command line still visible. After outputting the message, NE displays its standard prompt for reading a new line of commands. This has the effect of keeping the message lines on the screen for the user to read. The user can either . Press {ENTER} (i.e. enter a null command line) to revert to screen editing; . Enter a new line of commands; . Press {CURSOR-UP} to recall the previous command line into the input area, edit it, and then press {ENTER} to obey the revised line. A few errors are so serious that NE cannot continue process- ing. These include a number of internal consistency failures and any kind of system-detected crash. In these circumstances, NE attempts to save the data from the editing session by writing the contents of all buffers that are marked 'changed' to an emergency file, whose name is system-dependent, but is normally NECRASH. The message ** Attempting to write data to <file name> is output, followed by one of the following messages for each buffer: ** <n> lines written from the cut buffer ** <n> lines written from buffer <n> (<buffer title>) ** No changes made to buffer <n> (<buffer title>) The contents of the cut buffer are written out only if it has not been pasted. The text 'from buffer <n>...' is omitted if there is only one buffer in existence, and the phrase 'since last SAVE' may be added to the last message if relevant. The data is written to the emergency file with no separators between the lines of the various buffers. -123- NE also writes error messages to a log file (usually called NECRASHLOG) when it crashes, to help in tracking down the cause of the crash. -124- 33. LINE-BY-LINE EDITING NE can be run as a line-by-line editor, both interactively and non-interactively. The majority of this document assumes that screen editing is used when NE is run interactively. However, interactive line-by-line editing is necessary if, for example, the terminal being used does not support full-screen handling. In this circumstance, NE should automatically start up in line-by-line mode. The arrangements for this are dependent on the operating system. 33.1 Interactive line-by-line editing To force NE to operate line-by-line, the option -line can be given on the NE command line. When operating interactively line-by-line, NE normally verifies the current line before reading the next line of commands, and does not output any prompt string. This makes it easy to use the single character commands, as each single character typed in the command line is exactly below the character of the current line which it will affect. More details are given in chapter 10 above. 33.2 Non-interactive line-by-line editing Non-interactive use of NE is always in line-by-line mode. In this case, verification of the current line before each line of commands is not the default. A non-interactive run is normally initiated by specifying a -with item on the NE command line, giving the name of a file of NE commands to be obeyed. For example, ne myfile -with myedits When there is no interactive input, the default right-hand margin is 79 - this affects the FORMAT command only. Reaching the end of the command file is equivalent to obeying a W command in NE. It causes any modified buffers to be output, and NE to exit normally. If any error occurs when NE is running non-interactively, an error message is output to the verification file and the run is abandoned with an error return code. 33.3 Verification output Verification output and error messages are normally sent to the terminal (even in non-interactive runs). A -ver keyword is available on the command line to direct this output elsewhere, for example, -125- ne myfile -with myedits -ver verification NE contains a switch which determines whether the current line is to be verified on the verification file before each new line of commands is read. The initial state of this switch is 'on' for interactive runs, and 'off' for non-interactive runs. It can be changed at any time by means of the VERIFY command, which is followed by one of the words 'on' or 'off'. If VERIFY is given without an argument, then the verification switch is changed to the opposite state from the one it is in. There is also a command to cause verification of the current line only. This is the single-character command consisting of a question mark. It may be used at any time, and is described in detail in chapter 10. 33.4 Format of verification output The format of the output produced by the ? command and by the automatic verification facility is described with the full description of ? (see chapter 10). When NE is running interac- tively and automatic verification is on, it does not output a command prompt in addition to the verification. This is to make it easy to make use of the single-character editing commands. 33.5 The T and TL commands Automatic verification and the ? command show only a single line at a time (the current line). The T and TL commands enable a number of lines to be output at once. Each takes a single number for an argument, or an asterisk character. If a number is given, it is the number of lines which are to be verified; an asterisk means 'type until the end of the file'. The output begins with the current line and continues for the number of lines specified, or until the end of file is reached. The T command simply outputs the data in each line, while the TL command outputs line numbers at the left-hand side as well. The data is output in the same format as is used for automatic verification and the ? command - a single line if there are no non-printing characters, two lines otherwise. The current point is not altered by the T and TL commands. After obeying one of them in an interactive line-by-line session with automatic verification on, the current line is verified before the next line of commands is read. These commands can occasionally be useful in screen mode, for showing lines containing non-printing characters. The message Press RETURN to continue -126- is output afterwards to enable the user to read what has been output before returning to screen editing. 33.6 The COMMENT command The COMMENT command takes a string as an argument, and its only effect is to output the string to the verification file. 33.7 The C command The C command takes a file name as an argument. The file is opened for input, and NE reads and obeys lines of commands from it until it is exhausted, or until an error occurs. C commands may be nested. If a file of NE commands is obeyed via a C command from an interactive run of NE, any global commands (GA, GB or GE) in it are obeyed in non-interactive fashion, that is, no prompt- ing takes place. However, if it contains any IF commands with the PROMPT option, prompting still takes place. If any command in a file obeyed via C generates verification output (for example, COMMENT, SHOW), and the C command was issued from a screen editing run of NE, then after such output has appeared in the message area at the bottom of the screen, NE pauses and outputs the message Press RETURN to continue Pressing {ENTER} causes NE to continue with the next command. At the end of the command file, verification output is lost as screen editing resumes. 33.8 The CBUFFER and CDBUFFER commands These two commands take a buffer number as an argument, and they cause NE to obey the contents of the buffer as a command file. CBUFFER leaves the buffer intact, marking it 'not changed', so that it can subsequently be overwritten without complaint, while CDBUFFER deletes the buffer after the com- mands have been obeyed. See the MAKEBUFFER and PASTE commands for details of how to create a buffer with a given number and paste material into it. -127- 34. UNIX INTERFACE Versions of NE are currently available for the following versions of Unix: . SunOS 4.x (Solaris 1) . SunOS 5.x (Solaris 2) . DEC's OSF1 . Silicon Graphics' IRIX 5 . Hewlett-Packard's HP-UX . Linux They require terminals with sufficient functionality for screen editing to be defined via the terminfo or termcap mechanism (which of these is used is a compile-time option). Other versions of Unix are likely to be supported in due course. When NE is run in a windowing system under a version of Unix which supports the SIGWINCH signal (most modern systems do) it notices immediately if the size of its window is altered, and adjusts its display accordingly. 34.1 Using NE as a filter NE can be run as a filter under Unix by specifying the input file as '-' (a single minus sign). The text to be edited is then read from the standard input and written by default to the standard output. The default command input is switched to the null file, and the default verification output to the standard error, but these can be changed by means of the -with and -ver keywords if necessary. Commands may also be specified using the -opt keyword, of course, as in this example: ls | ne - -opt "rmargin 40; format" | more The -to keyword can be used to direct the output to a different destination when the input is being read from the standard input, and, conversely, a minus sign can be used with -to to direct output to the standard output when input is not from the standard input. 34.2 Environment variables When NE starts up, it searches its environment for a variable with the name NEINIT (in capital letters), unless the command argument -noinit is present. The contents of the variable are -128- taken to be a string of NE commands which are obeyed before the -opt string. For a compatibility with the previous E editor, if NEINIT does not exist, NE looks for the variable EINIT. However, this feature will be removed in some future version. The environment variable TERM is used in determining the terminal type. Details are given in the section on terminal types below. The environment variable NETABS can be used to set up default tab handling options, as described in section 5.1 above. The environment variable HOME is used in the interpretation of file names, as described below. 34.3 Exit codes The following exit codes are used by NE: 0 normal exit 4 warning 8 errors detected, or STOP obeyed 12 NE ran out of memory 16 an internal error was detected 24 NE crashed The only warning that is applicable to Unix occurs when a non- interactive run of NE terminates with an unpasted cut buffer in existence. When NE is run interactively, exit code 8 is generated only as a result of the STOP command, and exit code 4 is never given. 34.4 File names File names in NE commands may be specified using the normal Unix syntax. Delimiters are needed only if a file name contains a semicolon or begins with two backslashes. Unix allows almost any character to be included in a file name, so it is not possible to choose delimiters that cannot be part of a file name for this implementation. For uniformity with shell usage, only the two quoting characters, single quote and double quote, have therefore been installed as file name delimiters. If a file name begins with a tilde character, it is interpreted in the same way as the shell would interpret it: . If the name is of the form ~/<path> then the contents of the environment variable HOME are used in place of the tilde. -129- . If the name is of the form ~<user>/<path> then the entry in the password file for the given user is looked up, and the contents of its home directory field replaces ~<user> in the file name. 34.5 Emergency files The name of the emergency file is NEcrash, and the crash log is NEcrashlog. 34.6 File backup If the BACKUP FILES option is on, then an existing file that is about to be overwritten for the first time in an editing session is renamed by adding a tilde character onto the end of its name. 34.7 Shell commands The NE '*' mechanism can be used to cause shell commands to be executed from within NE. It is a Unix convention that an empty shell escape starts a new interactive shell. However, it is an NE convention that an empty '*' command puts NE temporarily into line mode. This is particularly useful on terminals that re-display the scrolling screen when returning to line mode. Since the users of NE on Unix are expected to be people who also use it on other systems, the NE rather than the Unix convention has been adopted. Therefore a command line such as */bin/bash is necessary in order to create a new interactive shell. 34.8 Interruptions In line editing mode, special keystrokes such as the inter- rupt, suspend and quit characters are handled by Unix, so they have their normal effects. In screen editing mode, NE traps the interrupt signal gener- ated by the user's interrupt character (typically CTRL/C) while obeying NE commands, so this keystroke can be used to interrupt loops or long searches, etc. It also terminates an interactive I (insert) command. During screen editing itself, the keystroke is available as a normal editing keystroke, except when entering lines of com- mands following {READ-COMMAND}, when it can be used to abandon command entry (useful for multi-line commands). This means that, if NE's keystrokes are reconfigured so that the inter- rupt character is bound to one of the editing functions that -130- is recognized during command entry (e.g. {DELETE-HERE}) then this function is not available during command entry. The default assignment, to {CLOSE-UP}, is not used during command entry. If NE is interrupted in a loop producing output, quite a lot of output can be buffered up and this is not thrown away on receipt of an interruption, so it sometimes takes a while before NE appears to notice an interruption. 34.9 Terminal types NE supports terminals described in the Unix terminfo or termcap databases. Which one of these is used is controlled by a compile-time parameter. If the -line keyword is not present on the NE command line, and neither -with nor -ver is present, NE attempts to start up in screen editing mode. To do this it needs to know what kind of terminal is being used. . NE interrogates the Unix terminfo or termcap database to find out the characteristics of the terminal described by the string in the environment variable TERM. If the terminal is capable of sustaining a screen editing session, NE initializes its terminfo/termcap driver. . Otherwise a message is output, and NE enters line editing mode. The configuration required for the terminal or terminal emu- lator may depend on the communications route being used. 34.10 Terminal capabilities The following minimum capabilities are required of a terminal in order to support screen editing using NE. These are listed with both their termcap and terminfo names. cm cup move to (x,y) on screen kd kcud1 cursor down kl kcub1 cursor left kr kcuf1 cursor right ku kcuu1 cursor up If the 'cm' or 'cup' string contains '%.' it means that binary values are used for cursor positioning. It is not desirable to generate zero in these circumstances, since it is likely to get swallowed en route to the terminal. NE avoids generating binary zeroes by requiring the availability of the 'up' or 'cuu1' control string (cursor up) and either a backspace or the 'bc' or 'cub1' string in this case. The following optional capabilities are used if present: -131- al il1 add (i.e. insert) line ce ed clear to end of line cl clear clear screen cs csr set up scrolling region dc dch1 delete character - but not if in 'delete mode' dl dl1 delete line F1-F9 kf11-kf19 function keys 11-19 FA-FK kf20-kf30 function keys 20-30 ic ich1 insert character - but not if in 'insert mode' k0-k9 kf0-kf9 function keys 0-9 k; kf10 function key 10 ke rmkx end 'keypad' mode ks smkx start 'keypad' mode se rmso end standout mode sf ind scroll text up so smso begin standout mode sr ri scroll text down te rmcup end use of screen management ti smcup initiate use of screen management As well as using the generalised terminal information in terminfo or termcap, NE contains built-in code to make use of the special capabilities of certain terminals which cannot be described by the terminfo/termcap mechanism. Descriptions of these features are given separately below for each relevant terminal. The terminals are: . An xterm session running under the X windowing system. . The Fawn II terminal emulator running on a Macintosh. . The Computing Service's TTP or !Hydra terminal emulators running under Acorn's RISC OS operating system. The terminfo/termcap driver for NE is designed to be usable with a minimal terminal containing only the standard ASCII keys and four arrow keys. The default control keystrokes are set up as shown in the following table. CTRL/A {ALIGN-LINE} CTRL/B {MARK-LINE} CTRL/C {CLOSE-UP} CTRL/D {REFRESH} CTRL/E {CUT-COPY} CTRL/F <unset> CTRL/G {READ-COMMAND} CTRL/H {SCROLL-LEFT} CTRL/I {NEXT-TAB} CTRL/J {SCROLL-DOWN} CTRL/K {SCROLL-UP} CTRL/L {SCROLL-RIGHT} CTRL/M {SPLIT-LINE} CTRL/N {MARK-GLOBAL} CTRL/O {KEYSTRING-60} i.e. "overstrike" CTRL/P {PASTE} CTRL/Q {DELETE-MARKED} (but see below) -132- CTRL/R {MARK-RECTANGLE} CTRL/S {RECTANGLE-SPACES} (but see below) CTRL/T {MARK-TEXT} CTRL/U {DELETE-LINE} CTRL/V {DELETE-RIGHT} CTRL/W {CUT-DELETE} CTRL/X {DELETE-LEFT} CTRL/Y {DELETE-HERE} CTRL/Z {ALIGN-PREVIOUS} CTRL/[ <escape> CTRL/\ {SCREEN-LEFT} CTRL/] unset CTRL/^ {KEYSTRING-58} i.e. "top" CTRL/_ {KEYSTRING-59} i.e. "back" On some communications routes CTRL/S and CTRL/Q are used for flow control and so cannot be passed through to NE. A fudge using ESC is implemented to get round this - see below. The RETURN key is synonymous with CTRL/M. DELETE provides the {DELETE-PREVIOUS} function and the {CONCATENATE} function when used at the start of a line. The cursor keys are used to move around the screen. If the terminal has function keys described by terminfo/termcap, then these are used by NE, with F0 corre- sponding to NE's {KEYSTRING-10}. Not all terminals have func- tion keys, and so this facility, together with all other keyboard functions required by NE is also implemented using a keystroke sequence beginning with ESC. Many terminals use character sequences starting with ESC for their special keys, so there is in principle some danger that these may clash with NE's usage. It is hoped that the danger has been minimised in the following choices. When NE receives a sequence of characters starting with ESC it first searches the list of terminal-specific strings for the functions in which it is interested. Only if the sequence is not in this list does it test for its own built-in interpretations: <ESC>1-<ESC>9 functions 1-9 <ESC>0 function 10 <ESC><ESC>1-<ESC><ESC>9 functions 11-19 <ESC><ESC>0 function 20 <ESC>DELETE ignored (a way to cancel ESC) <ESC>RETURN repaint the screen <ESC>TAB {PREVIOUS-TAB} <ESC><ESC><ch> enter control char as data <ESC>S simulate CTRL/S <ESC>Q simulate CTRL/Q If a sequence of two escapes is followed by DEL or a character whose code value is less than 32, then that character is interpreted as a data character. Otherwise, unless the charac- ter is a digit, the two bits with values 32 and 64 are forced -133- to zero, and the resulting character is handled as a data character. Thus, for example, the data character with binary value one can be inserted into a file by typing ESC twice followed by 'A' or 'a'. The default assignments to NE's logical keystrokes are shown in the following table. Not all the keystrokes are available on every terminal, and not all of them are definable via the termcap or terminfo mechanisms. {ALIGN-LINE} CTRL/A {ALIGN-PREVIOUS} CTRL/Z {BOTTOM-RIGHT} <unset> {CLOSE-BACK} SHIFT/DELETE and SHIFT/BACKSPACE {CLOSE-UP} CTRL/C {CONCATENATE} DELETE at start of line {CURSOR-DOWN} DOWN-ARROW {CURSOR-LEFT} LEFT-ARROW {CURSOR-RIGHT} RIGHT-ARROW {CURSOR-UP} UP-ARROW {CUT-COPY} CTRL/E {CUT-DELETE} CTRL/W {DELETE-HERE} CTRL/Y {DELETE-LEFT} CTRL/X, CTRL/DEL, and CTRL/BACKSPACE {DELETE-LINE} CTRL/U {DELETE-MARKED} <ESC>Q or CTRL/Q if not flow control {DELETE-PREVIOUS} DELETE and BACKSPACE {DELETE-RIGHT} CTRL/V {END-LINE} SHIFT/CTRL/RIGHT {ENTER} RETURN {FIRST-CHAR} CTRL/LEFT {INTERRUPT} CTRL/C when obeying commands {KEYSTRING-N} <ESC>1 - <ESC>0 for 1-10 <ESC><ESC>1 - <ESC><ESC>0 {LAST-CHAR} CTRL/RIGHT {MARK-GLOBAL} CTRL/N {MARK-LINE} CTRL/B {MARK-RECTANGLE} CTRL/R {MARK-TEXT} CTRL/T {NEWLINE} <unset> {NEXT-TAB} TAB {PASTE} CTRL/P {PREVIOUS-TAB} <ESC>TAB and CTRL/TAB {READ-COMMAND} CTRL/G {RECTANGLE-SPACES} <ESC>S or CTRL/S if not flow control {REFRESH} CTRL/D {SCREEN-LEFT} CTRL/\ {SCROLL-BOTTOM} CTRL/DOWN {SCROLL-DOWN} CTRL/J and SHIFT/DOWN {SCROLL-LEFT} CTRL/H and SHIFT/LEFT {SCROLL-RIGHT} CTRL/L and SHIFT/RIGHT {SCROLL-TOP} CTRL/UP {SCROLL-UP} CTRL/K and SHIFT/UP {SPLIT-LINE} RETURN {START-LINE} SHIFT/CTRL/LEFT -134- {TOP-LEFT} <unset> {WORD-LEFT} <unset> {WORD-RIGHT} <unset> 34.11 Keyboard interruptions While screen editing is occurring, most keystrokes are taken over by NE and used for controlling the editing process, as described above. The only exceptions are any flow control characters that may be in use (typically CTRL/S and CTRL/Q). However, while NE is obeying a line of commands entered from screen mode, the interrupt keystroke (typically CTRL/C) changes its meaning, and if pressed causes an interrupt to be sent to NE. It can thus be used to interrupt a command loop or a long search command. The many other special keystrokes (kill, literal-next, etc.) are never available during screen editing, the relevant keystrokes retaining their NE meaning. If these facilities are wanted they can be accessed by leaving screen mode, by obeying a command line containing only an asterisk. In the line editing state NE runs with 'cooked' terminal input and so all the special keystrokes are available. 34.12 xterm NE has some built-in knowledge of the xterm terminal emulator which is part of the X windowing system. When the value of the TERM variable is 'xterm', the internal tables in NE give access to the following additional keystrokes over and above those defined by termcap or terminfo: SHIFT/LEFT {SCROLL-LEFT} SHIFT/RIGHT {SCROLL-RIGHT} SHIFT/UP {SCROLL-UP} SHIFT/DOWN {SCROWN-DOWN} In addition, the following are also available if the terminal emulator is configured appropriately: SHIFT/DELETE {CLOSE-BACK} CTRL/DELETE {DELETE-LEFT} CTRL/LEFT {FIRST-CHAR} CTRL/RIGHT {LAST-CHAR} CTRL/UP {SCROLL-TOP} CTRL/DOWN {SCROLL-BOTTOM} CTRL/TAB {PREVIOUS-TAB} The BACKSPACE key is distinguishable from CTRL/H, and it is initially defined to have the same effect as the DELETE key. The function keys correspond to NE's function keystrokes, and SHIFT may be used with any of them to add 10 to its value. -135- 34.13 Fawn II NE has some built-in knowledge of the Fawn II terminal emulator which runs on Macintosh computers. When the value of the TERM variable is 'fawn', the internal tables in NE give access to the following additional keystrokes over and above those defined by termcap or terminfo: SHIFT/LEFT {SCROLL-LEFT} SHIFT/RIGHT {SCROLL-RIGHT} SHIFT/UP {SCROLL-UP} SHIFT/DOWN {SCROWN-DOWN} However, these keystrokes cannot actually be generated by holding down the shift key and pressing the arrows. Instead, the key which corresponds to PF1 on a VT100 terminal must be pressed, followed by the arrow key. (This key is often labelled NUM LOCK.) The keypad keys 1-9 are used for function keys 1-9, with keypad key zero corresponding to function key 10. Preceding these keys with PF1 adds 10 to the function number. 34.14 TTP and Hydra NE has some built-in knowledge of the TTP and Hydra terminal emulators for Acorn computers running RISC OS. The appropriate value to set in the TERM environment variable is 'ttpa' for the former and 'arc-hydra' for the latter. When a Telnet connection is used, these values are set automatically. The internal tables in NE give access to the following additional keystrokes over and above those defined by termcap or terminfo: COPY {DELETE-HERE} SHIFT/COPY {CLOSE-UP} CTRL/COPY {DELETE-RIGHT} SHIFT/DELETE {CLOSE-BACK} CTRL/DELETE {DELETE-LEFT} SHIFT/LEFT {SCROLL-LEFT} SHIFT/RIGHT {SCROLL-RIGHT} SHIFT/UP {SCROLL-UP} SHIFT/DOWN {SCROWN-DOWN} CTRL/LEFT {FIRST-CHAR} CTRL/RIGHT {LAST-CHAR} CTRL/UP {SCROLL-TOP} CTRL/DOWN {SCROLL-BOTTOM} In addition, the BACKSPACE key is distinguishable from CTRL/H, and it is initially defined to have the same effect as the DELETE key. The function keys correspond to NE's function keystrokes, and SHIFT may be used with any of them to add 10 to its value. -136- 35. RISC OS INTERFACE This chapter contains information that is specific to the implementation of NE running under Acorn's RISC OS operating system. NE requires RISC OS 3 or later when it is run as a desktop application. NE can be run either as a RISC OS desktop application, or from the command line or a script. In the latter case it can be interactive or non-interactive, or operate as a screen editor or a line-by-line editor. NE is packaged as a traditional desktop application, in a directory called !NE. When this directory is first 'seen' by the filer, it sets up a command alias NE which can then be used to run NE as a non-desktop command. When run that way, NE operates very much as it does in other non-desktop environ- ments, for example, under Unix. 35.1 NE on the desktop When run as a desktop application, NE installs itself on the icon bar in the normal way, and arranges that any operations that require a text editor (such as double-clicking on a text file) make use of it. Each NE buffer is displayed in a separate desktop window that can be scrolled and sized in the normal way. No 'End of file' line is displayed. The window's title bar contains the NE status flags, the title of the file, and an asterisk if the buffer has been modified since it was last saved. If a mark is set, a b, g, t, or r is displayed before the file name. The b becomes B if the 'bulk line' mark is 'held' by pressing it twice. If the margin is enabled, m is added to the end of the flags. There are no line or column indicators on NE data windows. However, a separate small window that displays the line number of the current line and the cursor's column number is dis- played if the 'Line info' option on the iconbar menu is ticked. This can also be turned on and off via the keystroke SHIFT/CTRL/F9. The line numbers shown in this window are the original line numbers of the file; inserted lines have no numbers, and four asterisks are displayed when an inserted line is current [RENUMBER]. The small window can be positioned anywhere convenient on the desktop; NE ensures that it is usually at the front of the window stack. There is at present no way to change the colours used in the windows. The cursor is shown as an orange rectangle. When a mark is set, the cursor rectangle changes to red until the cursor moves to a different position, whereupon the position of the mark is indicated by a blue background, and the cursor position by the normal orange. -137- This implementation is very much 'NE running in a window' rather than an editor designed for the desktop. Therefore, apart from using the mouse pointer to set the cursor position, the scrolling controls, and a menu that allows the usual dragging method of saving, NE is controlled entirely by keystrokes as it is in its other implementations. The {READ-COMMAND} keystroke causes a separate command line input window to appear. Other input is requested in a similar way, with the NE prompting text in the window's title bar. The BUFFER command (by default on function key 1) swaps between different windows and brings the current buffer's window to the front of the desktop. Error messages from NE are displayed in a separate text window. The shortcut keystroke SHIFT/CTRL/F10 can be used to close this window. The STOP and W commands do not cause the application to quit. They deal with all the buffers in the normal way, then place NE into a 'quiescent' state, as it is when first loaded. The only way to quit the application is via the 'quit' item on the iconbar menu. The quiescent state is also entered when the last display window is closed. In this state, the cut buffer is emptied, and any remembered information, such as the last search expression, is lost. The memory used is reduced to its initial amount. NE does not reduce its memory usage while any windows are open. It is useful to have available keystrokes that save the current buffer and either do or do not close the window. If the following commands are included in the NEINIT variable, then {FUNCTION-13} (i.e. SHIFT/F3) saves and closes, while {FUNCTION-23} (i.e. CTRL/F3) saves without closing: fks 13 /prompt off;save;dbuffer/; fks 23 /prompt off;save;prompt on/;key 23=23" Command-line arguments cannot be used when running NE in the desktop, and in particular, it cannot be run in binary mode. 35.2 Taskwindows NE is capable of handling taskwindows when running in the desktop. There are two aspects to this: (1) If NE is already running, it will catch taskwindow output and display it in a window. If this is not required, the following line in its !BOOT file should be uncommented (i.e. the vertical bar at its start should be removed): | If "<alias$ne>" = "" then Set NE$TaskWindow no -138- (2) If no taskwindow handler is running when a taskwindow is required, NE will normally be started up. If this is not required, the following line in the !BOOT file should be commented out (i.e. insert a vertical bar at its start): If "<alias$ne>" = "" then Set Taskwindow$server "<Obey$Dir>.^.!NE " This should always be done if the former line is uncommented. When the taskwindow support in NE is enabled, a new, interac- tive taskwindow can be obtained by clicking on the 'Task' option in the iconbar menu. The menu displayed in a taskwindow has the additional item 'kill task' while the task is running. When the task ends, the text ---- End ---- is written to the task window, and thereafter it behaves as a normal NE window. A taskwindow cannot be closed while the task is still running; NE prompts the user and asks if the task should be killed. If an attempt at killing the task fails, at the next attempt to close the window the user is asked whether it should be closed regardless. 35.3 File types NE sets the type of output files to FFF (text) unless there is an input file associated with the buffer that is being written, in which case the file type is copied. 35.4 Initialization If the operating system variable NE$INIT exists, its contents are used as a line of commands which is obeyed before the -opt text when NE is run as a command. Note that the string of commands may contain a C command which reads further NE commands from a file. In the desktop style of working, the initializing commands are obeyed whenever there are no current buffers and a new buffer is created. When all NE windows are closed (i.e. all buffers are deleted) NE enters a 'quiescent' state which approximates to the state immediately after loading. NE$INIT can be used to configure NE as required. For example, the RISC OS command set NE$Init "rmargin" -139- ensures that NE is always entered with its right margin turned off. Such a command is normally placed in a suitable bootstrap file (the system !BOOT or NE's !BOOT). 35.5 Screen modes NE runs successfully in all RISC OS screen modes, though some of its informational output is wider than 40 characters. 35.6 File names A file name used in an NE command is given in the usual RISC OS format, for example name newfile name $.xyz.pqr.abc Delimiters are only required in the rare case of a filename which starts with two backslashes (NE's comment sequence), because semicolon is not used in RISC OS file names. The following delimiters are available: , " ' + * Spaces and non-printing characters are forbidden by NE to appear in file names; otherwise file names are checked for legality by calling the system to check for the existence of the file. 35.7 Emergency files The name of the emergency file is NEcrash, and the crash log is NEcrashlog. 35.8 File backup If the BACKUP FILES option is on, then an existing file that is about to be overwritten for the first time in an editing session is renamed by adding a tilde character onto the end of its name, provided the final component of the name is less than 10 characters long. Otherwise the final character is changed to a tilde. 35.9 Return codes The following return codes are given by NE: -140- 0 no errors 4 warning(s) only 8 error(s) detected 12 insufficient memory 16 disaster 24 NE crashed When running interactively, return code 8 is given only as a result of obeying the STOP or ABANDON command; errors that do not cause NE to stop do not set a return code in an interactive editing session. 35.10 Interruptions The key marked ESC can be use to interrupt NE's processing when it is obeying commands. 35.11 Non-printing characters Characters whose ASCII codes are less than 32 are displayed in desktop windows as question marks. Codes greater than 127 are not treated specially. When NE is run from the command line, character codes in the range 0-31 are displayed as small mnemonics, code 127 is displayed as a solid blob, and the remaining non-printing characters are shown as the mnemonic 'SB' (for the 'substitute' character). Non-printing ASCII characters in the range 0-31 may be input as data by pressing the appropriate CTRL keystroke after SHIFT/CTRL/COPY. Similarly, character 127 (<DEL>) may be input in the same way. In addition, any character can be input by number after SHIFT/CTRL/COPY by holding down the ALT key and then typing the decimal character number on the numeric keypad (this use of the keypad is a standard RISC OS facility). 35.12 Keystrokes For function keys, the F keys are used, either on their own for functions 1-12, with the SHIFT key for functions 11-20, or with the CTRL key for functions 21-30. The ESC key cannot be used as an alternative to the function keys. In addition to the standard CTRL keystrokes and the function keys, the following keystrokes can be configured using NE's KEY command: COPY S/COPY C/COPY INSERT S/INSERT C/INSERT S/C/INSERT TAB S/TAB C/TAB S/C/TAB <arrow> S/<ARROW> C/<ARROW> S/C/<ARROW> DELETE S/DELETE C/DELETE S/C/DELETE BACKSPACE S/BACKSPACE C/BACKSPACE S/C/BACKSPACE -141- where <arrow> is any of the four arrow keys. The standard assignments to NE's logical keystrokes are shown in the following table: {ALIGN-LINE} CTRL/A {ALIGN-PREVIOUS} CTRL/Z {BOTTOM-RIGHT} <unset> {CLOSE-BACK} SHIFT/DELETE and SHIFT/BACKSPACE {CLOSE-UP} CTRL/C {CONCATENATE} DELETE at start of line {CURSOR-DOWN} DOWN-ARROW {CURSOR-LEFT} LEFT-ARROW {CURSOR-RIGHT} RIGHT-ARROW {CURSOR-UP} UP-ARROW {CUT-COPY} CTRL/E {CUT-DELETE} CTRL/W {DELETE-HERE} COPY or CTRL/Y {DELETE-LEFT} CTRL/X or CTRL/DELETE {DELETE-LINE} CTRL/U {DELETE-MARKED} CTRL/Q {DELETE-PREVIOUS} DELETE {DELETE-RIGHT} CTRL/V or CTRL/COPY {END-LINE} SHIFT/CTRL/RIGHT {ENTER} RETURN {FIRST-CHAR} CTRL/LEFT-ARROW {INTERRUPT} ESCAPE {KEYSTRING-N} F1 - F12 and SHIFT/F1 - SHIFT/F10 {LAST-CHAR} CTRL/RIGHT-ARROW {MARK-GLOBAL} CTRL/N {MARK-LINE} CTRL/B {MARK-RECTANGLE} CTRL/R {MARK-TEXT} CTRL/T {NEWLINE} <unset> {NEXT-TAB} TAB {PASTE} CTRL/P {PREVIOUS-TAB} CTRL/TAB {READ-COMMAND} CTRL/G {RECTANGLE-SPACES} CTRL/S {SCREEN-LEFT} CTRL/\ {SCROLL-BOTTOM} CTRL/DOWN-ARROW {SCROLL-DOWN} SHIFT/DOWN-ARROW {SCROLL-LEFT} SHIFT/LEFT-ARROW {SCROLL-RIGHT} SHIFT/RIGHT-ARROW {SCROLL-TOP} CTRL/UP-ARROW {SCROLL-UP} SHIFT/UP-ARROW {SPLIT-LINE} RETURN {START-LINE} SHIFT/CTRL/LEFT {TOP-RIGHT} <unset> {WORD-LEFT} <unset> {WORD-RIGHT} <unset> -142- 35.13 Calling other programs When NE is running in the desktop, calling external commands from within it is not permitted. When running from the system command line or a script, there are no restrictions imposed by NE on which programs may be run from within it by using a command line beginning with an asterisk. However, because of the way in which memory is handled in RISC OS, other 'applications' (such as compilers) should not be run. In particular, NE cannot be run recursively. -143- 36. MS-DOS INTERFACE MS-DOS is an operating system for IBM personal computers and compatibles. 36.1 File handling The largest file that can be handled in the MS-DOS version of NE is one of 32767 lines, even in stream mode. 36.2 Emergency files The name of the emergency file is NEcrash, and the crash log is NEcrash.log. 36.3 File backup If the BACKUP FILES option is on, then an existing file that is about to be overwritten for the first time in an editing session is renamed by changing its extension to .BAK. 36.4 Automatic initialization The environment variable NEINIT can be set to a string of NE commands which are obeyed at startup. If the string contains characters significant to the MS-DOS command decoder, it must be enclosed in double-quote characters. Note in particular that vertical bar and the two angle brackets are such charac- ters. Thus, for example, one might include the command set neinit="beginpar(nps//&nb/./); endpar(b/./|b/ /|p//)" in an AUTOEXEC.BAT file to make it possible to format para- graphs in SGCAL source files correctly. Note that the string of commands may contain a C command which reads further NE commands from a file. 36.5 Screen display NE does not alter the screen mode. It supports any (small) number of screen lines and columns. Characters outside the normal ASCII printing range are shown where possible using the standard PC characters - the exceptions are NUL, BEL, LF, and CR. These are represented by code 254, a small square. -144- 36.6 Screen colours The environment variable NECOL can be set to specify which colours are used in the screen display. It contains a list of four colour names, separated by spaces, specifying the normal foreground, normal background, highlighted foreground, and highlighted background colours, respectively. The available colour names are: black blue green cyan red magenta brown white grey (or gray) light_blue light_green light_cyan light_red pink yellow light_white For example: SET NECOL=YELLOW BLACK RED WHITE Only the first eight colours apply to the background. The default is to pick up the currently active foreground and background colours, and swap them for highlighting. 36.7 Keystrokes Most of the keystrokes follow the standard NE conventions. Keystrokes that are not recognized are ignored. The keystroke CTRL/BACKSLASH does not work on most UK keyboards. You have to use CTRL/GRAVE-ACCENT instead. Arrow keys on the keypad cannot be used with SHIFT as this produces digits, etc., but can be used in the standard way with CTRL. CTRL/ARROW and SHIFT/ARROW with the editing keys (inverted T) all work standardly. The big key with the left arrow at the top right of the main keyboard (called 'backspace') is used for the {DELETE- PREVIOUS} function, as is conventional in MS-DOS. This keystroke is distinguished from CTRL/H, leaving the latter available for use in the normal NE fashion. The key marked 'Delete' is used for the {DELETE-HERE} func- tion, as is done in other MS-DOS editors. 'Function' keystrokes are obtained by use of the dedicated function keys: F1 - F10 give NE function keystrokes 1-10 SHIFT/F1 - SHIFT/F10 give NE function keystrokes 11-20 CTRL/F1 - CTRL/F10 give NE function keystrokes 21-30 ESC followed by any keystoke inserts the second keystroke's value into the file as data. This applies to all character codes. PAGE UP and PAGE DOWN provide the NE vertical scrolling functions {SCROLL-UP} and {SCROLL-DOWN}, which are also avail- able as CTRL/K and CTRL/J. Horizontal scrolling functions are by default allocated to CTRL/H and CTRL/L. -145- SHIFT/TAB provides the backwards tab function, {PREVIOUS-TAB}. The default assignments to NE's logical keystrokes are shown in the following table: {ALIGN-LINE} CTRL/A {ALIGN-PREVIOUS} CTRL/Z {BOTTOM-RIGHT} <unset> {CLOSE-BACK} <unset> {CLOSE-UP} CTRL/C {CONCATENATE} BACKSPACE at start of line {CURSOR-DOWN} DOWN-ARROW {CURSOR-LEFT} LEFT-ARROW {CURSOR-RIGHT} RIGHT-ARROW {CURSOR-UP} UP-ARROW {CUT-COPY} CTRL/E {CUT-DELETE} CTRL/W {DELETE-HERE} CTRL/Y {DELETE-LEFT} CTRL/X {DELETE-LINE} CTRL/U {DELETE-MARKED} CTRL/Q {DELETE-PREVIOUS} BACKSPACE {DELETE-RIGHT} CTRL/V {END-LINE} END {ENTER} RETURN {FIRST-CHAR} CTRL/LEFT-ARROW {INTERRUPT} CTRL/BREAK {KEYSTRING-N} F1-F10, SHIFT/F1-SHIFT/F10, and CTRL/F1-CTRL/F10 {LAST-CHAR} CTRL/RIGHT-ARROW {MARK-GLOBAL} CTRL/N {MARK-LINE} CTRL/B {MARK-RECTANGLE} CTRL/R {MARK-TEXT} CTRL/T {NEWLINE} <unset> {NEXT-TAB} TAB or CTRL/I {PASTE} CTRL/P {PREVIOUS-TAB} SHIFT/TAB {READ-COMMAND} CTRL/G {RECTANGLE-SPACES} CTRL/S {SCREEN-LEFT} <unset> {SCROLL-BOTTOM} CTRL/PGDN or CTRL/DOWN {SCROLL-DOWN} CTRL/J {SCROLL-LEFT} CTRL/H {SCROLL-RIGHT} CTRL/L {SCROLL-TOP} CTRL/PGUP or CTRL/UP {SCROLL-UP} CTRL/K {SPLIT-LINE} RETURN {START-LINE} HOME {TOP-LEFT} <unset> {WORD-LEFT} <unset> {WORD-RIGHT} <unset> -146- 36.8 Interruptions CTRL/BREAK can be used to interrupt loops or long-running NE commands. If NE is expecting keyboard input at the time it is pressed, it is necessary to follow CTRL/BREAK with RETURN. 36.9 Calling other programs There are no restrictions on which programs may be run from within NE, if sufficient memory is available, by using a command line beginning with an asterisk. Even NE itself can be run recursively in this way. -147- 37. LOGICAL KEYSTROKE SUMMARY This chapter lists the logical screen editing keystrokes recognized by NE, preceded by the mnemonics used to specify them in the KEY command (where relevant), and followed by the equivalent NE commands for performing the same operations. al {ALIGN-LINE} ALIGN alp {ALIGN-PREVIOUS} P; PB S//; CSD; ALIGN cssbr {BOTTOM-RIGHT} no equivalent clb {CLOSE-BACK} CLOSEBACK cl {CLOSE-UP} CLOSEUP co {CONCATENATE} no direct equivalent; use CL on previous line csd {CURSOR-DOWN} CSD csl {CURSOR-LEFT} < csr {CURSOR-RIGHT} > csu {CURSOR-UP} CSU co {CUT-COPY} COPY cut {CUT-DELETE} DCUT dc {DELETE-HERE} # dal {DELETE-LEFT} DLEFT dl {DELETE-LINE} DLINE de {DELETE-MARKED} DMARKED dp {DELETE-PREVIOUS} no direct equivalent; use <;# dar {DELETE-RIGHT} DRIGHT csle {END-LINE} PLR {ENTER} not relevant cstl {FIRST-CHAR} no equivalent {INTERRUPT} not relevant {KEYSTRING-N} no equivalent cstr {LAST-CHAR} no equivalent gm {MARK-GLOBAL} MARK GLOBAL lb {MARK-LINE} MARK LINES rb {MARK-RECTANGLE} MARK RECTANGLE tb {MARK-TEXT} MARK TEXT csnl {NEWLINE} N cstb {NEXT-TAB} no equivalent pa {PASTE} PASTE csptb {PREVIOUS-TAB} no equivalent rc {READ-COMMAND} not relevant rs {RECTANGLE-SPACES} ISPACE rf {REFRESH} not relevant cssl {SCREEN-LEFT} not relevant sb {SCROLL-BOTTOM} M* sd {SCROLL-DOWN} no direct equivalent; use N and M sl {SCROLL-LEFT} not relevant sr {SCROLL-RIGHT} not relevant st {SCROLL-TOP} M0 su {SCROLL-UP} no direct equivalent; use P and M sl {SPLIT-LINE} SA or SB cstl {START-LINE} PLL csstl {TOP-LEFT} no equivalent cswl {WORD-LEFT} no direct equivalent cswr {WORD-RIGHT} no direct equivalent -148- 38. COMMAND SUMMARY *<text> pass command line to operating system ? verify current line < move cursor one place left > move cursor one place right # delete character at cursor $ lowercase character at cursor % uppercase character at cursor ~ flip case of character at cursor A <se> <qstring> after <se> insert <qstring> ALIGN align line(s) with cursor ATTN ON permit keyboard interruptions ATTN OFF suspend keyboard interruptions AUTOALIGN flip autoalignment on/off AUTOALIGN ON enable autoalignment for split lines AUTOALIGN OFF disable autoalignment for split lines B <se> <qstring> before <se> insert <qstring> BACK move back to previous change place BACKUP FILES flip output file renaming BACKUP FILES ON enable output file renaming BACKUP FILES OFF disable output file renaming BEGINPAR <se> define paragraph beginning BF <se> find backwards BREAK [<n>] break out of loop BUFFER [<n>] select buffer [<n>] C <file name> obey commands from file CASEMATCH ON match letter cases by default CASEMATCH OFF do not match letter cases by default CASEMATCH flip case matching state CBUFFER <n> obey commands from buffer <n> CDBUFFER <n> as CBUFFER, then delete the buffer CENTRE centre the current line CL [<string>] concatenate line with next CLOSEBACK close up line(s) before cursor position CLOSEUP close up line(s) at cursor position COMMENT <string> output comment text COPY copy marked block to cut buffer CPROC <proc> cancel procedure CSD cursor down one line CSU cursor up one line CUT cut marked block to cut buffer CUTSTYLE APPEND append copied and cut data to cut buffer CUTSTYLE REPLACE replace data in cut buffer each cut or copy CUTSTYLE flip append/replace state DBUFFER [<n>] delete buffer [<n>] DCUT delete contents of cut buffer DETRAIL remove trailing spaces in current buffer DETRAIL OUTPUT remove trailing spaces on output DF <se> delete lines forwards until <se> is found DLEFT delete to the left of the cursor DLINE delete current line DMARKED delete marked text DREST delete rest of file DRIGHT delete to the right of the cursor -149- DTA <qstring> delete till after <qstring> DTB <qstring> delete till before <qstring> E <se> <qstring> exchange <se> for <qstring> ELSE <cg> follows IF or UNLESS ENDPAR <se> define paragraph end F <se> find forwards FKEYSTRING <n> <string> set function keystring FKS <n> <string> abbreviation for FKEYSTRING FORMAT re-format rest of current paragraph GA <se> <qstring> globally after <se> insert <qstring> GB <se> <qstring> globally before <se> insert <qstring> GE <se> <qstring> globally exchange <se> for <qstring> I insert in-line text I <file name> insert named file ICURRENT insert copy of current line IF <cond> THEN <cg> conditional command ILINE <string> insert single line before current ISPACE insert rectangle of spaces KEY <data> specify key binding(s) LCL lower case current line LOAD <file name> load file to current buffer LOOP restart current command loop M <n> move to line n (zero means 'start of file') M* move to end of file MAKEBUFFER <n> [<file name>] create new buffer <n> [for <file name>] MARK LIMIT set global limit mark MARK LINE set line block mark MARK TEXT set text block mark MARK RECTANGLE set rectangular block mark N move to next line NAME <string> set file name NEWBUFFER [<file name>] create new buffer [for <file name>] OVERSTRIKE ON overstrike data characters OVERSTRIKE OFF insert data characters (default) OVERSTRIKE flip overstriking state P move to previous line PA <se> point after context in current line PASTE paste cut buffer in current buffer PASTE <n> paste cut buffer in buffer <n> PB <se> point before context in current line PLL point to line left PLR point to line right PROC <name> is <cg> define procedure PROMPT ON enable prompting for current buffer PROMPT OFF disable prompting for current buffer READONLY ON make current buffer read-only READONLY OFF make current buffer read-write READONLY invert read-only state of current buffer REFRESH update current screen RENUMBER renumber lines in current buffer REPEAT <cg> loop of indefinite duration RMARGIN flip right margin on/off RMARGIN ON set right margin on -150- RMARGIN OFF set right margin off RMARGIN <n> set margin on, with new value SA <se> split current line after context SAVE [<file name>] [rename and] write buffer SB <se> split current line before context SET AUTOVSCROLL <n> set automatic vertical scroll amount SET NEWCOMMENTSTYLE double backslash for comments SET OLDCOMMENTSTYLE single backslash for comments SET SPLITSCROLLROW <n> set up/down scroll boundary SHOW CKEYS display CTRL keystrokes SHOW COMMANDS display command names SHOW FKEYS display function keystrokes SHOW KEYACTIONS display key action mnemonics SHOW KEYSTRINGS display function keystrings SHOW WORDCOUNT show line, word & char count STOP stop immediately (error return code) STREAM <file name> convert to stream buffer STREAMMAX <n> set line limit for stream buffers T <n> type <n> lines TITLE <string> set title for buffer TL <n> type <n> lines with line numbers TOPLINE current line to top of screen UCL uppercase current line UNDELETE restore deleted character or line UNIXREGEXP interpret regular expressions using Unix syntax UNLESS <cond> DO <cg> conditional command control UNTIL <cond> DO <cg> loop control UTEOF <cg> same as UNTIL EOF DO <cg> VERIFY flip automatic verification state VERIFY ON enable automatic verification VERIFY OFF disable automatic verification W windup (normal exit) WARN flip warning state WARN ON enable warnings (default) WARN OFF disable warnings WHILE <cond> DO <cg> loop control WORD <string> define 'word' for W qualifier WRITE <file name> write buffer to <file name> -151- 39. ARGUMENT FORMAT SUMMARY This chapter contains summaries of the formats for the various different kinds of argument that are used by NE commands. 39.1 String delimiters The available delimiters for string arguments are ' " ! . , : + - * / For file names the delimiter set is a subset of the above, with those characters that are allowed in file names removed. This varies according to the operating system. 39.2 String qualifiers The following qualifiers are available for modifying the effect of string matching: B match at the beginning of the line only C match the line's control character (MVS only) E match at the end of the line only H match 'here' (at current cursor position) only L match leftwards in the line N negate the result of the match P match the line precisely R interpret the string as a regular expression S ignore leading and trailing spaces U match letters in an uncased manner V match letters verbatim W match the string as a word X the string is in hexadecimal <n> the string must match <n> times in the line [<n>,<m>] match between columns <n> and <m>, inclusive 39.3 Regular expressions The characters of a qualified string are interpreted as a regular expression if the qualifier R is present. Regular expressions can either be in NE-style or in Unix-style, which is selected by obeying the UNIXREGEXP command. 39.3.1 NE-style regular expressions The following meta-characters have special meaning: -152- ? wild character " quote character # zero or more repetitions ^ one or more repetitions $ introduces character type or hex - character range ~ negation ( start of group ) end of group | alternation The possible letters that may follow '$', and their meanings, are A alpha-numeric character D decimal digit H hex character or range L letter P punctuation (not letter or digit) S white space (space or tab) W word character When searching in a case-sensitive manner, the case of $A and $L is relevant. $H must be followed by two hexadecimal digits or by two pairs of hexadecimal digits separated by a minus sign. 39.3.2 Unix-style regular expressions The following meta-characters have special meaning: . wild character \ quote character * zero or more repetitions + one or more repetitions ? zero or one repetitions [ introduces character set ] ends character set - character range ( start of group ) end of group | alternation ^ as first character, start of line $ as last character, end of line 39.4 Regular expression replacements When a text replacement command has a regular expression as its first argument, the insertion string can be qualified with the R qualifier, in which case the character '%' in the replacement string is interpreted specially. -153- %0 inserts the entire matched string %<n> inserts wild string <n> %% inserts a single percent character %<x> inserts the character <x> Any number of wild strings can be matched by a regular expression, but only the first nine can be inserted in this way. 39.5 Hexadecimal insertions An insertion string can be specified in hexadecimal by qualifying it with the X qualifier. This can be in addition to the R qualifier for regular expression replacements. -154- INDEX ? command 62, 126 % command 63 \ see backslash ~ command 63 # command 63 $ command 63 < command 62 > command 62 -help 31 -init 128 -line 31, 125 -noinit 31, 128 -notabs 31 -opt 33 -readonly 31 -stream 32 -tabin 31, 33 -tabout 31, 33 -tabs 31, 33 -to 32 -ver 32 -with 32 a 73 'actual' control keystrokes 117 align 114 align-line 13, 16 align-previous 13, 16 alignment of lines 109 'all' prompt response 84 Archimedes: see also RISC OS argument format summary 152 attention handling 104 attn 105 autoalign 12, 77, 80, 109 automatic alignment 109 automatic scrolling 112 autovscroll (set option) 112 b 73 back 68, 92 backing up files 130, 140, 144 backslash in command lines 36 backslash in file name 38, 140 backslash in separator line 15, 80 backup 94 beginpar 81 bf 66 binary files 33 block deletion 18 brackets, nesting limit 36 browsing files 112 buffer 90 buffer deletion 90 buffer handling 88 buffer information 100 built-in function mnemonics 120 c 127 calling other programs: 122 MS-D18~OS 147 RISC OS 143 Unix 130 case-sensitive matching 109 casematch 109 cbuffer 127 cdbuffer 127 centre 80 centring lines 80 'change' prompt response 84 changing defaults: keystrokes 117 operations 109 changing the current line 73 character count 100 cl 77 close-back 13, 17 close-up 13, 17 closeback 114 closeup 114 column numbers 45 column qualifier 45 command arguments: 36 format of 37 command for running NE: 4, 6 command format 31 command group 36 command lines: 25 comments 36 continuation 37 format 36 maximum length 36 stack 39 wider than screen 40 command loops 98 command name 36 command output 39 command prompt 38 command repetition 36, 67, 82 command summary 149 commands: display of 101 commands while screen editing 38 comment 127 comment character 36 concatenate 12, 15 concatenating lines 12 conditional commands 96 context matching 42 control character input 141, 145 control character input (Unix) 133 control keystrokes 102 'control-type' keystrokes 117 copy 115 copying between buffers 91 count of lines & characters 100 count of words 28, 100 cproc 61 crashes: 123 creating new files 32 creating new files: 6 csd 114 csu 114 ctrl/o 14, 111 current line: alignment 13 changing 63, 73 closing up 13 definition 3 deletion 13 display 71 selection 69, 70 splitting 11, 12 verification 62 current point 3 current point movement 68 cursor-down 39 cursor-up 39, 123 cut 115 cut buffer: 18, 106 appending text 110 deletion 90 cut-copy 20, 22 cut-delete 19, 22 cutstyle 110 cutting and pasting 18, 110 dbuffer 90, 111 dcut 90, 110 delete-here 12, 25, 111 delete-left 13, 17, 25 delete-line 13, 17, 25 delete-marked 20, 22 delete-previous 12, 25 delete-previous at screen edge 15 delete-right 13, 17, 25 deleting blocks 18 deleting buffers 90 deleting text 78 deleting the current line 13 delimiters 37, 140 detrail 88 df 67 'discard' prompt response 107 discarding buffers 90 dleft 115 dline 78, 115 dmarked 115 down 9 drest 78 dright 115 dta 74 dtb 74 e 73 editing command lines 25 editing on the screen 11 emergency file 123 emergency file name: MS-DOS 144 RISC OS 140 Unix 130 end of paragraph 24 end-line 15 end-of-file 11 endpar 82 enter 25, 38, 40, 84, 100, 123 error handling 123 error message 39 'error' prompt response 85 error while writing output 108 exit codes: RISC OS 140 Unix 129 extra keystrokes 102 f 25, 65 Fawn II 136 file backup 130, 140, 144 file names: 4, 38, 107 delimiters 38 RISC OS 140 Unix 129 file operations 92 files, large 95 filter, in Unix 128 'finish' prompt response 85 first-char 9, 15, 71 fkeystring 118 format 81 formatting commands 80 formatting paragraphs 23 function keys 38 function keystrings: 38, 103, 118 default values 118 function keystrokes 102 'function-type' keystrokes 117 ga, gb and ge 26, 83 global commands: 83 acting on long lines 86 continuation of 86 interactive 84 margins 86 non-interactive 85 null strings 86 prompting 84 global marker 87 help information 24 hexadecimal characters: in insertion strings 60, 154 in regular expressions 50 in search string 45 inserting whole lines 75 Hydra 136 i 75, 92 icurrent 75 if 96 iline 75 information displays 100 inserting characters 58 inserting files 92 inserting single lines 75 inserting text 75 interactive global commands 84 interruptable commands 104 interruptions: 104 MS-DOS 147 RISC OS 141 Unix 130, 135 inverse video 7, 14, 16, 19, 22, 25, 26, 38, 84 IRIX see Unix ispace 116 joining lines 12, 77 joining rectangles 110 key 118 key actions 102 key definition 119 key identification 118 keyboard interruptions 104 keystring-1 90 keystring-3 29, 106 keystring-6 15 keystring-7 25, 67 keystring-8 15, 70 keystring-9 24, 101 keystring-10 15, 24, 80 keystring-16 15 keystring-17 26, 67 keystring-18 15, 70 keystring-19 24, 102 keystring-20 23, 28, 81 keystring-58 10 keystring-59 10 keystring-60 14 keystrokes: binding command 118 display of 101 equivalent commands 114 MS-DOS 145 RISC OS 141 terminal differences 5 large files 95 'last' prompt response 84 last-char 9, 15, 71 lcl 74 leaving NE 29, 106 left 9 line concatenation 12, 77 line count 100 line numbers 7, 62, 88, 137 line search 65 line splitting 77 line-by-line editing 63, 125 Linux see Unix load 27, 92, 111 long command lines on screen 40 loop 98 looping commands 98 lower case 42, 109 m 27, 69, 92 makebuffer 89 margin see right-hand margin mark 114 mark-global 87 mark-line 16 mark-rectangle 21 mark-text 19 matched strings 46 Memory usage 5 mnemonics for built-in functions 120 moving about the file 8 moving between buffers 91 moving the current point 68 MS-DOS: calling other programs 147 colours on screen 145 control character input 145 emergency file 144 file size, maximum 144 initialization 144 interface 144 interruptions 147 keystrokes 145 maximum file size 144 screen colours 145 screen display 144 multi-line editing 16 multiple buffers 88 n 27, 70 name 90 NE command 31 NEcrash 123 NEcrashlog 123 nested brackets 36 network delays 5 newbuffer 89 newcommentstyle (set option) 112 non-interactive editing 125 non-printing characters 16, 62, 141 null strings in globals 86 number as command argument 37 oldcommentstyle (set option) 112 'once' prompt response 84 OSF1 see Unix overstrike 111 overstriking characters 14 p 27, 70 pa 70 paragraph formatting 23, 81 paste 20, 22 paste 115 pasting 18 pb 70 pll 71 plr 71 power typing: 11, 27, 80 previous-tab 9 proc 61 procedures 61 prompt 111 prompt: command line 38, 122, 123 cut buffer 29, 106 global commands 26, 84 line mode 64 output file 29, 93, 107 pause 100 suppression of 90, 111 qualified insertion strings 58 qualified strings 42 qualifier combinations 46 qualifiers for search expressions 47 'quit' prompt response 85 read-command 25, 38 readonly 112 rectangle-spaces 23 rectangular blocks 21 refresh 40 refreshing the screen 8, 40 regular expressions: 44, 48 alternation 52, 56 beginning of line 56 character classification 50 character ranges 50 character repetition 49, 54 character sets and ranges 55 end of line 56 grouping 51, 56 hexadecimal characters 50 meta-characters 48 negated alternation 52 negation 51, 55 quoting character 49, 54 replacements 153 summary 152 Unix syntax 54 wild character 49, 54 wild replacement 58 renumber 88 repeat 98 repeat qualifier 45 repeating change commands 74 repeating search commands 67 replicating lines 75 restoring deleted text 79 return 12, 119 return codes: RISC OS 140 Unix 129 right 9 right-hand margin 11, 14, 24, 80, 86 RISC OS: calling other programs 143 configurable keys 141 control character input 141 desktop 137 emergency file 140 file names 140 file types 139 initialization 139 interface 137 interrupting NE 141 keystrokes 141 non-printing characters 141 return codes 140 taskwindows 138 terminal emulators for Unix 132 rmargin 27, 80 sa 77 save 28, 93, 111 saving files 93 sb 77 screen display 7 screen refresh 40 screen refreshing 8 screen-left 10, 15 scroll-bottom 10, 70 scroll-down 10 scroll-left 15 scroll-right 15 scroll-top 10, 70 scroll-up 10 scrolling command line 40 search commands 65 search expressions 46 search expressions, qualifiers for 47 search repetition 67 search type: line search 65 string search 65 semicolon 36 separator lines 7, 14, 109, 110, 111 set 112 show: 100 ckeys 102 commands 28, 101 fkeys 102 keyactions 102 keys 101, 121 keystrings 103 wordcount 28, 100 xkeys 102 single-character commands 62 'skip' prompt response 84 spaces, trailing 88 special keystroke names 119 split-line 12, 15, 111 splitscrollrow (set option) 112 splitting lines 77 start-line 15 stop 28, 106 'stop' prompt response 107 store see memory stream buffer 101 string as command argument 37 string delimiters 37 string qualifier summary 152 string qualifiers 42 string search 65 summaries: argument formats 152 commands 149 regular expressions 152 string delimiters 152 string qualifiers 152 SunOS see Unix t 126 tab 9 tabs 33 termcap 131, 133 terminal type: Unix 131 terminfo 131 text blocks 19 tl 126 'to' prompt response 107 topline 71 trailing spaces 88 TTP 136 ucl 74 undelete 79 undeleting 14 Unix: control character input 133 ctrl sequences 133 emergency file 130 environment variables 128 esc sequences 133 exit codes 129 Fawn II terminal emulator 136 file names 129 Hydra terminal emulator 136 initializing commands 4 interface 128 interruptions 130, 135 NE as a filter 128 RISC OS terminal emulators 132 shell commands 130 terminal type 131 TTP terminal emulator 136 xterm terminal emulator 135 Unix regular expressions 54 unixregexp 48 unless 96 until 98 up 8 upper case 42, 109 user initialization 4 uteof 98 verification output 125 verify 126 w 106, 111 warn 113 while 98 wide lines 14 wild character 49, 54 wild replacements 58 word 113 word as command argument 37 word character 113 word count 28, 100 word-left 9 word-right 9 write 93 writing part files 93 xterm 135