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

Text File | 1994-03-03 | 8.6 KB | 299 lines

This is the ReadMe file for ZapCMode 0.20

    © Bryan Scattergood (03-Mar-1994)

This is an extension mode for Zap.  It requires Zap 0.91 or later.  It adds
simple bracket matching and automatic indent to the standard Text mode in Zap
to create a mode suitable for editing C, Pascal, Tex, LaTex and Gofer.  It
does *not* add bracket matching to BASIC mode.

It also adds a C function browser and function search commands, in the style
of Martin Ebourne's derivative of CMode 0.03 (which he called 0.10).  It now
supports a simplified version of his compilation command.

The distribution conditions of ZapCMode are the same as those for Zap, with
one exception; you do not need my permission to copy ZapCMode if you have
Dominic Symes' permission to copy Zap.  Thus, ZapCMode is freeware and those
wishing to distribute it on a cover disk need only contact Dom for
permission.


Installation
============

1. Check your version of Zap is >= 0.91 (in the Info box).
2. Copy the ZapCMode module into the !Zap directory.
3. Add the line
    RMLoad <Zap$Dir>.ZapCMode
   after the line
       RMLoad <Zap$Dir>.ZapBasic
   in the !Zap.!Run file, if it is not already present.
4. Restart your copy of Zap.


The menu
========

The mode adds the following menu on the Zap Mode menu.

....    +----------+
CMode =>| Pause  =>|
....    | Indent =>|
    | Match  =>|
    | C        |
    | Tex      |
    | Gofer    |
    +----------+

The pause option sets the delay in centiseconds when the cursor is moved back
to the open bracket after a close bracket is typed.  The field can be set to
any value between 0 and 255 inclusive.

The indent option sets the relative indent of lines following an open brace
('{').  The field can be set to any value between 0 and 31 inclusive.  The
indent is relative to the start of the line containing the open brace, and
consists of space characters.  Setting to 0 gives the same indent as
AutoIndent on the lines following open braces.

The Match menu controls which 'bracket' characters are matched.

    +-------+
    |  { }  |
    |  [ ]  |
    |  ( )  |
    |  ` '  |
    |  " "  |
    |  $ $  |
    | $$ $$ |
    |  ` `  |
    +-------+

The three sets of brackets are generally useful, as are the double quotes.
The single quotes, and dollar patterns are useful for TeX, while the
backquote is used in Gofer for turning functions into infix operators.

The remaining three options on the main menu select commonly used sets
of options for the Match menu.

The keyboard
============

To enter CMode from the keyboard, with the default keymap, use scF8. In this
version, the function browser is invoked using SAVEANDRUN, bound to scE in
the standard keymap.  The bounce function is bound to BASIC, which is scB.
The next/previous function commands are on RUNANDQUIT and RUN respectively,
normally scF and scU. The function lister is bound to scH as in BASIC mode.
The compile entry point is on scC.

Overloadings of the basic mode entry points may be removed in later versions;
they are no longer necessary given the keymaps of Zap 0.91 and later.


The commands
============

Some of these keys are also available via other entry points and so are
bound in the standard keymap to the indicated keys.

C_LIST_FUNCTIONS                (SAVEANDRUN, scE)

Pops up a function browser on the current buffer.  As usual with throwback
buffers, double click will jump to the corresponding location in the original
buffer.  The throwback buffer will not be displayed if no functions can be
found.

C_PREV_FUNCTION                    (RUN, scU)
C_NEXT_FUNCTION                    (RUNANDQUIT, scF)

These step to the next function definition in the appropriate direction.

C_COMPILE                    (COMPILE, scC)

Looks up one directory for a Makefile, and does a DataOpen broadcast if
it finds one; this is only successful if !Make is already loaded.

C_BOUNCE                    (BASIC, scB)

This bounces back to the open corresponding to the close character under
the cursor.

C_SET_PAUSE n
C_SET_INDENT n

These set the pause delay and indent step (the writable menu items)
to the corresponding value.

C_MODE
TEX_MODE
GOFER_MODE

Switch the buffer to CMode, and set the match flags appropriately.


Bugs and suggestions
====================

First, the standard disclaimer:

This program is provided "as is", without any warranty of any kind. The
entire risk as to its quality and performance is with you.  In no event will
I be liable for damages arising from the use of this program.

Having said that, CMode has been under test (in various versions) for several
months and is coded fairly defensively.  If you manage to find any bugs,
especially serious ones, then contact me as soon as possible and I'll try
to fix it.

Similarly, suggestions are welcome, although many of the usual requests are
not possible with the current version of Zap without insane amounts of work.

I can be contacted as

    [e-mail]

or by post as

    Bryan Scattergood
    The Queens College
    Oxford
    OX1 4AW

both addresses being good until September 1994.  After then, post sent to the
above address should reach me eventually.

Acknowledgements
================

Thanks must obviously go to Dominic Symes, firstly for creating Zap and
secondly for answering my (numerous) questions about writing extension modes.
Thanks must also go to the many members of the Oxford Arc User Group who
pushed this from being a prototype supporting only C, to a configurable
stable product supporting C, TeX and Gofer.  Their efficiency at finding
some of the more subtle bugs was especially valuable.

This version of CMode incorporates some ideas first implemented by Martin
Ebourne in his CMode, which in turn used code from CMode 0.03.  In doing
so it fixes some bugs in the function browser code.


Version history
===============

0.01
0.02

Early prototype versions for testing by the Oxford Arc User Group.

0.03

Simple version matching {}, () and [] unconditionally.  Released with Zap
0.90 by Dominic Symes.

0.04

Added simple $..$ matching for Dom.

0.05

Add quote matching and $$..$$, together with Match menu item to
allow for configuration for different languages.

0.06

Cleaned up sources, creating a separate library to share with other modes,
and changed to use w_tabc rather than wiring in character 9.

0.07

Added bounce command as BASIC, (so on scB).

0.08

Added code to remove delay on bounce when the user types ahead.

0.09

Added accelerators for commonly used Match combinations; TeX, C and Gofer.

0.10

Added function searching and browsing, together with incomplete command
interface.

0.11

Allow tabs and spaces after the open brace when indenting on a return.
Use Zap_BaseMode, rather than Zap_CallBaseMode.
Moved C_LIST_FUNCTIONS onto e_listfns vector.
Fixed glitch in function browser (scanner now handles '{' properly).
Fixed the bounce bug introduced in 0.08; the delay for the display when
bouncing was essentially random, and usually very small.

0.12 (Released with Zap 1.0)

Fixed mistake with function browser when no functions present; tried to clear
modify bit without checking whether throwback buffer had been generated.

0.13 (Not released; checkpoint version before 0.14)

Modified recogniser to make the code more K&R friendly; essentially allow
semicolon between the closing parenthesis and opening brace of a potential
function body provided (a) there was some non white-space before and it
and (b) there was only white space after it.

0.14

Changed the recogniser still further so that preprocessor directives are
skipped (and so correspond to whitespace).  This allows the idiom below,
which is fairly common in code which must support both K&R and ANSI C
compilers.

    #ifdef __ANSI__
    void foo(int x)
    #else
    void foo(x)
    int x;
    #endif /* <- this is now skipped */
    {
      /* Wibble */
    }

This also means that macro definitions involving blocks are no longer
recognised as well, so that

    #define swap(x, y) { int t = x; x = y; y = t; }

is no longer considered a function definition (it was previously).

0.15

(Alex) Character literals and strings are no longer scanned within comments.
This prevents a comment like /* This " comment */ from losing all the
subsequent functions in the file.

0.16

Add a beep when the function browser fails to find any functions as feedback
that the button was pressed.

0.17

Add a minimal compile command; it simply broadcasts a DataOpen on the
Makefile, if it exists.

0.18

Revise source code layout in library area, and modify library loading
to match.  No functional changes.

0.19    Development version

Augmented the compile command to scan for ZapCompile:, and added ZapInitial:
processing.  Added the *_MODE commands for use with Initial:.

0.20

Removed the ZapInitial and ZapCompile prototypes: abandon initial as too
vulnerable to attack by Trojans, and ZapCompile needs much more work.