RISC DISC 1/RISC_DISC_1.iso/pd_share/utilities/zap/!Zap/3rdParty/LineEdHelp

Text File | 1994-03-19 | 11.9 KB | 298 lines

LineEditor Module release 2.50:
===============================

Source, binaries and documentation Copyright (C) Oliver Betts, 1994.

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 someone else.
Incidentally, I highly recommend 4DOS if you have to use DOS.

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 a few extra features, some of which were inspired by tcsh (for
UNIX) 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.

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

Random note:  Ctrl-N is now mapped to Next-line (same as cursor down), so to
turn paged scrolling on, you need to type Ctrl-Q Ctrl-N.  Similarly for
some other useful Ctrl-<letter> combinations.  I'll probably add an option
to allow these bindings to be turned off at some point.

A few comments on use with !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.

* COPYing works - activated by the command COPY which is bound to COPY and
  Shift-COPY by default.

* 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.

Use with !Edit/!SrcEdit:

* !Edit TaskWindows don't "understand" the codes to move the cursor left
  and right (&08 and &09) so things don't work terribly well.  Also, the
  code for a beep (&07) is ignored, so failing filename completions don't
  beep.

* 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 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 the 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 under RISC OS 2.  This seems
  to be the fault of the TaskWindow module again (v 0.29 anyway).

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.
If email bounces, I read the usenet group comp.sys.acorn regularly.  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.

Files in this release:

!ReadMe    - this file
LineEditor - the module

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 ;) ).

Olly Betts, 1994.03.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.

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

Ctrl-H performs backspace (RKL's interprets it as Ctrl-Delete and erases
the history).

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

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 DOSFS leafnames (eg AUTOEXEC/BAT)
(maximum leafname length increased from 11 to 15 chars).

RKL's used CMOS locations 37 and 38, but his !Trash also uses 38 - currently
I only use 6 bits of 37.

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

You can now have separate history buffers for each TaskWindow (controlled by
bit 0 of *Configure EdFlags).  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 on
4DOS].

Added Emacs-like bindings [some are 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 and mark (Emacs ^X ^X), ^W delete region

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 limit on the number of lines in the history buffer, only on the
size of the buffer.

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.

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).

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

Added option to assemble with less verbose help text.


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

Changes to *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) - I see no
reason why it shouldn't work, but this is programming...

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
intersecting OS_Byte, but I can't see much point.


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

Allocate filename completion buffers on-the-fly which'll remove a few
lingering potential reentrancy problems and allow us to cope with arbitrarily
long leafnames.

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

More *Conf. options, for example:
 overtype on by default?
 redisplay on ^L, Home, etc

Add Yank, Delete word and other actions.

Maybe allow user-defined key bindings.

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

Add completion of *-commands? (those implemented by modules through the table
pointed to by the header - can't deal with anyone intercepting `Unknown
*-command'.  This usage is deprecated by the PRMs, but I think Econet has to
use it for *Pass, etc).  We can also cope with aliases (look at Alias$*) and
files on Run$Path.

Maybe change the name (?)

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.


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

2.50 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

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