 ____          ____  ___
|_  /__ _ _ __|  _ \/ __|
 / // _` | '_ \ |_) \__ \ 0.30d, 30 September 1997
/___\__,_| .__/____/|___/  Darren Salt, 1996/7
         |_|

This software is COPYRIGHT, but has been released as FREEWARE. Please see the
end of this file for conditions of use and distribution.


Installation


Easy - just merge it with the existing !Zap. It replaces the ZapDS files in
!Zap.3rdParty.Salt (ZapDS, DS*); these should be deleted.

You will need to update Zap's External file if you're upgrading from v0.24 or
earlier - just run MakeExtern (supplied with Zap).

The file "HelpData" contains help text usable by Zap's HELP command - if you
merge it with !Zap.Docs.HelpData.


Commands


Commands without any specifed syntax take no parameters.

Any commands which take a string parameter will open the minibuffer if no
parameter is supplied.


DS_RunApp


Will save the file if changes have been made, then tries to run it as an
application (also sends the window to the back) - AFTER Shift & Ctrl are
released (if they were pressed). For example:
  File being edited  File actually run  Notes
  !Beep.!RunImage    !Beep.!Run		Runs !Beep.!RunImage if not found
  !Beep.Data.Make    !Beep.Data.Make
  Text.Build	     Text.Build


DS_Insert


Inserts a space at the cursor as in !Edit.
In byte mode, inserts a zero byte.
In word mode, inserts a zero word.
In code mode, inserts a DCD 0.


DS_Eval


Evaluates the supplied expression and inserts the signed result in the
supplied base at the cursor position. If the expression evaluates to a
string, the base (if supplied) is ignored.

Syntax: DS_Eval "<base>:<expression>"
    or: DS_Eval "<expression>"

For numeric expressions:

Valid base values are between 2 and 36. In the second form, the base defaults
to decimal.

  Examples:		C	BASIC	Others
	16:160*1024	0x28000	&28000	&28000
	640-16		624	624	624
	36:123456	36_2N9C	36_2N9C	36_2N9C
	2:27	 	0b11011	%11011	2_11011

Exceptions:

In byte mode, only the bottom byte of the result is used. For example, if
DS_EVAL "123" is executed then the byte &7B ('{') is inserted. The base is
ignored.

In word and code modes, the result is inserted as a hex word, much like DCD
in assembler, but reversed if the 'big endian' flag is set. The base is
ignored.

For these modes, or for string expressions, it does not matter whether you
use DS_Eval, DS_UEval or DS_EvalH since they will function identically.


DS_UEval


Like DS_Eval but the result is unsigned. Similar syntax.


DS_EvalH


Like DS_Eval but the result is always unsigned hexadecimal.

Syntax: DS_EvalH "<expression>"


DS_AdrL


Assembles a long (two instruction) ADR.

Syntax: DS_AdrL "[<condition code>] <register>,<address>"

Example:
	at address &1000, the command
		DS_AdrL "LT R1,&5344"
	is equivalent to
		Assemble "ADRLT R1,&1344"
		Assemble "ADDLT R1,R1,#&4000"
(It will of course use SUB if required.)


DS_AdrX


Assembles a very long (three instruction) ADR, much as DS_AdrL does - it even
has the same syntax.


DS_FindFile


Looks for an object name (file or directory) at the cursor. If a file name is
found, then it attempts to load the named file - if nothing appears to
happen, this is because the file is already loaded. If a directory name is
found, then it is opened using *Filer_OpenDir.

A name may not contain control codes, spaces, or one of " # * |. These, along
with start and end of file, are taken as the delimiting characters. For
example, executing DS_FindFile with the cursor somewhere in the middle of
*<Zap$Dir>.Fonts.* causes the directory <Zap$Dir>.Fonts to be opened. Note
that the trailing dot is ignored.

Slight cheat: even if nothing is found with the given name, Zap_FindFile is
called in order to expand the name to a full pathname and report an error.


DS_OpenParent


Opens the directory containing the current file - just like clicking
Shift-Adjust on the close icon!


DS_SwapCaseCursor


Swaps the case of the letter at the cursor, advancing the cursor by one
character - whether there is a selection or not.


DS_SaveKeepStamp


Saves the file immediately (ie. no prompt), but preserves the datestamp
regardless of whether the file has changed or not.

If the file does not have a complete pathname, it is not saved - you will
hear a beep instead.


DS_StripCtrlCodes


Strips all control codes (except for the current tab and return characters)
from a file, and removes everything from the first ctrl-Z onwards. These
effects are, of course, optional.

Syntax: DS_StripCtrlCodes <action>

The following values of 'action' are defined:

Bit 0 set: strip all control codes
Bit 1 set: strip all control codes except ctrl-G [bell], ctrl-H [backspace]
	   and ctrl-L [form feed]
bit 2 set: remove everything from the first ctrl-Z [soft-EOF]

The default parameter value is 5.

Other values are masked so that only the above values may occur.

If control code stripping is selected, then the 'DOS text file' and 'spool
file' flags are also cleared.

The cursor may be moved by this command: this one small feature not
implemented = vast speed improvement.

This command will not operate in byte, word, code or BASIC modes (it will
beep at you instead).


DS_Untabify


Converts tabs to spaces, whilst maintaining the formatting - thus reversing
the effects of StripSpaces 4.

In BASTXT, CMode, C, Pascal, and Assembler modes, tabs enclosed in double
quotes " are left intact.

The cursor may be moved by this command: this one small feature not
implemented = vast speed improvement.

This command will not operate in byte, word, code or BASIC modes (it will
beep at you instead).


DS_StripCtrlWithMask


Like DS_StripCtrlCodes, but much more flexible...

The command takes one parameter (evaluated via OS_EvaluateExpression - think
*Eval if you don't know that SWI), in which bit x (if set) causes all
occurrences of character code x to be removed from the file.

The default parameter, if 0 is supplied, is to strip all control codes except
\a (\7), \b (\8), \f (\12), and the current return and tab characters.

The cursor may be moved by this command: this one small feature not
implemented = vast speed improvement.

This command will not operate in byte, word, code or BASIC modes (it will
beep at you instead).

Syntax: DS_StripCtrlWithMask "<mask_word>"

For example, to strip ASCII codes 1, 2, 3, 6 and 21:
	DS_StripCtrlWithMask "2_00000000001000000000000001001110"
or	DS_StripCtrlWithMask "&0020004E"
or	DS_StripCtrlWithMask "1<<21 OR 1<<6 OR 1<<3 OR 1<<2 OR 1<<1"


DS_Add, DS_Sub, DS_Rsb, DS_And, DS_Or, DS_Eor
          

These commands perform an arithmetic or logic operation on the current byte
(or word, if in word or code mode). Each takes a string parameter, evaluating
to a number. (Even if the byte/word is unchanged, the cursor is moved on.)

For example, to add &180 to a word (in word mode), you'd use
	DS_Add "&180"


DS_SWItoName


This takes an SWI number, found at the cursor position, and replaces it with
the corresponding name. In BASIC and BASTXT modes, quotation marks are
automatically inserted.


DS_SWItoNumber


This takes an SWI name, found at the cursor position, and replaces it with
the corresponding number. In BASIC and BASTXT modes, surrounding quotation
marks are automatically removed.


DS_ToIcon


Allows you to copy the selection to a writable icon, stopping at the first
control character. All you need to do is to click Select (or Adjust, which
causes a ^U to be typed first) where you want the text to be inserted, or
Menu to cancel.


DS_CloseFile


This command name is deprecated: use CloseFile instead.


If, And_If, Or_If, Eor_If
      

The supplied string parameter is checked against whatever is at the cursor,
and a boolean result is returned. The first character of the string
determines the comparison type; if the second is ^ then the result is
inverted.

C - Check character at cursor
	Control characters are represented using the GSTrans "|" format
	Ranges may be specified, eg. for all upper case: A-Z
	If "-" is to be checked for, it should be either the first character
	  (other than "^") or should be prefixed by "|"
	IF "C" will check for end of file; IF "C^" will check for NOT EOF

P - Check character to left of cursor
	Exactly as for 'C', except that:
	IF "P" will check for start of file; IF "P^" will check for NOT SOF

W - Check word at cursor
	Requires a list of words. The 'big endian' flag is used.
	For example:
		IF "W&20"		word=&20
		IF "W&20*&FF"		(word AND &FF)=(&20 AND &FF)
		IF "W1234,-5678"	word=1234 OR word=-5678
		IF "W^&4AF80"		word<>&4AF80
		IF "W^0,-1"		word<>&4AF80 AND word<>-1

M - Check mode
	Requires a mode string of the format <name>[,<name>]*
	For example:
		IF "MText,C,Assembler"
		IF "M^Basic"		(note that case doesn't matter)

IFs may be nested within IF_TRUE and IF_FALSE.


If_TRUE and If_FALSE
     

These both rely on the last IF command, and execute the given command string
depending on its result.

IFs may be nested, with the current IF status being preserved. This allows
you to say
	IF "C "
	IF_TRUE "IF ""P "":IF_TRUE ""LEFT"""
	IF_TRUE "IF ""P|I"":IF_TRUE ""RIGHT"""

It's also possible to suppress the preservation of the IF status by prefixing
the command string with "^".

Format_Indented


This command formats the current paragraph, using the supplied string as the
indent. The paragraph *must already* be indented using this string.

You can specify the tab character using '\t' or '\T'; to specify \, use '\\'.
If \ is followed by any other character, then that character is treated
normally.

If you specify "\<" as the indent string, then whatever's to the left of the
cursor on the current line is used. (If you want to use "\<" *as* the indent
string, specify "\\<" instead.)

For example:
	Format_Indented " * "		format a C comment
	Format_Indented "// "		format a C++ comment
	Format_Indented "\t"		format TAB-indented text
	Format_Indented ""		equivalent to FORMATTEXT

(This code is based on the formatting code in ZapEmail, and has similar
advantages over the standard formatting code in Zap 1.35.)

(A future version will allow use of the indent string on the *following*
logical line. This is intended to get round bullet point problems.)

CloseFile


Closes all views on a file, and removes that file from memory. You are
prompted first, though, if the file is modified.


CloseAll, DiscardAll, SaveAll, SaveAndCloseAll, SaveAndDiscardAll
        

Save		saves all modified files.
Close		removes unmodified files.
Discard		removes all files, modified or not. Be careful!

If saving, those files without full pathnames are not saved, and thus remain
marked as modified; they may therefore be discarded but not closed.

"Remove" is used in the same sense as on Zap's iconbar menu; no questions are
asked about unmodified files.

If, when attempting to save a file, an error occurs or Zap displays a query,
then the command will terminate early and not attempt to save other files.
You should attempt to resolve the problem (eg. click on "Overwrite") and try
again.

(Based on code provided by James Aylett)


SendURL


This command will look for something URL-like at the cursor position, and
will try to send it to any currently-loaded web browser.

ZapDS recognises URLs of the form "#{protocol}{address}#" or
"#URL:{protocol}{address}#". Recognised {protocol} types are:
	finger://	http://		news:		telnet://
	ftp://		https://	nntp:		tn3270://
	gopher://	mailto:		rlogin://
Minimal checking is performed on the {address}; however, email addresses
should contain one '@' else they'll not be coloured. mailto: is coloured
differently, and may be omitted if "URL:" is also. The "URL:" prefix is case
sensitive. '#' may be TAB, LF, space, '"', '<', or '>'.

For example, these will be recognised and sent:

ftp://ftp.demon.co.uk/pub/acorn/
"http://www.dsse.ecs.soton.ac.uk/"
<mailto:arcsalt@spuddy.mew.co.uk>
<URL:http://www.spuddy.org/>
darren.salt@unn.ac.uk

The last example would be automatically prefixed with "mailto:".

(Tested with ArcWeb and Messenger; should also work with InterTalk, Termite
and Fresco, possibly also Voyager. Uses message &4AF80.)


SendURLGivenOffset


This command is intended for use by Zap modes to implement the sending of
URLs via mouse clicks, taking a file offset as a parameter and using this
instead of the cursor position. It is otherwise equivalent to SendURL.

Suitable code for calling this command may be found in the source for
ZapEmail (.mode_click).


DosTextFile and SpoolFile
	

Both commands have been deleted at the suggestion of Chris Manning
(chrism@spuddy.mew.co.uk)
For DosTextFile or FFlags_Toggle &1B, use FFlags_Toggle &DD1B
For SpoolFile	or FFlags_Toggle &1D, use FFlags_Toggle &DB1D


DS_MessageID


Removed; use Email_Stamp instead.


Copyright


The conditions of copying this program and its associated documentation are
the same as those of the main Zap application, except you do not need my
permission to copy it if you have Dominic Symes's.

This software is provided as is with no warranty as to its suitability or
otherwise for any particular task. If it does anything nasty then I want to
know so I can fix it, but I'm not taking any responsibility. (Besides,
there's no point in sueing me since I've got next to no money.)

Please note that I reserve the right to make alterations to this program, its
operation, documentation, and/or conditions of use without notice in any way
I see fit. Hopefully it will be an improvement.


Contact


Darren Salt - arcsalt@spuddy.mew.co.uk
