Initial revision

[ssr] / StraySrc / Libraries / Sapphire / sail / SAILInfo

                               The SAIL System
                               ~~~~~~~~~~~~~~~

The name
~~~~~~~~

	SAIL stands for Straylight Application Interface Language.  It's
	Another Straylight Contrived Acronym (ASCA).

The Concept
~~~~~~~~~~~

	To allow a nice script language in major Sapphire application.  In
	particualr is allows access to most of sapphire, making extensible
	applications easy and powerful.

SAIL API
~~~~~~~~

Requirements

	Intialisation routine, done through normal Sapphire architecture

Environments

	A SAIL environment contains the following sorts of information:

	  * A parent environment, from which this one inherits.  There is a
	    default environment provided by SAIL which interfaces to
	    important bits of Sapphire.

	  * The names and code for any CALLs which the environment supports.
	    We must ensure that we allow extension DLLs to add their own
	    CALLs into this structure somehow.

	sail_createEnvironment

	On entry:	R0 == parent environment handle, or 0
			R1 == address of CALL table

	On exit:	R0 == environment handle
			May return an error

	Use:		Creates an environment

	CALL table format

	string		name of this CALL
	align
	word		address to call
	...
	word		0

	sail_addCalls

	On entry:	R0 == environment handle
			R1 == address of new call table

	On exit:	May return an error (but probably not)

	Use:		Adds an extra CALL table to an environment.  Useful
			for extension DLLs.

Initialising a script

	Initialisation of a script requires the following information:

	  * An environment to attach the script to.

	  * A global variable pool which it can play with.

	  * How often to pre-empt the script while it's running.

	  * A flex block/filename containing the text.

	After all the excitement of building data structures and tokenising
	the script, you end up with a script handle.


	sail_initScript

	On entry:	R0 == flex block handle of file
			R1 == environment handle to attach script to
			R2 == flex anchor of global variable pool
			R3 == how often to pre-empt the script (-1 == don't)

	On exit:	R0 == script handle

	Use:		Tokenises the script, set up global labels etc.


	sail_killScript

	On entry:	R0 == handle of the script

	On exit:	--

	Use:		Removes all the information associates with a given
			script.

Running a script

	Given a script handle, we can start executing by:

	  * running a particular procedure

	  * starting from a line number

	  * evaluating an expression in the script's context

	  * where it is at the moment (if it was pre-empted)


	sail_goto

	On entry:	R0 == handle of the script
			R1 == name of label (may contain really strange
			  chars), or 0 for start

	On exit:	R1 == 0 if finished, else more to go

	Use:		Starts executing the script from the given label.

	sail_contine

	On entry:	R0 == handle of the script

	On exit:	R1 == 0 if finished, else more to go

	Use:		Executes the script from its current position.  This
			is used for scripts which can be pre-empted.

	sail_eval

	On entry:	R0 == handle of the script
			R1 == pointer to string to evaluate

	On exit:	R1 == 0 if finished, else more to go

	Use:		Evaluates the given string.

	sail_proc

	On entry:	R0 == handle of the script
			R1 == pointer to parameter block

	On exit:	R1 == 0 if finished, else more to go

	Use:		Calls the given procedure by binding to arguments
			in the block to the formal arguments of the
			procedure definition.

	The block looks like this:

	Word		Variable type
	Data		Variable data
	...
	-1


Variable handling
~~~~~~~~~~~~~~~~~

Global variables

	Access to the global variable pool is done via the `@' symbol.  All
	label, procedure, function and variable names may be preficed by an
	@, in which case the varible is looked up in the global pool.


Useful routines


	sail_createPool

	On entry:	--

	On exit:	R0 == handle of an empty variable pool
			May return an error

	Use:		Creates a variable pool, so you can attach it as a
			global variable pool to a script.

	sail_findVar

	On entry:	R0 == script handle
			R1 == name of variable
			R2 == type of variable to find

	On exit:	CS if variable found, and
			  R1,R2 == lvalue of the variable
			else CC

	sail_createVar

	On entry:	R0 == script handle
			R1 == name of variable
			R2 == type of variable to create

	On exit:	R1,R2 == lvalue of variable


	sail_load

	On entry:	R0 == script handle
			R1,R2 == lvalue of variable

	On exit:	R3,R4 == rvalue of variable


	sail_store

	On entry:	R0 == script handle
			R1,R2 == lvalue of variable
			R3,R4 == new rvalue to write

	On exit:	--

	Note that we use appropriate floating point registers (i.e. F1
	instead of R1 etc.) if the variables have floating point values.

Important CALLs to have available
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Sail_Expand
	Sail_CallAddress


Example button code
~~~~~~~~~~~~~~~~~~~

	CALL "Dbox_Create","myTemplate" TO myDbox%
	CALL "Dbox_EventHandler",myDbox%,"myDboxHandler"
	CALL "Dbox_Open",myDbox%
	END

	DEF PROCmyDboxHandler(reason%,args%)
	CASE reason% OF
	  WHEN 4
	    CALL "Sail_Expand",args% TO ,buttons%
	    CALL "Dbox_Slab",4
	    ...
	    CALL "Dbox_Unslab"
	  ...
	ENDCASE
	ENDPROC


The transmogrification of TermScript (nah!) into SAIL (whuppeeee!)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Use flex memory management
	Allow for floatinng point variables
	Add SAIL API
	Do new global variable handling
	No more RAM grabbing (use alloc)
	Removal of Termite specific commands
	New CALL syntax (slightly)
	Enviroment handing
	Error handling