Variable Load/Save (VLS)
                           ========================

   SuperBASIC utilities to fast save and load arrays and scalar variables

                             ©PWITTE May 7th 1995
                           ©pjwitte July 19th 2006


VSAVE - save a list of variables in internal format
VLOAD - load them back in again


key: < > => entity, | => or, [ ] => optional, .. => repeated


        er = VSAVE( <filename> \ | , array1 | var1 [, array2 | var2 ..] )

VSAVE saves a list of variables to file which can again be loaded back
into variables of the same kind using VLOAD. VSAVE can save two kinds
of variables of three types. The kinds are:

A) scalars,
B) arrays.

The types are
1) string, 2) float, 3) integer.

If the \ parameter is used after <filename>, any file with the same
name as <filename> is overwritten.

A certain amount of coersion is performed at the VSAVE stage in an
attempt to anticipate the wishes of the user:

An expression is interpreted as a variables of the same type.

FOR and REPeat indices are similarly treated as normal variables.

Unset variables are treated as variables containing zero or a nul
string.

A single array element is treated as a variable.

A substring and a single dimension string are treated as a string
variable: eg DIM a$(10) is a single dimension array and the slice of
that a$(2 to 3) is a sub-string. (This is not the same as: b$ = 'abc';
in this case b$(2 to 3) is NOT a sub-string but an expession).

Sub-arrays are treated as any other array and complete arrays may be
reloaded into sub-arrays.


        er = VLOAD( <filename>,  array1 | var1 [, array2 | var2 ..] )

Loads a list of values from file and stuffs them into the list of
parameters on a first-come-first-serve basis. The parameters neednt be
the same as those used in VSAVE, however if a variable overflows
during coercion, parsing of the file stops at that point and an
overflow error is returned in the variable er.

If an expression is encountered it is simply ignored and the value
skipped.

Sub-strings and single dimension arrays are treated as variables

Sub-arrays may be filled by array values provided the dimensions are
the same. If they are not an Out of Range error will be returned.

It is possible to skip values in the parameter list by using null
parameters, eg er = VLOAD(fnm$; a,, c) will skip the saved value b and
load in a and c in their correct places.

If the parameters to skip are at the end of the list they may simply
be omitted. The error Not Complete is then returned after the values
corresponding to those parameters supplied have been read in, unless
any other errors were encountered first.

If more parameters are found than there are values in the file an End
of File error is returned after reading in all the values that have
corresponding parameters.


Tips:

See VLS_txt for examples of usage

The VSAVE file structure:

       dc.l 'VS01'           ; header flag & version number
       dc.w count            ; number of parameters (excl filename)

Then repeat count times:

       dc.l skiplength       ; offset to next parameter (or 0)

   either:

       dc.w $30x             ; array (string, integer or float)
       dc.w nodims           ; number of dimensions

     repeat nodims times:

       dc.w highest_index    ; highest index number
       dc.w multiplier       ; multiplier for this dimension

     followed by the data:

       data                  ; array data in internal format

   or:
       dc.w $20x             ; scalar variable, types as above
       data                  ; value of variable