ARM Club 3/TheARMClub_PDCD3.iso/hensa/misc/lineeditor_1/!ReadMe

Text File | 1998-10-20 | 23KB | 504 lines

                        LineEditor Module release 2.73
                        ==============================

** Source, binaries and documentation                  **
** Copyright (C) Oliver Betts 1994,1995,1996,1997,1998 **

This software is provided as is - it has been tested to a reasonable extent,
but probably has a few lurking bugs.  I take no responsibility for any loss
or damage, directly or indirectly caused.

UNIX is a trademark of AT&T; 4DOS is a trademark of JP Software Inc.
Incidentally, I highly recommend 4DOS if you have to use DOS.

Versions with a letter suffix are test versions and may only be distributed
with express permission from me.  Other versions may be distributed freely
provided all files are supplied intact and that no profit is made.  You may
bundle it with other freeware software provided these distribution
restrictions are met, but please make sure you're supplying the latest
version.  If you want to distribute it in some other way, get in touch.

*****************************************************************************

This module started out as some modifications to version 2.30 of Richard K.
Lloyd's LineEditor module, to make it work better with TaskWindows
(specifically to use the same *FX4 and *FX 220-228 settings as the Wimp).

However, RKL seems not to respond to email or snail mail, and so not having
his permission to release my modified version, I have entirely rewritten the
module.  In doing so I have fixed a number of bugs which were in the original
and added many extra features, some of which were inspired by tcsh (and other
UNIX shells) and 4DOS (for DOS!).

I'm still actively working on this program, so watch out for new versions.
Please let me know if you find any bugs or problems (read this file first
though!).  I'll release the source with future versions.

Files in this release:

!ReadMe    - this file
LineEditor - the module
RebindKeys - obey file to change key bindings
Actions    - a list of the actions which can be bound to keys
DfltKeys   - default key bindings
OllyKeys   - the bindings I use -- provided as an example
Rebinder   - used by RebindKeys -- don't run directly

The keys file has a very similar layout to the !Zap keys file.  The
mechanism for rebinding is a bit nasty, and will be improved when I get
some spare time.

For a list of the default key bindings, load the LineEditor module and type
"*Help Editor".

Random note:  Ctrl-N is now mapped to Next-line (same as cursor down), and
similarly for some other useful Ctrl-<letter> combinations.  Unless bound
otherwise, Ctrl-Shift-<letter> is bound to "vanilla", which will input
Ctrl-<letter>.  Alternatively, "quote" the keypress, e.g. Ctrl-Q Ctrl-N.

Use with Dom Symes' !Zap (see also !Zap's !Help file):

* To use function keys and Control + key you need to type Ctrl-Q first to
  "Quote" the key - otherwise !Zap will process the key.  The cursor keys,
  TAB and PageUp/PageDown are passed through and so don't need quoting.
  !Zap 1.20 will also pass most Ctrl-Letter combinations through, although
  it won't pass through keys that have certain actions bound to them (eg.
  QUOTE).  See the !Zap documentation for a complete list.

* COPYing works - activated by the command COPY which is bound to COPY and
  Shift-COPY by default.  From !Zap 1.20, pressing Escape during COPYing will
  stop the copy, but not abort the line.  Press Escape again to abort the
  line.  LineEditor behaves in the same way outside of TaskWindows.

* TaskWindows under RISC OS 2: The TaskWindow module supplied with !Edit on
  RISC OS 2 Application Disc 1 (v 0.03) won't work with !Zap - you need the
  one supplied with the C/Asm DDE (about 0.29) or above.  0.03 only works
  with !Edit 1.00 and not very well.  The RISC OS 3.1 TaskWindow module
  works best of all, but you can't legally get it without having RO 3.1...

* With the default keymap supplied with !Zap 1.10 and 1.20, Enter on the
  numeric keypad acts like Ctrl-J in TaskWindows, ie the line isn't stored in
  the history.  You can make it act like Return by altering the appropriate
  line in the keys file from:
   kENTER        &166    RETURN
  to:
   kENTER        &166    CHAR &0D
  which makes Enter behave like Return in TaskWindows, and in other modes.

* Due to a minor bug in !Zap, Ctrl-Q Ctrl-@ in a TaskWindow gives an `R',
  rather than setting the mark.  A work around is to use Ctrl-Q Ctrl-SPACE
  instead in TaskWindows.

Use with Acorn's !Edit/!SrcEdit:

* !Edit/!SrcEdit TaskWindows don't "understand" the codes to move the cursor
  left and right (&08 and &09) so things don't work terribly well.

* My version and RKL's seem to work equally well/badly (simple recall and
  filename completion work okay).

* I don't think it's possible to work around not having VDU 8 - get !Zap if
  you want to use TaskWindows much - it's much faster too!

Use with Alun Jones' !TaskShell:

* TaskShell 1.21 has very full VDU support (since it runs full screen and
  uses the OS VDU calls).  It works well with LineEditor, except that
  Ctrl/Shift + Tab combinations don't work as expected (Alun has acknowledged
  this a due to a shortfall in TaskShell's emulation of the keyboard system).

* Unfortunately, TaskShell doesn't currently support cursor copying.

* LineEditor doesn't send codes to change cursor shape to TaskWindows (as
  they are ignored by most servers and just slow things down a bit).  With
  TaskShell, they would change the cursor shape, but it's not easy to tell
  the difference between a TaskShell and a TaskWindow.

Use with Guttorm Vik's !StrongED:

* Recent versions of StrongED (I've tested with 4.11beta2) have improved
  TaskWindow support, and support all the codes LineEditor requires.

* !StrongED support COPYing in TaskWindows, in much the same way as !Zap.

Use with Brian Brunswick's !VMode:

* VMode is a graphical desktop TaskWindow server.  It's a bit slow though.
  Version 1.5 seems to work with LineEditor so long as you don't want to
  use the cursor keys, the function keys, Tab, etc.

That's all the TaskWindow servers I am aware of.  If you know of any others,
let me know and I'll check them out and add them to the list.

Use with RISC OS 2:

* I've added code to versions 2.34 and above to read the task handles of
  TaskWindows under RISC OS 2, so local history buffers should now work.

* The TaskWindow modules supplied with RISC OS 2 and the Acorn C DDE (0.03
  and 0.29 anyway) have a problem - if LineEditor is loaded, closing a
  TaskWindow doesn't release the memory allocated to the task.  This would
  seem to be a TaskWindow bug [it occurs if you soft-load 0.03 or 0.29 with
  RISC OS 3.1, and with RKL's version].  My best advice (other than to get
  RISC OS 3.1) is to reduce the next slot before starting a TaskWindow and
  not to close task windows that you might want again.

* There's a problem with the cursor keys producing symbols rather than being
  interpreted as cursor keys with some setups when using TaskWindow 0.29.

Comments and suggestions are greatly encouraged - email will get a reply (if
I can get through), snail mail will eventually, but don't hold your breath.
Please try to give as much detail as possible in bug-reports - steps to
demonstrate the bug from loading in the module are very helpful indeed.

Thanks to Andy Hayward, David Moore and Dom Symes for testing and comments.
Also to Clive Jones for suggesting how to find the current task's handle
under RISC OS 2 (though his idea didn't work ;) ).  Also, thanks to everyone
who's reported bugs and problems, particularly Ian Palmer and Nick Craig-Wood
who've been especially diligent.  And to Ben Summers for supplying some
(slightly buggy) code for creating a dynamic area and maintaining a heap in
it, and to OSLib's headers for telling me how to delete a dynamic area once
I've got one.  And Mark Wooding for some code.

The latest versions of LineEditor and most of the other free software I've
written can be found on my web page:

http://www.muscat.com/~olly/

New releases usually quickly make it to hensa and its mirrors at
ftp.demon.co.uk or src.doc.ic.ac.uk.

If you don't have web or ftp access, send me email asking nicely and I'll
send you the latest version.  Or send me an SAE and a floppy disk.

Olly Betts, 1998-10-20

Internet email:         [e-mail]

Indirected snail mail:  Olly Betts,
                        24 Morgans Road,
                        Hertford,
                        Herts,
                        SG13 8BS,
                        UK


Improvements/bugfixes over RKL's 2.30:
======================================

More TaskWindow compatible:
---------------------------

Changed to use same *FX4 and *FX 220-228 settings as Wimp, so using the
line editor in a TaskWindow doesn't screw up the cursor keys.

More values are stored in registers or blocks rather than absolute locations,
which greatly improves behaviour with multiple TaskWindows.

Each TaskWindow now has a separate currently-recalled-line pointer.  If
Global history is on, when lines are deleted (by Shift-Insert, or when the
history buffer gets full), the pointers for each TaskWindow are adjusted
appropriately.

Function keys work separately in each TaskWindow.

You can't *RMKill the LineEditor module while a line is being entered.

Beeps are produced by calling sound system SWIs, so work even if the
TaskWindow server doesn't support VDU7 (e.g. !Edit doesn't).

Miscellaneous bugs fixed:
-------------------------

Ctrl-H performs backspace (RKL's interprets it as Ctrl-Delete and erases
the entire contents of the history buffer!)

Backspace in overtype mode didn't delete characters on the screen.

RKL's gave incorrect underline cursor in non-BBC gap modes (eg MODE 17).

Escape now moves cursor to end of line before exiting.

You can now enter all top-bit-set characters; Eg With RKL's version, you
can't enter LOAD"Ý" (to type "Ý" hold down ALT and type 221 on the numeric
keypad, then release ALT - RKL's reads it as Shift-Insert).

Filename completion code now copes with long leafnames (RKL's would break
for leafnames >11 characters eg AUTOEXEC/BAT is 12).

RKL's used CMOS locations 37 and 38, but his !Trash also uses bits 0-2 of
location 38.  LineEditor now longer uses CMOS RAM at all.

R12 wasn't being passed to readlinev - RKL had just hacked around this...

V flag is explicitly cleared on errorless exit from ReadLineV routine, as
OS_CallAVector doesn't clear V on entry (RISC OS 2 PRMs, vol I, page 30).

Module initialisation code would call OS_GenerateError upon failure - it
should return with V set and R0 -> error block (RO3 PRMs, page 1-204).

Other changes which I view as improvements:
-------------------------------------------

For RISC OS 3.5, it will now create its own dynamic area for workspace,
rather than using the RMA.  This should help to reduce RMA fragmentation,
especially if local history buffers are used.

You can now have separate history buffers for each TaskWindow. (controlled
by bit 0 of the flags word).  Ctrl-Delete wipes *current* history buffer;
*EraseHistory and Shift-Ctrl-Delete wipe *all* history buffers.  When in
local buffer mode, *Recall and *EdStatus put a '*' by the last used buffer.
If the command was typed in using OS_ReadLine, this will be the "current"
buffer, but results may be less meaningful if the command is executed by a
program.

Added PageUp/PageDown to scroll through lines with start matching entered
line (also on shift-cursor-up/down) [like Instigator and cursor up/down in
4DOS].

Added Emacs-like bindings [mostly from tcsh]:
Duplicating existing keys:
 ^A ^E start/end of line ^B ^F cursor left/right ^N ^P next/prev line
 ^D delete right
New actions:
 ^Q quote next key, ^T transpose, ^K delete to end of line, ^@ place mark,
 ^X exchange cursor with mark (Emacs ^X ^X), ^W delete region,
 Shift-^D delete to end of word, ^Y yank back last text deleted with ^K, ^W,
 or Shift-^D

Added another style of filename completion (like 4DOS).  Shift-Tab completes
fully on first match, then Shift-Tab and Ctrl-Shift-Tab step through other
matches.

Removed nasty hacky "Supervisor awareness" as it didn't work for RO 3.x or
at ShellCLI prompt (f12 from desktop). Replaced with better system (for
Acc.Fred[Tab] it looks first for "Acc.Fred*"; if that fails it then looks
for "Fred*" [on the assumption that Acc. is an abbreviated *-command]).

There is no longer a limit on the number of lines in the history buffer,
only on the size of the buffer.

You can specify minimum and maximum lengths of lines to record in the
history.

Doesn't display copyright message on start-up and reset.

Syntax messages added for commands.

Code doesn't bother trying to change cursor shape in TaskWindows (as VDU
sequences are ignored and only slow things up more).

The code is "lazier" about inserting and deleting characters during filename
completion - this gives a slight speed increase in TaskWindows.

My completion code doesn't insert `delete' characters into the keyboard
buffer, which might have caused problems if you pressed Shift or Ctrl at
just the wrong moment.

Next/previous word treat '(' and ')' as word breaks (same as !Zap 1.10).

Module help messages compacted using OS dictionary.

Ctrl-L & HOME now redraw current line (bit like tcsh).

^J still behaves like RETURN but doesn't store line in history.

Doesn't do *Unset LineEditor$Dir (was done incorrectly for *EraseHistory for
example).

Buffers for filename completion code are only allocated when they're needed.

No swi-padding code as it is *not* needed (slightly faster and smaller).

Added option to assemble with less verbose help text.

You can configure completion to add a '.' when completing a directory name,
(a bit like tcsh adds a '/').  However "ls foo/" works and "cat foo."
doesn't, so this is configurable (set bit 1 of the flags word to turn it
on).  As of 2.70 this works for 4DOS-style completion as well.

You can configure overtype mode to be on by default if you prefer (though
why you would is beyond me - still, DOS 6 does it...)

LineEditor will now do completion of system variable names (when enclosed in
'<' and '>') and filing system names (when enclosed in '-').

Shortfalls compared to RKL's version:
=====================================

Changes to the buffer size (RKL's *Configure EdSize) don't affect existing
history buffer(s), but are used for new buffers.  I'm not sure if this is
actually a shortfall or a useful feature - may be fixed.

No wimp frontend (or is that an improvement?) - seriously, let me know if
you think a Wimp frontend is needed - I might write one if it's wanted...

Hasn't been tested with Arthur (the Archimedes OS before RISC OS) - the help
text is compacted but otherwise I think all the new OS calls used fail-safe.
Do let me know if you try it...

Minor "feature" - *FX216,0 no longer stops current function key expansion
during OS_ReadLine, but this is no big deal really - it could be solved by
intercepting OS_Byte, but I can't see much point.


Possible future additional features:
====================================

Add some more csh events (e.g. !$ for last "word" in previous command) and
(optionally) allow csh events to work anywhere in the line.

Improve key redefining stuff

Improve this documentation!

Key-command to glob a wildcarded filename (i.e. expand to a list of all
matching names -- so *.* expands to a list of all objects one directory
down).

Filer_OpenDir/Filer_CloseDir key-commands.  Mostly written, but need tidying
up a bit.

Some actions can be pretty slow (eg type a very long line with no spaces in
a taskwindow, go to the start and delete word (Ctrl-Shift-D).  Then go and
put the kettle on if you have an ARM 2.  This could be improved if the code
was lazier and redrew only the finished result - although as it stands it
does look quite slick on the command line with an ARM 3 or above.

Doesn't work wonderfully in VDU5 mode [neither does RKL's] - maybe fix.

Maybe add Ctrl-Page-Up/Down to scroll case sensitive.

If we allow the size of existing buffers to change, we should preserve as
much of the history as will fit in new size buffer.

As with RKL's, you can recall lines which have characters in which are
outside the range specified by R2 and R3 on entry to OS_ReadLine - the only
solutions I can see are to strip them out (not wonderful) or to only allow
recall if all chars in the range &20-&FF are allowed (this applies to
ShellCLI, BASIC, and GOS (TaskWindows)).  The problem also applies to
filename completion.  Ideas on this one are especially welcome.

Other (please specify): ....................................................

Revision History:
=================

For 2.67 onwards -- See WhatsNew file.

2.66 Now creates dynamic area for workspace under RISC OS 3.5

2.65 [Bundled in !Zap 1.20 release]
     Improved key decoding code so that ctrl-C in taskwindows copies numbers
      okay
     Unbound keys default to vanilla not ignore
     Previously undocumented feature:  vanilla treats Ctrl-J as action return
      so it won't enter lines into the history -- this is useful for function
      keys where you probably don't want the commands executed put in the
      history (Eg. *Set Key$4 <0><&94>SYS"Wimp_CommandWindow",-1|JQUIT|J
      makes scF4 quit the BASIC Editor and return to the desktop)
     sc2 (c@ except on Risc PC) now bound to setmark
     Now deals with flag bits in bits 30 and 31 of R0 on entry to
      OS_ReadLine.  Bit 30 is set for password entry and if set, the
      OS OS_ReadLine is used.  Bit 31 set means echo only those characters
      which enter the buffer and is ignored currently
     vanilla now handles Ctrl-H and Delete

2.64 sReturn, cReturn, scReturn and scJ are now mapped
     If you're copying, Escape now cancels copying mode and leaves you
      editing the line.  Press Escape again to abandon the line.  This
      currently doesn't work with copying in !Zap TaskWindows, since !Zap
      handles the copying itself.  The next release of !Zap will behave in
      the same way.  In the meantime, you can either use ^B and ^F during
      copying, or bind a spare key to uncopy
     You can bind uncopy to keys to stop copying (note that binding it to
      COPY or the cursor keys won't work, as the OS/!Zap takes control of
      them during copying).  The copy action now toggles, but this doesn't
      work if bound to the COPY key for the same reason
     If keystrokes are actually coming from an OS function key expansion,
      now treat them as OS_ReadLine would, so you can program this:
      *KEY 4 <0><&94>SYS"Wimp_CommandWindow",-1|MQUIT|M
      and then use scF4 to return from the BASIC Editor to the desktop

2.63 Shift-SPACE now produces a SPACE in the Default map (and Olly's)
     Keypad /*-+. and Enter now work in the Default map (and Olly's)
     Fixed bug in code which works out !Zap key numbers - discovered via
      dropped characters in combination with Brian Brunswick's Bits module
     Fixed non-freeing of a small amount of RMA if allocation of a new buffer
      fails part-way through
     Fixed problem of "LineEditor in use" when it had never been used

2.62 With global history, if you hadn't used a non-TaskWindow command line,
      then the history was lost if all TaskWindows were closed - fixed

2.61 Fixed bug with reading value of EdFlags
     Fixed off-by-one error in interpretation of minimum line length to store

2.60 Cursor probably didn't get redefined for RISC OS 2 - should be now
     Fixed bug which recalled junk on pressing cursor-up on a non-empty
      line when history was empty
     Streamlined service call handler for "nothing of interest" case
     Should cope better if any SWI OS_Write* returns an error (and hence
      corrupts R0) - eg if *Spool-ing output and the disk becomes full
     All case-insensitive matching code rewritten to be smaller and faster
     Next/previous word now works just like in Zap 1.10 - ie ' ', '(' and ')'
      are treated as word breaks
     Now allocates leafname buffers for filename completion on-the-fly, so
      we can now cope with arbitrarily long leafnames. Tested with Jason
      Tribbeck's LongFilenames module (version 0.08)
     Added ^Y to yank back text deleted with ^K, ^W (like emacs)
     Filename completion now works properly in overtype mode
     *Help Editor output tweaked to fit better on 80x32 screen
     Ctrl-Shift-D deletes to end of word (Emacs Meta-D)
     Keypresses now decoded using !Zap key codes and a 512 byte table to
      enable easy re-mapping
     Compacted help messages using own dictionary
     You can specify a minimum length of line to record in the history -
      currently you set bits 4-7 of EdFlags to one less (eg 4 to store lines
      of 5 chars or more), so 1 <= min. length <= 16
     Doesn't output VDU sequences to change cursor on start-up now (stops
      empty window appearing when LineEditor module run from Filer)
     Ctrl-Down on typed line with empty history gave garbage - fixed
     Delete word can be yanked back

2.53 Path buffer for filename completion now allocated on the fly

2.52 Routine `free' now returns R0=0
     Explicitly clear V on errorless exit from ReadLineV (bug-fix over RKL)
     Fettled help messages and compacted a little more
     R12 is mostly derefenced on entry (smaller and faster)
     OS_GBPB buffer allocated on the fly
     Print padded decimal routine uses 12 bytes of stack for workspace

2.51 Dom suggested adding a '.' when filename completion completed to a
      directory - controlled by bit 1 of EdFlags
     Set bit 2 of EdFlags to turn overtype mode on by default

2.50 [Bundled in !Zap 1.10 release]
     Pressing Tab/^I on an empty line incorrectly moved the cursor left one
      character if a completion occured
     Deleting left at the end of a recalled line didn't set the modified flag
     With empty history, typing something and pressing PageUp recalled crap
     Added 4DOS style filename completion:  Shift-Tab completes fully, then
      steps thru' completions - Shift-Ctrl-Tab steps backwards
     Shift-Copy does the same as Copy (to match !Zap defaults)
     Updated and tidied output from *Help Editor

2.40 Tidied up a little for release with !Zap 1.10 ('cept it's been delayed)

2.35 TaskWindow tracking workspace if now freed on soft-reset
     If a claim for RMA fails, a beep is emitted and something sensible done
      (start-up gives an error, a function key is ignored, starting a new
      TaskWindow reverts to the default OS_ReadLine routine)
     Fixed minor bug in filename expansion code (introduced in 2.34)
     PageUp and PageDown now don't insert start line into the history

2.34 Fixed minor bug in filename completion code
     Added code to find task handle for RISC OS 2 (easier than I thought)
     Now marks "current" buffer with a '*' in *Recall and *EdStatus if
      local history is in operation
     Recoded filename completion to enter characters directly, rather than
      via keyboard buffer

2.33 First beta release