                          Rabbit Programmer's Manual
                          ==========================

This document ist intended for authors of Rabbit scripts, if you are a "normal"
user, please read the files in Docs.User instead.


*** Programmer documentation is (very) incomplete, if anyone would like ***
*** to volunteer to write some of it, please contact me at one of the   ***
*** addresses in Docs.User.Guide.                                       ***

In the meantime I have provided the source code for all the scripts included
with Rabbit, hopefully they will be of some help with things not documented
here. Should you have any qustions about writing a script, please do not
hesitate to contact me.

Introduction
------------
Rabbit is a generic internet application designed to be used for a multitude of
purposes. Specific applications are handled by scripts. The relationship between
a script and Rabbit is similar to that between the WIMP and a task.


Terminology
-----------
- Rabbit refers to the application !Rabbit.
- RabbitScript refers to the language in which scripts for Rabbit are written.
- A Rabbit script (or simply a script) refers to a program written in
  RabbitScript to be run by Rabbit.


Technical details
-----------------
RabbitScript is a programming language with a syntax similar to C, but far
more basic in nature. For a detailed description of syntax see
Docs.Programmer.Syntax (which has barely been written yet, sorry). The rest of
this document assumes familiarity with RabbitScript's syntax.

RabbitScript is a compiled language, however it compiles to an internal
word-based code rather than ARM code. Scripts are compiled using the supplied
script compiler located in Rabbit's application directory, the command line
syntax is:

  <Rabbit$Dir>.Script <source file> <destination file>

Rabbit must have been seen by the filer for this to work.

Communication between rabbit and scripts is provided by specifically named
(non-local) functions called by Rabbit on the one hand and functions provided
by Rabbit for scripts to call on the other. for clarity from here on funtions
provided by Rabbit will be called "commands" and script functions called by
Rabbit are called "entry points". Docs.Interfaces contains detailed
descriptions of commands and entry points for each of Rabbit's script
interfaces.

RabbitScript provides direct access to Risc OS SWIs simialar to the way BBC
BASIC does, however Rabbit allows the user to restrict or prohibit scripts'
access to SWIs for security reasons.


Resource Interfaces
-------------------
  Rabbit provides scripts with interfaces to a number of system resources such
as sockets, files and displays. Most scripts will only need a small number of
these. Details of all interfaces can be found in the files contained in
Docs.Interfaces. The following is a list of interfaces along with brief
descriptions:

   Admin       - Administration issues between Rabbit and scripts, all scripts
                 require this to some degree.
   cpicker     - Access to the Risc OS colour picker.
   Display     - Scrolling text displays.
     Panes     - Panes attached to displays.
     Icons     - Icons contained in such panes.
   DNS         - Conversions between internet hostnames and IP addresses.
   Files       - Access to files.
   IconBar     - Placing icons on the icon bar.
   memblock    - Allocation of blocks of memory.
   Menu        - Using Risc OS menus.
   Misc        - Miscelaneous commands for things like conversions and text
                 manipulation.
   Sockets     - Access to TCP/IP sockets.
   Sprites     - Management of te script's private sprite area.
   Tasks       - Management of script tasks.
   WimpEvents  - Access to certain WIMP events received by Rabbit.

  NOTE: Some of the above files are incomplete and contain only brief listings
of commands and entry points.

  Script authors need only read those files relevant to their scripts, however
some details are shared by many interfaces:

  Unless stated otherwise whenever a call to claim a resource returns a handle
it will always be positive or zero unless the claim was unsuccessful, in which
case it will be negative (usually -1, although that should not be relied on).

  Unless stated otherwise colours are always specifed as ColourTrans palette
entries, i.e. 32 bit integers of the form 0xBBGGRRxx.
