chiark - git - mdw - ssr/blob - StraySrc/Libraries/Sapphire/sh/choices/options

   1 ;
   2 ; choices.options.sh
   3 ;
   4 ; Read options from an options chunk
   5 ;
   6 ; © 1995-1998 Straylight
   7 ;
   8
   9 ;----- Licensing note -------------------------------------------------------
  10 ;
  11 ; This file is part of Straylight's Sapphire library.
  12 ;
  13 ; Sapphire is free software; you can redistribute it and/or modify
  14 ; it under the terms of the GNU General Public License as published by
  15 ; the Free Software Foundation; either version 2, or (at your option)
  16 ; any later version.
  17 ;
  18 ; Sapphire is distributed in the hope that it will be useful,
  19 ; but WITHOUT ANY WARRANTY; without even the implied warranty of
  20 ; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21 ; GNU General Public License for more details.
  22 ;
  23 ; You should have received a copy of the GNU General Public License
  24 ; along with Sapphire.  If not, write to the Free Software Foundation,
  25 ; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26
  27 ;----- Overview -------------------------------------------------------------
  28 ;
  29 ; Functions provided:
  30 ;
  31 ;  options_read
  32 ;  options_write
  33 ;  optType_string
  34 ;  optType_integer
  35 ;  optType_literal
  36 ;  optType_enum
  37 ;  optType_bool
  38 ;  optType_version
  39
  40                 [       :LNOT::DEF:options__dfn
  41                 GBLL    options__dfn
  42
  43 ;+              LIB     sapphire:^.bsh.options
  44
  45 ; --- options_read ---
  46 ;
  47 ; On entry:     R0 == chunk file handle
  48 ;               R1 == pointer to a chunk name
  49 ;               R2 == pointer to options definition
  50 ;               R3,R4 specify address of output block
  51 ;
  52 ; On exit:      --
  53 ;
  54 ; Use:          Claims the specified options chunk, and reads the data in
  55 ;               it into a binary block.  Because the output data might be
  56 ;               in a flex block, the two registers R3,R4 which define its
  57 ;               address work as follows:
  58 ;
  59 ;               R3 == address or offset of data
  60 ;               R4 == -1 if R3 is address, else flex anchor address
  61
  62                 IMPORT  options_read
  63
  64 ; --- options_write ---
  65 ;
  66 ; On entry:     R0 == terminator character to write, 0 for none, or -1 for
  67 ;                       quoting with 's
  68 ;               R1 == pointer to name to save
  69 ;
  70 ; On exit:      May return an error
  71 ;
  72 ; Use:          Writes out an option name, terminated with the character
  73 ;               given in R0 (which will normally be a space or an `=' sign).
  74
  75                 IMPORT  options_write
  76
  77 ; --- optType_string ---
  78 ;
  79 ; Flags:        --
  80 ;
  81 ; Data:         (word) buffer size of string
  82 ;
  83 ; Use:          Handles string data.  The binary representation is a ctrl
  84 ;               terminated string.  The textual representation is a sequence
  85 ;               of characters, which is always output in single quotes,
  86 ;               although this is not necessary for the input.  The string
  87 ;               will be truncated to fit in the buffer during reading.
  88
  89                 IMPORT  optType_string
  90
  91 ; --- optType_integer ---
  92 ;
  93 ; Flags:        bit 8 == use given default base
  94 ;
  95 ; Data:         (word) default base, if bit 8 set
  96 ;
  97 ; Use:          Handles integer data.  The binary representation is a 32-
  98 ;               bit integer value.  The textual representation is the normal
  99 ;               RISC OS style of numbers (i.e. the base_value notation is
 100 ;               supported).  Numbers are always output in the default base
 101 ;               given (or in decimal if there is none given).  Numbers
 102 ;               being read may always have a sign; numbers will only be
 103 ;               output with a sign if the default base is decimal.  Uppercase
 104 ;               letters will be used for output, but any case is acceptable
 105 ;               for input.
 106 ;
 107 ;               Special prefixes allowed are `%' for binary and `&' for hex.
 108 ;               Such numbers are always output with these prefixes.
 109
 110                 IMPORT  optType_integer
 111
 112 ; --- optType_literal ---
 113 ;
 114 ; Flags:        --
 115 ;
 116 ; Data:         (string) data to write out (*null* terminated)
 117 ;
 118 ; Use:          Reads nothing; leave the name blank.  Writes out the data
 119 ;               literally.  Note that an extra linefeed is added to the
 120 ;               end, so don't overdo it.
 121
 122                 IMPORT  optType_literal
 123
 124 ; --- optType_enum ---
 125 ;
 126 ; Flags:        bit 8 == quote output string
 127 ;               bit 9 == don't put an `=' sign in output
 128 ;
 129 ; Data:         See below
 130 ;
 131 ; Use:          The data is a collection of ctrl-terminated strings, itself
 132 ;               terminated by a zero-length entry.  The textual
 133 ;               representation is one of these strings, or an abbreviation
 134 ;               of one.  The binary representation is a word containing the
 135 ;               index into the list.
 136
 137                 IMPORT  optType_enum
 138
 139 ; --- optType_bool ---
 140 ;
 141 ; Flags:        bit 8 == make flag active low
 142 ;               bit 9 == use `on'/`off' rather than `true'/`false'; also
 143 ;                       suppresses the `=' sign
 144 ;
 145 ; Data:         (word) bit mask to OR or BIC within word
 146 ;
 147 ; Use:          Handles a boolean option.  It will translate between the
 148 ;               strings `true' or `false' and a bit (or set of bits) within
 149 ;               a word.
 150
 151                 IMPORT  optType_bool
 152
 153 ; --- optType_version ---
 154 ;
 155 ; Flags:        --
 156 ;
 157 ; Data:         --
 158 ;
 159 ; Use:          Converts between version number strings (of the form
 160 ;               <int>[.[<digit>[<digit>]]]) and integers.  The version
 161 ;               number is stored multiplied by 100.
 162
 163                 IMPORT  optType_version
 164
 165                 ]
 166
 167 ;----- Data structures ------------------------------------------------------
 168
 169 ; --- Options definition block ---
 170
 171                 ^       0
 172 opt_flags       #       4                       ;Flags for this item
 173 opt_length      #       4                       ;Size of this table entry
 174 opt_offset      #       4                       ;Offset in block of data
 175 opt_type        #       4                       ;Address of type handler
 176 opt_name        #       0                       ;Name of this option
 177
 178 ; --- Option block flags ---
 179
 180 optFlag_last    EQU     (1<<0)                  ;This is the last block
 181 optFlag_ignore  EQU     (1<<1)                  ;Don't read this option
 182
 183 ; --- Integer type flags ---
 184
 185 intFlag_base    EQU     (1<<8)                  ;Default base specified
 186
 187 ; --- Enumeration type flags ---
 188
 189 enumFlag_quote  EQU     (1<<8)                  ;Quote the output string
 190 enumFlag_noEq   EQU     (1<<9)                  ;Don't output an `=' sign
 191
 192 ; --- Boolean type flags ---
 193
 194 boolFlag_cpl    EQU     (1<<8)                  ;Flag is complemented
 195 boolFlag_onOff  EQU     (1<<9)                  ;Use `on'/`off' notation
 196
 197 ; --- Type handler reason codes ---
 198 ;
 199 ; All enter with:
 200 ;
 201 ;  R0 == reason code
 202 ;  R7 == flags read from table
 203 ;  R8 == address of option name
 204 ;  R9 == address of type-specific data
 205 ; R10 == address of binary option
 206
 207                 ^       0
 208 optReason_read  #       1                       ;Read from option string
 209                                                 ;R1 == pointer to string
 210
 211 optReason_write #       1                       ;Write data to xsave file
 212
 213 ;----- Macros ---------------------------------------------------------------
 214
 215                 GBLA    opt__f
 216                 GBLA    opt__c
 217 opt__c          SETA    0
 218                 GBLL    opt__p
 219 opt__p          SETL    {FALSE}
 220
 221 ; --- Macro: OPTION ---
 222 ;
 223 ; Arguments:    offset == offset of data into options block
 224 ;               type == name of data type
 225 ;               name == name of option tag
 226 ;
 227 ; Use:          Starts building an entry in the options table.
 228
 229                 MACRO
 230 $label          OPTION  $offset,$type,$name
 231                 ALIGN
 232
 233                 [       opt__p
 234 opt__sz$opt__c  EQU     {PC}-opt__a$opt__c
 235                 ]
 236 opt__f$opt__c   EQU     opt__f
 237 opt__c          SETA    opt__c+1
 238 opt__p          SETL    {TRUE}
 239
 240 $label
 241
 242 opt__f          SETA    0
 243 opt__a$opt__c
 244
 245                 DCD     opt__f$opt__c
 246                 DCD     opt__sz$opt__c
 247                 DCD     $offset
 248                 DCD     $type
 249                 DCB     "$name",0
 250                 ALIGN
 251
 252                 MEND
 253
 254 ; --- Macro: OPTFLAG --
 255 ;
 256 ; Arguments:    bit == bit to set
 257 ;
 258 ; Use:          Sets a bit in the flags word for the current option.
 259
 260                 MACRO
 261                 OPTFLAG $bit
 262 opt__f          SETA    opt__f :OR: $bit
 263                 MEND
 264
 265 ; --- Macro: OPTEND ---
 266 ;
 267 ; Arguments:    --
 268 ;
 269 ; Use:          Terminates an options block.
 270
 271                 MACRO
 272                 OPTEND
 273                 OPTFLAG optFlag_last
 274                 ALIGN
 275                 [       opt__c<>0
 276 opt__sz$opt__c  EQU     {PC}-opt__a$opt__c
 277                 ]
 278 opt__f$opt__c   EQU     opt__f
 279 opt__c          SETA    opt__c+1
 280 opt__p          SETL    {FALSE}
 281                 MEND
 282
 283 ; --- Macro: OPTSTR ---
 284 ;
 285 ; Arguments:    offset == offset into block to write integer
 286 ;               name == tag for option
 287 ;               size == buffer size for string
 288 ;
 289 ; Use:          Adds a `string' option.
 290
 291                 MACRO
 292 $label          OPTSTR  $offset,$name,$size
 293 $label          OPTION  $offset,optType_string,$name
 294                 DCD     $size
 295                 MEND
 296
 297 ; --- Macro: OPTINT ---
 298 ;
 299 ; Arguments:    offset == offset into block to write integer
 300 ;               name == tag for option
 301 ;               base == (optional) default base to use
 302 ;
 303 ; Use:          Adds an `integer' option.
 304
 305                 MACRO
 306 $label          OPTINT  $offset,$name,$base
 307 $label          OPTION  $offset,optType_integer,$name
 308                 [       "$base"<>""
 309                 OPTFLAG intFlag_base
 310                 DCD     $base
 311                 ]
 312                 MEND
 313
 314 ; --- Macro: OPTLIT ---
 315 ;
 316 ; Arguments:    --
 317 ;
 318 ; Use:          Writes out the following text to the options chunk.
 319
 320                 MACRO
 321 $label          OPTLIT
 322 $label          OPTION  0,optType_literal,""
 323                 OPTFLAG optFlag_ignore
 324                 MEND
 325
 326 ; --- Macro: OPTENUM ---
 327 ;
 328 ; Arguments:    offset == offset into block to write integer
 329 ;               name == tag for option
 330 ;
 331 ; Use:          Adds an `enumeration' option.  Follow by null-terminated
 332 ;               list of null-terminated strings.
 333
 334                 MACRO
 335 $label          OPTENUM $offset,$name
 336 $label          OPTION  $offset,optType_enum,$name
 337                 MEND
 338
 339 ; --- Macro: OPTBOOL ---
 340 ;
 341 ; Arguments:    offset == offset into block to write flags
 342 ;               name == tag for option
 343 ;               flag == flag bit to set
 344 ;
 345 ; Use:          Adds a `boolean' option.
 346
 347                 MACRO
 348 $label          OPTBOOL $offset,$name,$flag
 349 $label          OPTION  $offset,optType_bool,$name
 350                 DCD     $flag
 351                 MEND
 352
 353 ; --- Macro: OPTVSN ---
 354 ;
 355 ; Arguments:    offset == offset into block to write integer
 356 ;               name == tag for option
 357 ;
 358 ; Use:          Adds a `version number' option.
 359
 360                 MACRO
 361 $label          OPTVSN  $offset,$name
 362 $label          OPTION  $offset,optType_version,$name
 363                 MEND
 364
 365 ;----- That's all, folks ----------------------------------------------------
 366
 367                 END