4 ; Read options from an options chunk
6 ; © 1995-1998 Straylight
9 ;----- Licensing note -------------------------------------------------------
11 ; This file is part of Straylight's Sapphire library.
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)
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.
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.
27 ;----- Overview -------------------------------------------------------------
40 [ :LNOT::DEF:options__dfn
43 ;+ LIB sapphire:^.bsh.options
45 ; --- options_read ---
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
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:
59 ; R3 == address or offset of data
60 ; R4 == -1 if R3 is address, else flex anchor address
64 ; --- options_write ---
66 ; On entry: R0 == terminator character to write, 0 for none, or -1 for
68 ; R1 == pointer to name to save
70 ; On exit: May return an error
72 ; Use: Writes out an option name, terminated with the character
73 ; given in R0 (which will normally be a space or an `=' sign).
77 ; --- optType_string ---
81 ; Data: (word) buffer size of string
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.
91 ; --- optType_integer ---
93 ; Flags: bit 8 == use given default base
95 ; Data: (word) default base, if bit 8 set
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
107 ; Special prefixes allowed are `%' for binary and `&' for hex.
108 ; Such numbers are always output with these prefixes.
110 IMPORT optType_integer
112 ; --- optType_literal ---
116 ; Data: (string) data to write out (*null* terminated)
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.
122 IMPORT optType_literal
124 ; --- optType_enum ---
126 ; Flags: bit 8 == quote output string
127 ; bit 9 == don't put an `=' sign in output
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.
139 ; --- optType_bool ---
141 ; Flags: bit 8 == make flag active low
142 ; bit 9 == use `on'/`off' rather than `true'/`false'; also
143 ; suppresses the `=' sign
145 ; Data: (word) bit mask to OR or BIC within word
147 ; Use: Handles a boolean option. It will translate between the
148 ; strings `true' or `false' and a bit (or set of bits) within
153 ; --- optType_version ---
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.
163 IMPORT optType_version
167 ;----- Data structures ------------------------------------------------------
169 ; --- Options definition block ---
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
178 ; --- Option block flags ---
180 optFlag_last EQU (1<<0) ;This is the last block
181 optFlag_ignore EQU (1<<1) ;Don't read this option
183 ; --- Integer type flags ---
185 intFlag_base EQU (1<<8) ;Default base specified
187 ; --- Enumeration type flags ---
189 enumFlag_quote EQU (1<<8) ;Quote the output string
190 enumFlag_noEq EQU (1<<9) ;Don't output an `=' sign
192 ; --- Boolean type flags ---
194 boolFlag_cpl EQU (1<<8) ;Flag is complemented
195 boolFlag_onOff EQU (1<<9) ;Use `on'/`off' notation
197 ; --- Type handler reason codes ---
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
208 optReason_read # 1 ;Read from option string
209 ;R1 == pointer to string
211 optReason_write # 1 ;Write data to xsave file
213 ;----- Macros ---------------------------------------------------------------
221 ; --- Macro: OPTION ---
223 ; Arguments: offset == offset of data into options block
224 ; type == name of data type
225 ; name == name of option tag
227 ; Use: Starts building an entry in the options table.
230 $label OPTION $offset,$type,$name
234 opt__sz$opt__c EQU {PC}-opt__a$opt__c
236 opt__f$opt__c EQU opt__f
254 ; --- Macro: OPTFLAG --
256 ; Arguments: bit == bit to set
258 ; Use: Sets a bit in the flags word for the current option.
262 opt__f SETA opt__f :OR: $bit
265 ; --- Macro: OPTEND ---
269 ; Use: Terminates an options block.
276 opt__sz$opt__c EQU {PC}-opt__a$opt__c
278 opt__f$opt__c EQU opt__f
283 ; --- Macro: OPTSTR ---
285 ; Arguments: offset == offset into block to write integer
286 ; name == tag for option
287 ; size == buffer size for string
289 ; Use: Adds a `string' option.
292 $label OPTSTR $offset,$name,$size
293 $label OPTION $offset,optType_string,$name
297 ; --- Macro: OPTINT ---
299 ; Arguments: offset == offset into block to write integer
300 ; name == tag for option
301 ; base == (optional) default base to use
303 ; Use: Adds an `integer' option.
306 $label OPTINT $offset,$name,$base
307 $label OPTION $offset,optType_integer,$name
314 ; --- Macro: OPTLIT ---
318 ; Use: Writes out the following text to the options chunk.
322 $label OPTION 0,optType_literal,""
323 OPTFLAG optFlag_ignore
326 ; --- Macro: OPTENUM ---
328 ; Arguments: offset == offset into block to write integer
329 ; name == tag for option
331 ; Use: Adds an `enumeration' option. Follow by null-terminated
332 ; list of null-terminated strings.
335 $label OPTENUM $offset,$name
336 $label OPTION $offset,optType_enum,$name
339 ; --- Macro: OPTBOOL ---
341 ; Arguments: offset == offset into block to write flags
342 ; name == tag for option
343 ; flag == flag bit to set
345 ; Use: Adds a `boolean' option.
348 $label OPTBOOL $offset,$name,$flag
349 $label OPTION $offset,optType_bool,$name
353 ; --- Macro: OPTVSN ---
355 ; Arguments: offset == offset into block to write integer
356 ; name == tag for option
358 ; Use: Adds a `version number' option.
361 $label OPTVSN $offset,$name
362 $label OPTION $offset,optType_version,$name
365 ;----- That's all, folks ----------------------------------------------------