
               ZapPerl, a Zap syntax colouring mode
               ====================================

1.0 Features
============

This module performs syntax colouring designed for Perl documents.
It contains knowledge about all(!?) the keywords of version 5 of Perl.

As a result of the second point, this is my slowest Zap mode to date.

The module contains some enhancements to the cursor keys so that
when they are used in combination with the shift key they behave in a
more appropriate manner than when is in text mode.  These routines have
been stolen from Martin Ebourne's C mode and are documented by him in
his own directory.  Basically they make the shift-cursor combinations
pause more frequently and more intelligently step through the code.
Martin has kindly given permission for his code to be used.

It also contains old C mode style bracket matching and indentation options.

If Ctrl-return is pressed after a "{" (where autoindenting would normally
perform its function), the cursor is placed at the start of the line.
If Shift-return is pressed, then a normal indentation will occur.
These operations operate in a hacky manner, scanning  the keyboard
directly in order to bypass Zap's normal keymap.

The settings for the delay (in centiseconds) may range from 0 to 255.

The limits on the maximum indentation allowed is 31 characters.

Setting either of these to zero turns the option off.
They also now default to off, and so will need to be configured via the
mode menu before they will do anything.

Although the author welcomes correspondence concerning this mode, he
makes no claim that it is bug-free and, it is not guaranteed to perform
any particular function.  It is to be used entirely at one's own risk.

This is Freeware, and may be distributed freely provided that all it is
redistributed intact.  If engaging in large-scale distribution, please
contact the author to get the latest version.


2.0 Installation
================

Copy the !ZapPerl application into the !Zap.Modules directory, then restart Zap.

3.0 Problems
============

                              Mode problems:
			      ~~~~~~~~~~~~~~
* List of functions does not work.
* The mode is over 11K in size, and cannot easily be made smaller.
* The bracket matching gets confused by brackets embedded in strings.
* For people used to using C mode the default colours can be confusing.

                       Syntax colouring problems:
		       ~~~~~~~~~~~~~~~~~~~~~~~~~~
First, the excuse: Perl is not an easy language to syntax colour well.

* The "/" character poses a number of difficult problems for Perl syntax
  colouring modes because it has a number of radically different meanings
  depending on the context in which it is used.  It acts as delimiters
  to regular expressions, and as a division operator.  ZapPerl tries to
  make educated guesses about the context, but it does sometimes get
  things wrong.  If anyone can pin down local criteria for foolproofly
  distinguishing between the various different types od slash, the
  information would be much appreciated.

* Similarly to the "/" character, the "'" character is also problematical.
  this may be the beginning of a quotes section, but may also occur
  legitimately in other contexts.  Once again, ZapPerl may not always
  get this right.

* No attempts are made to match quotes inside regular expressions.
  Regular expressions inside quotes are allowed and parsed correctly.
  As far as I know, this is the most logical situation.

* Regular expressions are now never allowed  in "-strings, '-strings or
  `-strings.  This is because of problems with distinguishing REs
  from the common "/" character in quoted paths.

* Strings cannot be nested in side strings of a different type. Colouring
  these differently would rarely be appropriate, so this is probably the
  correct method.

* Commands inside regular expressions and quotes are not syntax-coloured,
  and (controversially) nor should they be (at least not like normal).

* "@ARGV", "$ARGV" and similar constructs are currently coloured as though
  they are ordinary variables.

* Preprocessor directives are currently coloured as comments.

* There is currently no support for styles of regular expression
  delimited by arbitrary characters (i.e. only the "/"-style works).
  Adding support for this is proving to be quite complicated. Hopefully
  it will be done someday.

* There is no support for the __END__ directive, or its associates.

* There are, it seems, a number of places where it seems that it is
  legitimate to have a hash "#" where it does not start a comment.
  This is most common when the "#" is used to delimit a regular
  expression.  Many of these types of case will currently be coloured
  incorrectly.

If you know anything about Perl, then you can probably improve this mode
by remote control by emailing tt@cryogen.com with your comments.

4.0 History
===========

v0.20 - (04-Mar-03)
      * Reworked the Buttons code

v0.18 - (18-Jul-01)
      * Minor fix to redraw code

v0.17 - (06-Jul-01)
      * Bugfix to Scripts loading code.

v0.16 - (27-Sep-99)
      * Updated for Zap v1.45.

v0.15 - (25-Nov-97)
     * A few new keywords added and all reserved words made case-sensitive.
      * Minor changes to remove options duplicated in the latest release of
        Zap.

v0.14 - (08-Jul-97)
     * Keywords finally wrap properly around line ends.
      * Large speed up by removing a mistake in the code.  It's still
        very slow though.

v0.12 - (01-Mar-97)
     * Buttons support added.
      * New style configuration code added, removing limitations on the
        pause delay.

v0.11 - (02-Feb-97)
     * The # command in REs should now not cause confusion.
      * "'" quotation marks are now coloured correctly if preceded by
        a "{" character, and the linewrapping of their associated colour
        has been slightly improved.
      * Colouring of comments which wrap between lines slightly improved.

v0.10 - (30-Jan-97)
     * SAVEANDRUN should now work properly.

v0.09 - (23-Jan-97)
     * Fixed bug causing all Perl commands to be forced to be displayed
        in lower case.

v0.08 - (21-Jan-97)
     * Fixed bug (introduced in v0.07) causing REs to be coloured badly.
     * Hash commands immediately preceded by "$"s or "^"s are not
        treated as comments.
     * Tried to implement code to deal with arbitrary characters being
        used as regular expression delimiters.  No success yet.  The mode
        looks at its worst when the hash character is used in this context
        and this seems to be regrettably common.
     * Colours in REs are now coloured as REs and not as numbers.

v0.07 - (20-Jan-97)
     * Fixed bug involving clicking on the items in the mode menu.
      * Regular expressions inside strings are now no longer coloured
        as regular expressions.  Deciding what was a RE in these
        circumstances proved too difficult.
     * Fixed bug involving insertion of multiple characters interacting
        with the bracket matching code.

v0.06 - (16-Jan-97)
     * Replace functions such as "tr/ABC/XYZ/" and "tr[ABC][XYZ]" are
        now treated quite sensibly.
      * A number of other minor changes designed to improve the colouring.

v0.05 - (12-Jan-97)
     * "@", "$" and "%" are now all treated in essentially the same way.
      * Bugs with commands being followed by quotes or REs not being
        coloured properly cured.

v0.04 - (08-Jan-97)
     * It is now possible to save the configuration options to disc.

v0.03 - (06-Jan-97)
     * The Zap command "OLEFILECHANGED" was added in error and then
        quickly stripped out again.

v0.02 - (04-Jan-96)
      * Syntax colouring much improved; the syntax colouring may now be
        used to avoid function names that duplicate system functions
        in a much more friendly manner.
  
v0.01 - (03-Jan-96)
      * Very early release as a RFC to the population of the net.


5.0 : Contact
=============

If you have any comments or bug reports concerning Perl mode, we'd love to
hear from you. The best place to send messages to is the zap-users mailing
list at <zap-users@zap.tartarus.org> - you don't have to be subscribed to the
list to post to it. Alternatively, you could contact one of the Zap
developers directly - our addresses are in the Contact section of Zap's
website, which is at <http://zap.tartarus.org/>.
