#
# This file and its contents are supplied under the terms of the
# Common Development and Distribution License ("CDDL"), version 1.0.
# You may only use this file in accordance with the terms of version
# 1.0 of the CDDL.
#
# A full copy of the text of the CDDL should have accompanied this
# source.  A copy of the CDDL is also available via the Internet at
# http://www.illumos.org/license/CDDL.
#

#
# Copyright 2014 Garrett D'Amore <garrett@damore.org>
#

The configuration files in this directory are structured as lines,
where each line is made up of fields, separated by "|" characters,
possibly surrounded by whitespace.

New lines preceeded by backslashes are ignored, allowing for a continuation
of lines, in the usual UNIX way.

A line beginning with a hashmark is a comment, and is ignored, as are lines
consisting solely of whitespace.

The first field is always the "keyword", which determines the meaning and
presence of any other fields.

These files are parsed using the test_load_config() function.  This
function has the following prototype:

	int test_load_config(test_t, const char *, ...);

The variable arguments are the keywords and handling functions.  These
must be supplied in pairs and the list is terminated with a NULL, like this:

	test_config_load(t, "myfile.cfg", "mykeyword", keywordcb, NULL);

The test_config_load function will search for the named file (provided it
is not an absolute path) in a few locations:

	* relative to the current directory, exactly as specified
	* relative to $STF_SUITE/cfg/	(if $STF_SUITE is defined)
	* relative to ../../cfg/	(if $STF_SUITE is undefined)
	* relative to cfg/

The handling functions (keywordcb in the example above) have the following
typedef:

	typedef int (*test_cfg_func_t)(char **fields, int nfields, char **err);

so for example, keywordcb should be declared thusly:

	int keywordcb(char **fields, int nfields, char **err);

These functions are called each time a paired keyword is seen in the file.
"fields" is an array of fields, pre-split with surrounding whitespace removed,
and contains "nfields" items.  Internal whitespace is unaffected.

The function should return 0 on successful handling, or -1 on failure.  In
the event of failure, it should record an error string in "err" using
asprintf() or strdup(). ("err" should be unmodified otherwise.)

This parser is rather simplistic, and it lacks support for embedding "|"
fields in lines, and also doesn't support escaping, so you can't add "\"
at the end of a line (if you need that, leave some trailing whitespace).

There are also some internal limits on the length of lines (1K), and on the
number of fields (20).  As this is only used for these test suites, this
should not be a significant limitation.

Please see ../tests/symbols/symbols_test.c for an example of correct usage.

Aside:

  Astute readers may ask why invent a new configuration file, and why use
  position based parsing instead of name value pairs.  These files are
  optimized for specific needs, and intended to support relatively dense
  information in a format that is easy for humans to work with.  JSON or XML
  or even YAML could have served, but the overhead of a syntax was more than
  we wanted to introduce.  Test suites are free to use other formats if they
  choose, but this simple format has the advantage of being built-in and
  easy to use.