The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/z/zapupdates/Wagenaar/DWExtHelp

Text File | 1995-11-07 | 8KB | 183 lines

ZapDWExt - an extension to Zap, (c) 1994,1995 Daniel Wagenaar
This text describes version 1.15

ZapDWExt does not provide any new modes.

ZapDWExt provides one *command: *Zap_Command. This command takes a filename
and a colon-separated list of Zap commands for arguments. The file will be
opened if necessary, the cursor will jump into it, and the commands will be
executed.

It supports the following Zap commands:

BLOCKID        Blocks the identifier under the cursor. An
        identifier is as defined by ANSI C, ie it starts with
        a letter, and may contain numbers, letters, and the
        underscore.

FIRSTBLOCK    Finds the first occurence in the file of the marked
        block.

DEFBLOCK    Finds ‘.<block>’ or ‘DEF<block>’ for BASIC or
        ‘<block>(’ for C.

FINDBLOCK    Open a throwback window containing all occurences of the
        marked block.

FINDID        First do BLOCKID, then, if the mode is Basic, or the
        mode is C and the first char after the block is '(',
        do DEFBLOCK, else do FIRSTBLOCK. In this way, function
        definitions may be found, and the first occurence of a
        variable may be found in C mode.

BLOCKSTAR    Do ‘*TaskWindow "<block>" -quit’, where <block> is the
        selected area.

STARCOM        Does ‘*TaskWindow "<arg>" -quit’. <arg> may be
        included in the Keys file, or typed in a mini-buffer.

CC        Compiles a C program using ‘STARCOM "cc <filename>"’.
        It opens a minibuffer in which the command line
        options may be specified. The default options are read
        from and written to the system variable Zap$CCOptions.
        As explained below, a default value may be assigned in
        Zap's !Run file. A sensible default could be:
        ‘-IC: -throwback -Lc:o.stubs,c:o.risc_oslib -Desktop ^’

MAKE        Makes a project using ‘STARCOM "prefix <dirname> |M amu -f
        <leafname>"’. Additional command line options may be
        specified via the minibuffer. Default options are read
        from and written to the system variable Zap$AmuOptions.

ANYCOMPILE    Does ‘MAKE’ or ‘CC’, whichever is appropriate: for project
        files do MAKE; for C files do CC, unless the string
        'Makefile: <name> [<target>]' occurs near the start of the
        text. In that case, MAKE is done, but no options are asked.
        If a line of the form:
          xxx +-+ <command> +-+ xxx
        or:
          xxx +-+ <command>
        is found, then the command is executed instead of any
        default action. In the command, the sequences %f, %l, %d
        may be used to represent, respectively, the full filename,
        the leafname, or the parent directory name of the file.
        Example:
         /* +-+ cc -IC: -Lc:o.stubs -throwback -Desktop ^ %f +-+ */

OPENMAKE    Opens the makefile for this project, if the string
        ‘Makefile: <name>’ is included in the start of the
        file.

OPENREF        Opens a file referenced at the cursor, eg for
        #include <fff.h>. Note that OPENREF takes care of
        path element inversion, as in ‘fff.h’ => ‘h.fff’.

OPENCH        If the current file is named ‘...h.yyy’, opens
        ‘...c.yyy’ and vice versa

OPENOTHER    Does either OPENREF, OPENMAKE or OPENCH, whichever is
        most appropriate. OPENOTHER uses the path ‘ZapDWS:’ to
        complete filenames. For example, if a reference is made
        to ‘stdio.h’, then OPENOTHER/OPENREF will try to open
        ‘ZapDWS:h.stdio’. (As always, element inversion is taken
        care of.) To make this system work, a line defining
        ZapDWS$Path must be included in Zap's !Run file. See
        below.

CLOSETBTW    Closes all throwback and task windows.

MODBRK        Sets a breakpoint in a module, at the cursor address.
        The module must be loaded into Zap using

          Create.Get module.<modname>

        and the filename must have remained unchanged. You must
        be careful when using this command, because the computer
        may crash if you set a breakpoint in a piece of code that
        is used in IRQ mode. So: don't set breakpoints in the
        UtilityModule unless you know what your doing :-)
        In fact, MODBRK only works if the module in question
        is in RMA. For ROM-based modules, you'd have to do a
        *RMFaster before using MODBRK. This command is mainly
        intended to be of use while debugging.

LINEEND        Replaces all occurences of CRLF, CR, LF, LFCR by the
        correct return character (as set in the ‘Display->
        Misc->Return char->’ submenu). This is particularly
        useful when you've copied a text file from an MS-DOS
        system, which uses CRLF instead of plain LF.

CRLF        Exchanges CR <-> LF (Carriage returns with linefeeds).
        This can be used to convert Mac style texts to Risc OS
        style texts, or to convert spooled output (with LFCR)
        to 'DOS style' text (CRLF) which can be converted to
        ordinary Risc OS style texts by dragging them to the
        Zap icon. This command has been written to replace
        LINEEND where possible. It is *much* faster. CRLF can
        not be undone using the UNDO command. It's action is
        reversed by executing it again.

SETNAME        Sets the name of a file from an in-core filename.

REVERT        Reloads the current file from disc. This can be used in
        two occasions: firstly if you have accidentally currupted
        your work and don't feel like pressing ‘Full undo’ a
        million times. Secondly if an external program (such as
        amu) has changed your file and you want to edit the
        new version.

GOTOLINE    Alternative for F5 (GOTO), using the minibuffer. Thus it can
        be used through *Zap_Command. The (string) argument is either
        a logical line number, or 'P' followed by a physical line
        number. Example in Basic:
        ON ERROR OSCLI "Zap_Command this.file GOTOLINE "+STR$ERL:END
        Also very useful for TeX users who don't have throwback at
        their disposal.
        If the argument is ‘!’ or the empty string, the system
        variable ‘DWExt$LineNo’ is substituted.

GOTOADDR    As GOTOLINE, but goes to an address. If the command opens a
        minibuffer, an hexadecimal sign ('&') is typed in for you.
        No system variable substitution is performed.

In addition to the Zap commands, there is a single *-command: *Zap_Command.
This may be used to call Zap commands from an external task. Its syntax is:
*Zap_Command <filename> <commands>. The file is loaded if it isn't already
in memory. There may be more than one command, separated by colons as in the
‘Keys’ file. See the example under GOTOLINE.
Note that this command is currently in beta-release. It doesn't seem to do
terrible things, but sometimes the display update isn't very nice,
particularly when called from a task window.

I hope these commands may be of use to other people.
As I distribute ZapDWExt free of charge, I cannot take any
responsibility for any damage caused by using or the inability to use
it. In particular, I don't give any guarantee that it will leave your
texts intact. That said, I believe I've tested it rather thoroughly,
and to my knowledge, it is bug-free. There may be features, though :-)
If you do encounter any bugs, or unexpected behaviour, or if you have
any comments, please contact me:

        Daniel Wagenaar
snail:  Van Eeghenlaan 10
        1071 EL  Amsterdam
        The Netherlands
tel.:   [phone]
e-mail: [e-mail]

Any feedback is highly welcome!

Finally...

ZapDWExt will only run under Risc OS 3, mainly because Risc OS 2 can't
complete pathnames. If anybody urgently wants to run ZapDWExt under
Risc OS 2, then I hope someone will have a replacement for OS_FSControl
with r0=37, or else I may have to write something...

I agree that the documentation for ZapDWExt is rather terse. This is
because it originally served only as a post-it note to myself, to
enable me to remember the commands... Feel free to flame me about this
attitude. On popular demand I'll write more extensive docs. Also, if
you feel these commands lack universality, and have an idea to improve
them, I'd be delighted...