CONFIG -- Configuration Management


	1) Usage

	| OBJECT cnf[CONFIG];

	A configuration (CONFIG) object must be initialized before its
	use. Once set up, it can be loaded from and saved to disk. The
	disk file will be in ASCII format and consist of name/value
	pairs of the form

	| name = value

	where any number (but at least one) space or TAB character may
	occur before and after the equal sign (=). The value may be a
	number, a string, or a color value. See the description of the
	INIT method for details.

	The interface to the user program is defined by including the
	addresses of configuration variables (flags, sizes, etc) in the
	initialization table passed to CNF.INIT. When loading a
	configuration, these variables will be updated automatically.


	2) Methods


	2.1 INIT

	| CNF.INIT(set) ! Vec => Flag

	CNF.INIT is used to set up a configuration. It must be called
	before loading or storing the configuration. The INIT method
	sets all fields to their default values (see below). The SET
	argument is a table of CONF records with the following
	structure:

	C_NAME		the name of the configuration variable
	C_TYPE		the type of the variable
	C_DEFAULT	the default value of the variable
	C_VAR		a pointer to an internal variable

	The following types exists:

	Type		Saved as	Description
	T_STRING	name = "value"	any set of characters
	T_NUMERIC	name = value	a signed decimal or
	.		.		hexa-decimal number
	T_COLOR		name = color	a color value (see below)

	A color value consists of two color names separated by a slash.
	The following color names exist:

	black, blue, green, cyan, red, magenta, yellow, grey.

	The first color name may be prefixed with the string 'light-',
	thereby increasing the intensity of the prefixed color. For
	example, bright yellow characters on pink ground would be saved
	as 'light-yellow/magenta'.

	A sample configuration table may look like this:

	| msg := "Hello, World!";
	| col := ttyctl.F_GREY | ttyctl.B_BLACK | ttyctl.F_BRIGHT;
	| Set := [
	|   [ "x-pos",   config.T_NUMERIC,    20, @Xpos    ],
	|   [ "y-pos",   config.T_NUMERIC,    10, @Ypos    ],
	|   [ "color",   config.T_COLOR,   (col), @Color   ],
	|   [ "message", config.T_STRING,  (msg), @Message ],
	|   0
	| ];

	The last member of the table must be '0'. It indicates the end
	of the table. The (msg) entry could be replaced with the string
	"Hello, World!" as defined above. This has not been done here
	for space reasons. The same applies to the 'col' entry. The
	color values are defined in the TTYCTL class.

	When loading a configuration initialized with the above table,
	the value of the 'x-pos' field, for instance, would be stored
	in'Xpos' and the value of 'message' would be copied to
	'Message'. In this case, 'Message' must be a vector and it must
	provide enough space for the stored message. When saving the
	above configuration using its default values, the following
	file would be written:

	| x-pos = 20
	| y-pos = 10
	| color = light-grey/black
	| message = "Hello, World!"

	RETURN CODES:

	0	Configuration set up successfully
	-1	Bad type detected in a C_TYPE field


	2.2 LOAD

	| CNF.LOAD(path, errp) ! Str,Vec => 0|-1|-2

	CNF.LOAD will attempt to open the configuration file specified
	in PATH, parse it, and set the variables specified in the
	configuration table accordingly. ERRP is a pointer to a
	variable, which will be assigned the number of each input line
	before parsing it. In case of an error, it will hold the number
	of the line of the config file which has caused the error.

	The order of input lines does not matter. Empty lines and lines
	beginning with a hash character (#) will be ignored. Other
	lines will be split up into name/value pairs. They are expected
	to have the form

	| name = value

	where any positive number of white space characters is
	allowed before and after the equal sign (=). 'Name' will be
	looked up in the configuration table (C_NAME) and if it is
	found, the value will be converted according to its type
	(C_TYPE) and stored in the specified variable (C_VAR).

	Strings will have their double quotes (") removed, if any,
	numbers will be converted using STRING.STRTONUM, and color
	values will be decoded into values which may be passed to
	TTYCTL objects. Numeric values are assumed to be decimal unless
	they are prefixed with '0x' or '0X'. In the latter case, they
	are assumed to be hexa-decimal numbers in C-style notation.

	Color values and numeric values are assigned to the variables
	specified in the configuration table. Strings are copied to the
	specified variables using T3X.MEMCOPY. Therefore, atomic
	(integer) variables should be specified in COLOR and NUMERIC
	entries and vectors of a sufficient size should be specified in
	STRING entries.

	RETURN CODES:

	-2	Configuration file could not be opened
	-1	Error in configuration file
	0	Configuration loaded successfully

	When -2 is returned, the error pointer ERRP will not be set.


	2.3 SAVE

	| CNF.SAVE(path, head) ! Str,Vec => 0|-1|-2

	CNF.SAVE writes a configuration to the file specified in the
	PATH argument. The configuration records will be written in the
	order specified in CNF.INIT and an existing configuration with
	the same file name will be overwritten. Comments inserted by
	the user will be removed.

	HEAD may be zero or a null-terminated table of strings which
	will be inserted before the configuration records themselves.

	For example,

	| CNF.SAVE("xyzrc", [ "# This an XYZ config file", 0 ]);

	will save the configuration assigned to CNF to the file 'xyzrc'
	and insert the line

	| # This an XYZ config file

	before the first entry. Since CNF.LOAD will attempt to parse
	lines inserted using HEAD, it is a good idea to prefix comments
	with a hash character (#).

	RETURN CODES:

	-2	Configuration file could not be created
	-1	Error writing configuration file
	0	Configuration saved successfully