> Special

Title: DeviceFS special field handling
Authors: David De Vorchik, Tim Dobson
History:
        16-Apr-91 DDV Created.
        20-Apr-91 DDV Changed to cope with new improved special fields.
        20-Apr-91 DDV Added note about GSTrans escapes not yet implemented.
        29-May-91 TMD Corrected some typos.


INTRODUCTION
------------

Special fields within DeviceFS are commonly used to specify parameters to
the device, ie what buffers to be used, if the device should be flushing
when a stream is closed and so on.

The device can specifiy a validation string which is used to parse the
special field when the stream is being opened.  If this is present then
DeviceFS will parse the string and return a block of data relating to the
string's contents.  This data will remain intact until the stream is closed. 
If no validation string is specified then it is up to the device to take and
manage a copy, also to filter out any unwanted information (phew!).

The syntax for validation strings is very simple:

        <keyword>[,<keyword>]/<escape>[/<escape>] ...

Keywords are used to associate each command with an escape sequence, there
can be more than one keyword associated with a particular escape field, this
is provided for two reasons, the first is when a different word has the same
meaning, eg. Colour or Color.  And secondly when defining the various states
for a switch.

The escape sequence describes how the preceding data should be treated and
also what to do with the rest of the special field string (up to the next
separator).

The following characters are valid in escape sequences:

        \N      - number
        \S      - switch
        \G      - GSTrans               (NYI)

Within the special field string each parameter is seperated by a comma or a
character which is out of place, ie. a non-numeric in a numerical field. 
Each keyword within the special field string is separated by a semi-colon.

The buffer passed to the device contains the following:

        <word> per escape caracter
        <data> for GSTransed fields.

The words are reset to &DEADDEAD on entry to indicate that they are
currently of no use, as each command sequence is decoded then its contents
is placed into the return buffer.

Numbers are simply stored into the word, they are decoded using
OS_ReadUnsigned and stored away.  Switches, these store the state of the
keywords placed, ie:

        foo,poo/S 

This yields 0 if 'foo' is present within the string, 1 if 'poo' is present
within the string.  

The order of commands within the validation string and the special field
string do not match, the commands within the validation string control how
the values are returned back to the caller.
