WimpExtension document: Options Library (&20)                         Doc 07
============================================================================

The Options library provides facilities for creating and maintaining Options
files. You need to specify a Definitions block, which contains data on what
options are available to the user, and what values each option can take. The
Options library will then provide you with calls to set or read the various
options, and to store or read the options to or from a file.

A Definitions block consists of one line of section identifier in square
brackets, and then any number of lines of the form:
  <tagname>=<type>[:<default value>]

The section identifier can contain any printable characters, except [ and ].
The tagname is a short name by which you refer to that option. It can
consist of alphanumerics and _. The type specifies what sort of data the
option takes (eg. number, string, etc.). The default value is optional, and
specifies what value to give the option if it is not set by the user.

The available types are:
  Number[([<min>,]<max>)]
      The option can take integer between <min> and <max>. If no parameters
      are given, any 32-bit integer can be used. If one parameter is given,
      any number between 0 and that parameters can be used. (If no default
      is specified, <min> is used.)
  Text(<length>)
      The option can take a string of up to <length> characters, including
      null-terminator. The length must be between 2 and 256. (If no default
      is specified, an empty string is used.)
  List(<value>,<value>...)
      The option can take any of the specified values. (If no default is
      specified, the first value is used.)

An example valid definitions block would be: (note that the spaces at the
beginning of lines are for clarity - they are not allowed in an actual
definitions block)

  [MyExampleProgram]
  Percentage=Number(0,100):50
  Filename=Text(256)
  Animal=List(Dog,Cat,Horse):Dog
  Magazine=List("Acorn User","Acorn Computing","RISC User")

Note that strings, for example the names of the available values in a List
type, or the default for a Text type, do not need to be enclosed in quotes
if they contain only alphanumerics and _. e.g. <This> is a valid string, as
is <_this> and <"this!"> but not <this!>.

The options can be stored in a file automatically by the library. The format
of this file is as follows: (note that the section identifiers are not
optional, the square brackets are literal)

  [<section identifier>]
  <tagname>=<value>
  <tagname>=<value>
    ...
  [<section identifier>]
  <tagname>=<value>
    ...

Anything after a # or ; character (at the end of a line, or as the first
non-whitespace character in a line) is ignored and these characters can
therefore be used to introduce comments.

For example:
  [MyExampleProgram]
  Percentage=25
  Filename="ADFS::Burma.$.Options.Spec"
  Animal=Dog ; woof
  Magazine="Acorn User"

Note that the Options library is very strict about the format of the
definitions block (e.g. white space is not allowed outside strings) as this
data is only ever seen by the programmer. The saved options format is much
more lenient, allowing white space, comments, etc. as this is liable to be
edited by the user in a text editor.


R0 = &00 : Create 'current options' block
-----------------------------------------
R1-> memory to contain 'current options' block (0 to read size required)
R2-> definitions block
R3 = length of definitions block
Exit:
R0 = length of data written to R1

Creates a 'current options' block given a definitions block. You will
probably wish to use this call first with R1=0 to determine the size of the
block you will need, and then again with R1 pointing to a memory block of
the correct size. The format of the current options block is undefined.


R0 = &01 : Read options from file
---------------------------------
R1-> 'current options' block
R2-> filename of Options file

Reads in the specified file and sets the options in the 'current options'
block as necessary. It ignores everything up to the section identifier for
the block in R1, and everything after the next '[' at the beginning of a
line.


R0 = &02 : Read options from memory
-----------------------------------
R1-> 'current options' block
R2-> Options file in memory
R3 = length of Options file in memory

As for reason code &01, except that it uses data in memory rather than on
disk.


R0 = &03 : Write options to file
--------------------------------
R1-> 'current options' block
R2-> filename of Options file

Writes the options to the specified file, overwriting the file if it already
exists.


R0 = &04 : Write options to memory
----------------------------------
R1-> 'current options' block
R2-> block to contain Options file (0 to read size required)
Exit:
R0 = length of data written to R2

Writes the options in Options file format to the block in R2.


R0 = &05 : Read option's value
------------------------------
R1-> 'current options' block
R2-> tagname of option to read
R3-> block to contain value (0 to read size required)
Exit:
R0 = length of data written to R3

Reads the current value of the specified option, as stored in the 'current
options' block. The format of the data returned depends on the option's
type:
  Number
      four-byte numerical value in R3+0 to R3+3
  Text
      null-terminated string at R3+0
  List
      one byte index marker at R3+0 (0=first value, 1=second value, etc.)
      null-terminated string at R3+1


R0 = &06 : Write option's value
-------------------------------
R1-> 'current options' block
R2-> tagname of option to read
R3-> block containing value (word aligned)

Writes the value of the specified option into the 'current options' block.
The format of the input block is as for reason code &05. Note that for List
types you can set the value in two ways, either by putting the index marker
at R3+0, or by putting &FF at R3+0 and putting the string representation
at R3+1.


R0 = &07 : Read option's data
-----------------------------
R1-> 'current options' block
R2-> tagname of option to read
R3-> block to contain data (0 to read size required)
Exit:
R0 = length of data written to R3

Reads the data about the option into the block in R3. The format of the data
returned depends on the option's type:
  Number: R3+0 = &00000000
      four-byte minimum value at R3+4 to R3+7
      four-byte maximum value at R3+8 to R3+11
  Text:   R3+0 = &00000001
      four-byte maximum length at R3+4 to R3+7
  List:   R3+0 = &00000002
      one-byte number of possible values at R3+4
      series of null-terminated strings at R3+5, terminated with another
      null byte


R0 = &08 : Make menu from List option
-------------------------------------
R1-> 'current options' block
R2-> tagname of option to read
R3-> block to contain data (0 to read size required)
Exit:
R0 = length of data written to R3

Creates a Wimp menu block containing the available values for the specified
list option, with the currently selected one ticked and the menu title being
the tag name. '_' characters in the tagname will be converted to spaces in
the menu title. Note that this call will put indirected menu data after the
actual menu block.


R0 = &09 : Write changed options to memory
------------------------------------------
R1-> 'current options' block
R2-> block to contain Options file (0 to read size required)
R3-> old 'current options' block
Exit:
R0 = length of data written to R2

Writes the options in Options file format to the block in R2, only writing
the options from the block in R1 which have changed from the block in R3.
Note that if all the options in R1 and R3 are identical then *nothing* will
be written to R2, not even the section identifier.


R0 = &0A : Write changed options to file
----------------------------------------
R1-> 'current options' block
R2-> filename of Options file
R3-> old 'current options' block

As for reason code &09, except that it writes to disk rather than to memory.


R0 = &0B : Read named section from file
---------------------------------------
R1-> 'current options' block
R2-> filename of Options file
R4-> section specifier

Reads in the specified file, using the section named in R4 rather than the
section named in the current options block. It ignores everything up to the
section identifier, and everything after the next '[' at the beginning of a
line.


R0 = &0C : Read named section from memory
-----------------------------------------
R1-> 'current options' block
R2-> Options file in memory
R3 = length of Options file in memory
R4-> section specifier

As for reason code &0B, except that it uses data in memory rather than on
disk.


R0 = &0D : Write named options to file
--------------------------------------
R1-> 'current options' block
R2-> filename of Options file
R3-> null-terminated list of null-terminated tagnames

Writes the options to the file specified in R2, only writing the options
from the block in R1 which are named in the list in R3. Note that if no
options are listed in R3 then *nothing* will be written to R2, not even the
section identifier.


R0 = &0E : Write named options to memory
----------------------------------------
R1-> 'current options' block
R2-> block to contain Options file (0 to read size required)
R3-> null-terminated list of null-terminated tagnames
Exit:
R0 = length of data written to R2

As for reason code &0D, except that it stores the output in memory rather
than on disk.


R0 = &0F : Read tagnames of specified options from file
-------------------------------------------------------
R1-> 'current options' block
R2-> filename of Options file
R4 = block to contain null-terminated list of null-terminated tagnames
     (0 to read size required)
Exit:
R0 = length of data written to R4

Reads the tagnames of the options (in the relevant section) that are
specifically mentioned in the specified Options file. e.g. if the input file
was:

  [MyExampleProgram]
  Percentage=25
  Animal=Dog ; woof

the output would be "Percentage" and "Animal". Note that this call does not
return an error if the input file is incorrect - i.e. syntactically invalid
tag names will simply be ignored, and tag names not specified in the current
options block will be returned along with the other tag names in R4.


R0 = &10 : Read tagnames of specified options from memory
---------------------------------------------------------
R1-> 'current options' block
R2-> Options file in memory
R3 = length of Options file in memory
R4 = block to contain null-terminated list of null-terminated tagnames
     (0 to read size required)
Exit:
R0 = length of data written to R4

As for reason code &0F, except that it uses data in memory rather than on
disk.
