8 SAIL stands for Straylight Application Interface Language. It's
9 Another Straylight Contrived Acronym (ASCA).
14 To allow a nice script language in major Sapphire application. In
15 particualr is allows access to most of sapphire, making extensible
16 applications easy and powerful.
23 Intialisation routine, done through normal Sapphire architecture
27 A SAIL environment contains the following sorts of information:
29 * A parent environment, from which this one inherits. There is a
30 default environment provided by SAIL which interfaces to
31 important bits of Sapphire.
33 * The names and code for any CALLs which the environment supports.
34 We must ensure that we allow extension DLLs to add their own
35 CALLs into this structure somehow.
37 sail_createEnvironment
39 On entry: R0 == parent environment handle, or 0
40 R1 == address of CALL table
42 On exit: R0 == environment handle
45 Use: Creates an environment
49 string name of this CALL
57 On entry: R0 == environment handle
58 R1 == address of new call table
60 On exit: May return an error (but probably not)
62 Use: Adds an extra CALL table to an environment. Useful
67 Initialisation of a script requires the following information:
69 * An environment to attach the script to.
71 * A global variable pool which it can play with.
73 * How often to pre-empt the script while it's running.
75 * A flex block/filename containing the text.
77 After all the excitement of building data structures and tokenising
78 the script, you end up with a script handle.
83 On entry: R0 == flex block handle of file
84 R1 == environment handle to attach script to
85 R2 == flex anchor of global variable pool
86 R3 == how often to pre-empt the script (-1 == don't)
88 On exit: R0 == script handle
90 Use: Tokenises the script, set up global labels etc.
95 On entry: R0 == handle of the script
99 Use: Removes all the information associates with a given
104 Given a script handle, we can start executing by:
106 * running a particular procedure
108 * starting from a line number
110 * evaluating an expression in the script's context
112 * where it is at the moment (if it was pre-empted)
117 On entry: R0 == handle of the script
118 R1 == name of label (may contain really strange
119 chars), or 0 for start
121 On exit: R1 == 0 if finished, else more to go
123 Use: Starts executing the script from the given label.
127 On entry: R0 == handle of the script
129 On exit: R1 == 0 if finished, else more to go
131 Use: Executes the script from its current position. This
132 is used for scripts which can be pre-empted.
136 On entry: R0 == handle of the script
137 R1 == pointer to string to evaluate
139 On exit: R1 == 0 if finished, else more to go
141 Use: Evaluates the given string.
145 On entry: R0 == handle of the script
146 R1 == pointer to parameter block
148 On exit: R1 == 0 if finished, else more to go
150 Use: Calls the given procedure by binding to arguments
151 in the block to the formal arguments of the
152 procedure definition.
154 The block looks like this:
167 Access to the global variable pool is done via the `@' symbol. All
168 label, procedure, function and variable names may be preficed by an
169 @, in which case the varible is looked up in the global pool.
179 On exit: R0 == handle of an empty variable pool
182 Use: Creates a variable pool, so you can attach it as a
183 global variable pool to a script.
187 On entry: R0 == script handle
188 R1 == name of variable
189 R2 == type of variable to find
191 On exit: CS if variable found, and
192 R1,R2 == lvalue of the variable
197 On entry: R0 == script handle
198 R1 == name of variable
199 R2 == type of variable to create
201 On exit: R1,R2 == lvalue of variable
206 On entry: R0 == script handle
207 R1,R2 == lvalue of variable
209 On exit: R3,R4 == rvalue of variable
214 On entry: R0 == script handle
215 R1,R2 == lvalue of variable
216 R3,R4 == new rvalue to write
220 Note that we use appropriate floating point registers (i.e. F1
221 instead of R1 etc.) if the variables have floating point values.
223 Important CALLs to have available
224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
233 CALL "Dbox_Create","myTemplate" TO myDbox%
234 CALL "Dbox_EventHandler",myDbox%,"myDboxHandler"
235 CALL "Dbox_Open",myDbox%
238 DEF PROCmyDboxHandler(reason%,args%)
241 CALL "Sail_Expand",args% TO ,buttons%
250 The transmogrification of TermScript (nah!) into SAIL (whuppeeee!)
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253 Use flex memory management
254 Allow for floatinng point variables
256 Do new global variable handling
257 No more RAM grabbing (use alloc)
258 Removal of Termite specific commands
259 New CALL syntax (slightly)