A quick guide to G.Toal's ECCE-in-C for existing ECCE users. Invocation: ecce {-from} infile {{-to} outfile}? {-log file}? {-size bytes}? Keywords are optional if the parameters are given in the order above. If you omit a parameter, you should give the next keyword explicitly. -from infile This is a mandatory parameter, which is the file you want to edit. If you are creating a new file, use: ecce -from NULL: -to file.new Unfortunately, not all operating systems support named null files, so you may have to create an empty file once which you can use in future, eg on MSDOS you would create a file \NULL with nothing in it, and then ecce -from \NULL -to file.new -to outfile This is an optional parameter, which is the file where you want the output to go. Normally this is not given and defaults to the input file. -log logfile This is an optional parameter, and is a file where a log of keystrokes is writen. It can sometimes be used to recreate an edit (by feeding into a shell or command processor) if your machine crashes. -size bytes This is an optional parameter telling the system how much space ecce has available for the file you want to edit. It has a semi-sensible default depending on which operating system ecce is running; on MSDOS it is 128K, on the Archimedes it is 2Mb. If you use secondary input or multiple contexts, the size of the largest context and the edited file together be less that this number. Syntax: <+/-> This means that the command (eg M) can take a - which reverses in some way the normal sense of the command; ie M normally moves forwards so M- will move backwards. This version of ecce copies Richard Marshall's RED by making as many commands as possible accept -. Occasionally the resulting command may be a little obscure, such as P- and G- (print and move up, get and move back!) but the consistency of commands makes the editor easier to learn and remember. (You can also explicitly give a + to these commands - it has no special effect.) Commands which insert or search for text specify their text strings by enclosing them in valid string delimiters. The only delimiters guaranteed to be available are: " ' . / : = _ (double quote, quote, dot, slash, colon, equals, underline) Text location commands can have their searches limited to a specified number of lines, eg f/fred/ would normally search up to the end of the file -- but f4/fred/ would limit the search to the next four lines. Note that the 'dangerous' commands U and D (which combine text searching with deletion) have a default range of one line; ranges are otherwise up to the end of the file. Secondary input in this version of ecce is implemented by having a number of external 'contexts'. Typically, you would put extract a section of text by using the Note and Abstract commands, eg N m10 A would move a ten line piece of text into the main external context. It could later be reinserted somewhere else in the file by the Here command, eg m0 H The comes into play if you want to keep more that one section of text: you can number each context with a single digit identifier in the range 0 to 9 (if you don't mention a number, 0 is used), so our example above could be replaced by M m10 A1 m0 H1 A simple command like M only does its action once, ie it moves down one line. To make this more useful, you can put a repeat count after the command, so that M10 will move down ten lines. This repeat count is a general facility which can be applied to most commands, for instance f/fred/3 will find the third occurance of fred. There are two special repeat counts: '0' means 'lots', and '!' means 'even more lots'. '!' was implemented to keep really old ecce purists happy -- but its use is to be deprecated: stick to '0' (or its historic equivalent '*') instead. Commands: A Abstract noted region to context B<+/-> Break lines (insert newline) C<+/-> Case flip (or case lock) D<+/-> Delete the next occurance of text E<+/-> Erase characters F<+/-> Find text G<+/-> Get lines (G- puts them in backwards!) H Here (is where to insert the context) I<+/-> Insert text J<+/-> Join lines K<+/-> Kill lines L<+/-> Left move M<+/-> Move down a line N Note this position for later Abstraction O Not implemented. Oh dear! This doesn't do anything? P<+/-> Print (and move) Q Not implemented. Quite what should this do too? R<+/-> Right move S<+/-> Substitute text T<+/-> Traverse text U<+/-> Uncover (by deleteing Up to) text V<+/-> Verify that the text is here W Not implemented. Wait for this - it's reserved. X Not implemented. Y Not implemented. These are reserved for macros (not yet implemented). Z Not implemented. Grouping: ( ) This repeats a group of commands. The description of how repeat counts affect a single command applies equally to a bracketed group. For historical reasons, { }, < > and [ ] also serve as brackets. These should not be used as their meanings may change in the future. Conditionals: , , ! ! ! And if both fail, try this ! ! If it fails, try this next ! Try this one first \ \ makes the command appear to fail if it really succeeded, and appear to succeed if it really failed. ? ? says the command succeeded regardless of whether it did or not. Special commands: Commands starting with % are special and cannot be grouped with other commands. %L Searched text is translated to lower case, The case flip command (C) is modifed so that any text flipped is locked into lower case regardless of what it originally was. %U Searched text is translated to UPPER case, The case flip command (C) is modifed so that any text flipped is locked into UPPER case regardless of what it originally was. %N Searched text is translated to Neither case, ie left as Normal. (case sensitive) Case flipping is normal. %E Searched text is found in either case, ie case insensitive. Case flipping is normal. %V Prints the current version number of ECCE and date last edited. Please quote this if reporting any bugs. %W This Writes out the file (but doesn't close the edit). Useful on micros (or mainframes!) prone to crashing. (A side effect of %W is that if you are in a secondary context, you will be switched to the main context) %C This Closes the edit, writing out the main edit buffer to the output file. %A Abandon the edit without writing out files. %S Secondary input: there are two versions of the %S command: the simple one (with an optional context number) which switches to that context. (If you are in a context already, a plain %S will switch you back to the main edit buffer) And... %S=file This version lets you look at another file while editing the main one. You can make changes in this second (or third, fourth,...) buffer, but they will not be written back to the file. ---------- Implementation notes: 1) Secondary contexts are stored on disc under the names Note where is a context number. This has a useful side-effect that contexts stay around between edits. If the name of the file is chosen carefully (eg T#NOTE0 on emas) the file could be automatically deleted on log off or otherwise semi-regularly (e.g. by a unix daemon). 2) 8-bit data are not specifically supported yet, either as data in a file or as commands to ecce. It is possible that on some machines they work all right as ecce stands, but this is just luck. 3) Some machines (MSDOS and probably VMS if anyone tries it) make a distinction in the C library between files open in "r" mode (normal text) and "rb" mode (binary files). In unix-like systems (and EMAS) it makes sense to open files as binary because their newline character is sensibly the ASCII NL (10). On others it does not, so MSDOS users are forced into text mode whether they want it or not. They just have to hope that the text mode filtering does not upset too much else within their files. Future plans: 1) Change the command-line interface so that new files can be created if they don't exist already. 2) Work out how much memory is spare at run time and use that unless the user overrides it (rather than the current fixed-size default). 3) Implement %X %Y %Z macros 4) Allow the syntax f<13> so that non-printing characters can be searched for. This is going to be a bodge for single characters - it is not worth the effort in writing a complete meta-character string parser. 5) Have a % command to allow newlines in search/delete strings. I have experimented with various non-standard ecce features (such as NOT moving the cursor if a search fails); I decided that useful as they may be, they still cause too much confusion to users ingrained with years of traditional ecce practise (unless you have to ask for them explicitly.) 6) The PANOS version uses lots of machine-dependent stuff for interrupts. Once PANOS is officially dead (am I the only user?) all this code can be removed. 7) The #ifdef stuff is VERY messy. This needs rationalisation. It would help if I could get a list of the #defines made automatically by each compiler on each machine on which it has been compiled. 8) Some ecces have a o/text/ command analogous to i/text/, which overwrites text, extending the line if need be. I may add it IF anyone asks for it. 9) Some day (!!!) I would really like to hook my version of ecce into a good screen edit, as an 'ecce button' which invoked ecce recursively within the screen editors main editing loop (assumed, like emacs, to be in a lisp-like language). The ecce command as invoked could then issue an I (insert) or O (overtype) command -- WITHOUT a text string argument -- which would in turn recursively invoke the screen editor! This would allow you to program complex ecce commands (such as repeated finds using say a V/.../ macro) but make the changes at the located text by hand on the screen. Don't sit up waiting for this, though...