chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/sail/SAILInfo

   1
   2                                The SAIL System
   3                                ~~~~~~~~~~~~~~~
   4
   5 The name
   6 ~~~~~~~~
   7
   8         SAIL stands for Straylight Application Interface Language.  It's
   9         Another Straylight Contrived Acronym (ASCA).
  10
  11 The Concept
  12 ~~~~~~~~~~~
  13
  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.
  17
  18 SAIL API
  19 ~~~~~~~~
  20
  21 Requirements
  22
  23         Intialisation routine, done through normal Sapphire architecture
  24
  25 Environments
  26
  27         A SAIL environment contains the following sorts of information:
  28
  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.
  32
  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.
  36
  37         sail_createEnvironment
  38
  39         On entry:       R0 == parent environment handle, or 0
  40                         R1 == address of CALL table
  41
  42         On exit:        R0 == environment handle
  43                         May return an error
  44
  45         Use:            Creates an environment
  46
  47         CALL table format
  48
  49         string          name of this CALL
  50         align
  51         word            address to call
  52         ...
  53         word            0
  54
  55         sail_addCalls
  56
  57         On entry:       R0 == environment handle
  58                         R1 == address of new call table
  59
  60         On exit:        May return an error (but probably not)
  61
  62         Use:            Adds an extra CALL table to an environment.  Useful
  63                         for extension DLLs.
  64
  65 Initialising a script
  66
  67         Initialisation of a script requires the following information:
  68
  69           * An environment to attach the script to.
  70
  71           * A global variable pool which it can play with.
  72
  73           * How often to pre-empt the script while it's running.
  74
  75           * A flex block/filename containing the text.
  76
  77         After all the excitement of building data structures and tokenising
  78         the script, you end up with a script handle.
  79
  80
  81         sail_initScript
  82
  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)
  87
  88         On exit:        R0 == script handle
  89
  90         Use:            Tokenises the script, set up global labels etc.
  91
  92
  93         sail_killScript
  94
  95         On entry:       R0 == handle of the script
  96
  97         On exit:        --
  98
  99         Use:            Removes all the information associates with a given
 100                         script.
 101
 102 Running a script
 103
 104         Given a script handle, we can start executing by:
 105
 106           * running a particular procedure
 107
 108           * starting from a line number
 109
 110           * evaluating an expression in the script's context
 111
 112           * where it is at the moment (if it was pre-empted)
 113
 114
 115         sail_goto
 116
 117         On entry:       R0 == handle of the script
 118                         R1 == name of label (may contain really strange
 119                           chars), or 0 for start
 120
 121         On exit:        R1 == 0 if finished, else more to go
 122
 123         Use:            Starts executing the script from the given label.
 124
 125         sail_contine
 126
 127         On entry:       R0 == handle of the script
 128
 129         On exit:        R1 == 0 if finished, else more to go
 130
 131         Use:            Executes the script from its current position.  This
 132                         is used for scripts which can be pre-empted.
 133
 134         sail_eval
 135
 136         On entry:       R0 == handle of the script
 137                         R1 == pointer to string to evaluate
 138
 139         On exit:        R1 == 0 if finished, else more to go
 140
 141         Use:            Evaluates the given string.
 142
 143         sail_proc
 144
 145         On entry:       R0 == handle of the script
 146                         R1 == pointer to parameter block
 147
 148         On exit:        R1 == 0 if finished, else more to go
 149
 150         Use:            Calls the given procedure by binding to arguments
 151                         in the block to the formal arguments of the
 152                         procedure definition.
 153
 154         The block looks like this:
 155
 156         Word            Variable type
 157         Data            Variable data
 158         ...
 159         -1
 160
 161
 162 Variable handling
 163 ~~~~~~~~~~~~~~~~~
 164
 165 Global variables
 166
 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.
 170
 171
 172 Useful routines
 173
 174
 175         sail_createPool
 176
 177         On entry:       --
 178
 179         On exit:        R0 == handle of an empty variable pool
 180                         May return an error
 181
 182         Use:            Creates a variable pool, so you can attach it as a
 183                         global variable pool to a script.
 184
 185         sail_findVar
 186
 187         On entry:       R0 == script handle
 188                         R1 == name of variable
 189                         R2 == type of variable to find
 190
 191         On exit:        CS if variable found, and
 192                           R1,R2 == lvalue of the variable
 193                         else CC
 194
 195         sail_createVar
 196
 197         On entry:       R0 == script handle
 198                         R1 == name of variable
 199                         R2 == type of variable to create
 200
 201         On exit:        R1,R2 == lvalue of variable
 202
 203
 204         sail_load
 205
 206         On entry:       R0 == script handle
 207                         R1,R2 == lvalue of variable
 208
 209         On exit:        R3,R4 == rvalue of variable
 210
 211
 212         sail_store
 213
 214         On entry:       R0 == script handle
 215                         R1,R2 == lvalue of variable
 216                         R3,R4 == new rvalue to write
 217
 218         On exit:        --
 219
 220         Note that we use appropriate floating point registers (i.e. F1
 221         instead of R1 etc.) if the variables have floating point values.
 222
 223 Important CALLs to have available
 224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 225
 226         Sail_Expand
 227         Sail_CallAddress
 228
 229
 230 Example button code
 231 ~~~~~~~~~~~~~~~~~~~
 232
 233         CALL "Dbox_Create","myTemplate" TO myDbox%
 234         CALL "Dbox_EventHandler",myDbox%,"myDboxHandler"
 235         CALL "Dbox_Open",myDbox%
 236         END
 237
 238         DEF PROCmyDboxHandler(reason%,args%)
 239         CASE reason% OF
 240           WHEN 4
 241             CALL "Sail_Expand",args% TO ,buttons%
 242             CALL "Dbox_Slab",4
 243             ...
 244             CALL "Dbox_Unslab"
 245           ...
 246         ENDCASE
 247         ENDPROC
 248
 249
 250 The transmogrification of TermScript (nah!) into SAIL (whuppeeee!)
 251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 252
 253         Use flex memory management
 254         Allow for floatinng point variables
 255         Add SAIL API
 256         Do new global variable handling
 257         No more RAM grabbing (use alloc)
 258         Removal of Termite specific commands
 259         New CALL syntax (slightly)
 260         Enviroment handing
 261         Error handling