ACE User Guide ============== Revision 0.06 -- December 87 -- Steve Rencontre Note - this document assumes a fairly high degree of familiarity with software concepts in general and the Amiga operating system in particular. I. Introduction --------------- Ace is a fast text editor for the Amiga. It is intended primarily for use by programmers writing in C or assembler, and is not by any stretch of the imagination to be considered as a word processor. Ace is absolutely specific to the Amiga computer, and makes no compromises for portability. Multi-tasking and the Intuition environment are exploited to the full, but never to the point of sacrificing speed of operation. This is the primary design goal of Ace. Remember, of course, that multi-tasking will slow you down if other things are happening. Ace does not currently alter its execution priority, so you'll need to do a CLI ChangeTaskPri command if you want to give it a bit more processor time. The current implementation is usable and reasonably bug-free, but it's early days yet, and many new features will be incorporated in the not-too- distant future. The main reason for making it available in this preliminary form is that I gather from talking to other Amiga programmers that there aren't ANY fast editors around. Ed is unbelievably slow, Lattice is just as bad, I hear TxED is nothing marvellous, etc... Well, folks, it CAN be done, and no assembler or dodgy code needed - just read the RKM carefully and design your program to avoid unnecessary screen operations and away you go! Be aware that Ace is designed for my benefit, not yours, and that every feature incorporated or omitted is because I think it's better that way (or I haven't got round to it yet...) If you don't like it, send me something interesting and I'll let you have the source code in return. ('Interesting' in this context is deliberately left undefined!) PS - you may find that you can't compile it without the latest version of Lattice C, since the code is designed to take advantage of any available compiler/linker efficiencies. Ace 0.06 has been produced with Lattice C 4.00/Blink 7.2. II. Current features -------------------- STARTUP ------- Ace may be run from CLI or Workbench. The CLI syntax is, Ace [filename] If a filename is not specified, you will be prompted for one. The name need not refer to an existing file. From Workbench, you can double-click on the Ace icon, in which case you will again be prompted for a filename, or double-click on an Ace project icon. The default is for Ace to create icons when started from Workbench, and not to do so when started from CLI. If you wish to run Ace from Workbench WITHOUT icons for files, you can set 'NOICONS=TRUE' in the Tool Types field for Ace. (Select the Ace icon and choose Info from the Workbench menu. The word NOICONS must be in upper case, and strictly speaking, the word TRUE can be absolutely anything you like - the NOICONS= is the significant bit!) You cannot create icons at all if you start from CLI. IMPORTANT: As of version 0.06, you MUST have Kickstart/Workbench 1.2 or later. Ace will abort in a reasonably polite way if this is not the case. KEYBOARD -------- Cursor movement: arrow keys or click left mouse button. Cursor left/right does NOT wrap to previous/next line. Single line/column scroll: ALT-arrow keys, or automatic at edge of window. Page up/down: SHIFT-up/down arrow. Be aware that page redisplay is asynchronous and that no keystrokes are lost, even if the display can't keep up with the autorepeat rate. This means that you are still moving through the file at (say) 15 pages per second, even though the display takes nearly a second for each refresh. It just means that you only get one in ten or so pages displayed during the scroll. I really don't know how to avoid this without abandoning the Text() library call and burrowing into the graphics and layers libraries. Maybe if you install this FastFonts package I heard of somewhere it'll make a difference. BACKSPACE key moves left and replaces previous character with space in overtype mode or deletes it in insert mode. DEL key deletes current character and shifts rest of line left. SHIFT-DEL deletes to end-of-line. ENTER key (on numeric pad) inserts space at cursor position. RETURN key takes you to left margin and down one line. On the last line of the file, RETURN will create a new line for you. It does NOT have this effect otherwise. Cursor down will NOT move beyond end of file. TAB moves to next tab position (currently 4-col multiples for C programs and prose, 12-col for assembler). (You will NOT necessarily get TAB (0x09) characters in your disk file - see below for tab character usage in files.) SHIFT-TAB moves to previous tab. F1 inserts blank line after current. SHIFT-F1 deletes current line. F2 splits line at cursor position, padding second line with leading spaces. SHIFT-F2 joins next line to current deleting intermediate spaces. F6 toggles case of alpha characters (including G1 extended set) Note: No word-wrap yet - lines will just get longer and longer as you type until you hit the arbitrary limit of 32767 characters I have imposed. (OK, so it's not REALLY arbitrary, but you know what I mean...) MOUSE ----- Click left button to position cursor. Click and drag to select blocks of lines. If you move the mouse above or below the text area of the window, the selection area will scroll as appropriate. Character-level selection is not currently possible. Click close gadget to save and exit. Note that the Quit menu selection does NOT allow you to save (but does warn you if changes have been made). Front/back and sizing gadgets are standard, but note that the window uses SIZEVERIFY so that if you resize while Ace is thinking, Intuition will freeze for a moment. This is not normally a problem, but if, say, you're saving a large file to floppy, you might get worried by this effect. MENUS ----- Project New discard current file and prompt for a new one. If the current file has been changed and not subsequently saved, a requester appears warning you of this. Cancelling the discard operation returns you to the current file unchanged. When prompted for the new filename, if you just hit RETURN, the operation is cancelled. This convention applies to all operations that use the command window. Use the Open menu selection to save the file before starting a new one. Open save current file, prompt for a new one. Save rename 'file' to 'file.bak', write current data to 'file'. Save as as Save, but asks for a new filename. Quit discard everything and exit. The warning requester appears if you have pending changes. Use the close gadget for save and exit. Block Cancel deselect block. Delete delete marked block. If there are not enough remaining lines to fill the window, trailing blanks are created. This can cause a milder version of the problem mentioned under Find/Goto, described below. Copy copy block after current line. If the current line is within the block, other than on the last line, interesting things happen which may or may not be useful. (The current line is defined as the one that the cursor is on. This seems reasonable...) Move move the block to follow the current line. If you try to move the block inside itself, it gets moved to follow the first line after the block. (A simpler way of looking at it is that it's equivalent to saying that the line after the block gets moved in front of the block.) Read brings up a window asking for a filename and reads it in after the current line. Write asks for a filename and writes the current block to it. Find Find brings up a window asking for a search string and moves to the next instance of that string. See below for rules defining regular expression searches. Replace like Find, but also asks for a replacement string. No context- sensitive replacement text - it can only be a literal. Note that if you just hit RETURN for the replacement string it cancels the operation - if you want a null replacement (ie, delete the found text) press the ESC key (followed by RETURN). Again repeats the last Find or Replace operation. Goto brings up a window asking for a line number and moves there, or the beginning/end of file if the line number is invalid. Note a small bug: if you repeatedly Goto a very large number, you will get more and more blank lines tacked onto the end as Ace tries to display the last line at the top of the window and creates blank lines to fill the rest. These will go away when the file is saved because Ace never writes trailing blank lines or characters. Top take you to the first/last line of the file respectively. These Bottom functions are identical to using Goto with a line number less than or equal to one, or greater than or equal to the total number of lines, and are provided purely for convenience. Column like Goto, but takes you to a given column number. NB - line and column numbers start at one, not zero. Text Paper allows you to set the background colour. Ink ditto for foreground colour. Font searches memory and FONTS: for all mono-spaced fonts, and displays a requester for you to choose. Maybe I'll add pro- spaced ones sometime. I have a kind of idea that source code keywords would look good in a different typeface and things like that... Left margin sets the left margin to the current cursor position. The only effect this has at present is that it is where the RETURN key returns to. Right margin currently has no effect other than to display a margin line. It will probably remain advisory-only except in Prose format, when it will be used for word-wrap and paragraph repacking. NB: attempting to set the left and right margins the wrong side of each other will have no effect. Margin clear gets rid of both margins (ie, sets left margin to column one and right margin to 32767). Modes Insert self-explanatory, I hope. Overtype Max width removes the left and right window borders to allow the maximum possible text display width. The sizing gadget remains fully functional, and its vestigial remnant is just visible at the right-hand end of the bottom border. On a European PAL screen, this allows a maximum of 30 lines of 80 characters if you expand the window to fill the screen. I suggest changing the paper colour to retain a clear visual indication of the window limits. Normal restores the left and right borders to normal. Format C sets tab interval to 4, disables word-wrap [, enables auto- indentation, simple syntax-checking, parenthesis-matching, etc -- still to be done ] Assembler sets tab interval to 12, no word-wrap [, auto comment chars, etc, to be added ] Prose 4-col tabs [, word-wrap at right margin ] Info ACE displays some bumf about Ace, including the address to send contributions to if you're feeling guilty/generous. III. Regular expressions ------------------------ In search and replace operations, the search string is normally considered as a pure literal. However, if the first character is a ` (open quote or grave accent), the subsequent characters are treated as a regular expression formed according to rules similar to the Unix 'grep' utility. A full account of regular expressions is NOT given here, so if you've no idea how to use them, just think of them as like wildcards only a lot more so! The following symbols have special meaning in RE's:- ^ start of line (only if first char in RE) $ end of line (only if last char in RE) . any single character [xyz] any single instance of the characters x or y or z [x-y] any single character from x to y inclusive [!xyz] any single character EXCEPT members of the specified class [!x-y] sss* zero or more instances of the subexpression sss sss+ one or more instances of sss \c escapes the following special character c, where c is one of the characters listed above (including \ itself) or one of the standard C special escape characters, ie, \b = backspace, \n = newline, \r = return, \t = tab, although none of these latter will ever occur in normal Ace text. \xXX can be also be used to represent any arbitrary hex value XX. Note that because many of the special characters used in regular expressions are also commonly used in C programs, the default for search strings is not to use them. The ` character will almost never occur in a program, but if you genuinely want to search for a string beginning with this character, you must construct an RE for it. Moreover, RE's are MUCH!! slower than literal searches (by a factor of ten according to one test... when I was first checking that the code worked, I thought I'd screwed something up when my cursor disappeared and the keyboard went dead. No - I was just searching for a non-existent string in a 32K-odd file, and it took a long time not to find it. Oh well, everything else in Ace is very fast!) Although the ^ and $ characters allow you to anchor the match to one end or another of a line, you cannot search for a string split over more than one line. This kind of search is rarely useful for program source text. The implementation of RE's used here is from the Lattice Text Management Utilities package. It is not quite identical to the Unix implementation, but the differences are slight. It is also worth remembering that it is quite different to AmigaDOS pattern-matching conventions, which in some ways are more powerful, eg, the (string1|string2) format. I may at some point replace this with my own implementation which will probably be a superset of the AmigaDOS format. Still, don't complain, 'cos without the Lattice functions I probably wouldn't have got round to implementing RE's at all yet. An idiosyncrasy you should know about: trailing spaces on the end of a line may or may not be present, but are invisible to the user. However, they ARE visible to the search and replace functions. Thus to find the last non-blank character on a line, use '.[ ]*$', NOT just '.$'. IV. Significant known bugs -------------------------- Don't select Syntax/Prose. Anything that makes Ace try to do wordwrap will destroy parts of your text and possibly corrupt the line chain. Corrupting the line chain is the worst thing that can possibly happen to Ace and will result in damage to your file and/or a Guru. Wordwrap should be thought of as unavailable at present, as stated above, even though there is a sort of half-working facility there. (In fact, you might even get a crash that's too severe to display a Guru alert!) If you run out of memory while reading a file, Ace will just stop reading it without warning you that you haven't got the whole file. Naturally, if you save without noticing this, it will not magically reappear. This is a big problem in the following scenario:- Edit a file and lose some of it... recompile and see a simple typing error generate a whole cascade of messages... don't notice any 'unexpected end-of-file' message or ignore it 'cos you think it's just an artifact... re-edit the file and fix the typing error... save, overwriting your old GOOD .bak file with the truncated version! The reason for the absence of warning is that Ace will one day page to disk without you having to worry about memory size. At present though, if it runs out of memory, trying to post a requester could cause a Guru, so it doesn't! V. Miscellaneous info --------------------- Ace compresses spaces to 8-column tabs, in line with the console.device expansion. Trailing spaces on lines and trailing blank lines are always discarded. Lines are always and only terminated by a newline character. No other control characters will appear in the file than tabs and newlines, but non-ASCII graphics are permitted: strictly, anything above 0x1F, which includes the C1 control set. I may exclude C1 at some point, or possibly implement SHY and NBSP properly. (However, I doubt there are any compilers that would like them.) Remember that some fonts may not contain all characters - if in doubt, stick to Topaz! A subtle point is that while Ace will not allow you to put control characters in a file, it won't reject a file just because someone or something else already has. This means that Ace will display the 'not in font' symbol for such characters, but provided you leave them alone, no harm will come of it. If you delete one, though, there is no way of getting it back. I must do some work in this area one day... A subtle, recently-introduced, point about space compression. As of v0.05, Ace will NOT compress spaces within quoted strings, since they are almost certainly meant to be exactly as they appear to be. For example, unless you are lucky, console or printer output will not line up the way it seems to in the source code. The rules are very simple - any occurrence of a single or double quote turns off compression until the next occurrence of the same character except when preceded by the C escape symbol \. This is pretty much the same rule that a C compiler itself would follow. It also works fine with the other main convention used, which is that a repeated quote inside a string represents the quote character itself. If anyone remembers the good old FORTRAN Hollerith string, tough 4HSHIT baby - it won't work! Be aware of some limitations in the algorithm:- it works purely on a line-by-line basis, so if a string is continued over more than one line, all but the first line will have the wrong toggle state. Similarly, quotes used as an apostrophes or ditto marks in a comment are not picked out as special, thus if a comment PRECEDES the code on a line, it may cause problems. Neither of these cases are likely to occur in most programs, but you could go quietly crazy if you weren't warned! Ace needs about 70K for itself, plus text data space. It does not allocate memory before it needs it, and releases it when it's finished with it. Each line of text from the file has 9 bytes of overhead, plus the characters in the line. Internally, spaces are always fully expanded within a line, but trailing spaces are generally omitted. If you delete the last non-space character on a line, or physically type spaces beyond the last non-space, these will remain until the file is written, or they are explicitly deleted. There will be a 'Tidy' menu option at some point to do garbage collection. This is not likely to be of any great relevance! The command window uses a standard AmigaDOS console window, so the rules for typing search strings, etc, are not the same as within Ace proper. This will be changed when Ace goes fully re-entrant and multi-tasking. The current version only handles one file at a time, and a complete copy of the code is loaded every time Ace is started up. The intended future structure is a DOS server process and satellite tasks which communicate with it. The task code will be fully re-entrant, thus subsequent to the first execution of Ace, no extra code space will be needed for further files. At startup, Ace will look for its message port, and if it finds it, will send a message requesting a new file task and exit. If not, it will LoadSeg the rest of the code and become the server. The Project/New menu item will also become a way of starting another file task and will no longer discard the current one. If you specify a non-existent filename to edit or read in, a requester will appear warning you of this, but it is not considered an error - it is equivalent to reading in a file with no data. Ace ALWAYS creates a .bak file if the file is saved. There is no way to disable this, and won't be until the code is a lot more stable! Note that .bak is a true suffix, and does not replace any original extension. This means that if you edit 'prog.c' and 'prog.h' at the same time, you won't be embarrassed by losing one of the .baks! This also applies equally to the 'Write block' and 'Save as' options - Ace is currently totally paranoid about over-writing good data with bad. If you do something silly, like delete-protecting a .bak, you won't be told that Ace has failed to over- write it with the proper data. If you edit a .bak, you will get a .bak.bak file, and so on until you hit the 30-character AmigaDOS limit. When this happens, the filename is truncated to the first 24 characters plus .bak. Ace has an internal 80-character limit for total device:path/filename text, so if you exceed that, the name will again be truncated. Note a curious effect with unlikely names. If you have a file called '.../subdir/a' which is 80 characters long, the backup file will be called '.../subd.bak'. Ie, it will be a different filename in a different directory! Incidentally, since every file output operation in Ace goes through the same routine internally, .bak's get created (if necessary) by Save, Save as, Close and Write block. The same is true of .info files if icons are enabled. This means that you can quite rapidly use up a lot of disk space if you're not careful. Writing to a device, volume or assigned name, ie, anything ending in ':' will cause Ace to suppress its normal writing of a .info file if icons are enabled. You will notice that the cursor goes away sometimes. During block operations, etc, this is to indicate that you can't type or do anything until the operation has completed. During scrolling, it is to avoid the overhead of redrawing the cursor for every scroll. It will come back as soon as you release the key(s) you had pressed. (Line and column scrolling are, in my not very humble opinion, the most time-critical operations any editor can have. (Apart from actual keyboard response which ought to be indistinguishable from instantaneous, but have you ever seen one of those word processors that have one cursor to show you where they are, and another to show you where they would be if they could display the text as fast as you typed it? I kid you not!)) You can't interrupt any operations partway. However, none of the Ace block operations are particularly time-consuming. When Ace gets macros, there will be some way of aborting a macro, but for now there doesn't seem to be any need. I haven't done any theoretical calculations, or performed exhaustive tests, but Ace seems quite happy with the default 4K stack size. Obviously (?), if you do get semi-repeatable weird effects, that's one of the first things to look at. Many operations cannot be performed without a mouse. This is unlikely to change until I put some macro facilities in, and even then it's quite likely that there won't be true keyboard equivalents for all mouse actions. If you're not a mouse fan, Ace is probably not for you! A word or two on function keys, etc... In traditional fashion, all my function key assignments are different to every other editor the world has ever known. I thought of maintaining Ed compatibility on the grounds that at least it's probably reasonably well-known, but I have ended up with the following philosophy which is (fairly) consistent if nothing else. Character keys produce characters or nothing, regardless of control/shift/ alt variations. Labelled function keys (TAB, cursor arrows, etc) do what you would expect. F1 to F5 are line-oriented functions, F6 to F10 are character-oriented. SHIFT makes things bigger or reverses them (?!) and ALT makes things do something similar but different. (It's perhaps worth mentioning that control-M is NOT the same as RETURN, etc - Ace does not treat the keyboard as a purely ASCII device.) A small tip - Ace has no explicit 'Print' option, but 'Save as PRT:' does the job quite nicely. Admittedly, it doesn't do it as a background task, but you'd need to be locked out of the file while it was printing anyway, to keep it consistent. Ace is an acronym for Amiga C Editor, partly 'cos it's written in C, and partly 'cos it's intended for writing C. Syntax-checking and auto-formatting are on the way! (Not that there's any reason why you can't use it for Pascal, Basic or what-have-you, but don't expect any special features to support such strange behaviour...)