2N/A# This file and its contents are supplied under the terms of the
2N/A# Common Development and Distribution License ("CDDL"), version 1.0.
2N/A# You may only use this file in accordance with the terms of version
2N/A# A full copy of the text of the CDDL should have accompanied this
2N/A# source. A copy of the CDDL is also available via the Internet at
2N/A# Copyright 2014 Garrett D'Amore <garrett@damore.org>
2N/AThe configuration files in this directory are structured as lines,
2N/Awhere each line is made up of fields, separated by "|" characters,
2N/Apossibly surrounded by whitespace.
2N/ANew lines preceeded by backslashes are ignored, allowing for a continuation
2N/Aof lines, in the usual UNIX way.
2N/AA line beginning with a hashmark is a comment, and is ignored, as are lines
2N/Aconsisting solely of whitespace.
2N/AThe first field is always the "keyword", which determines the meaning and
2N/Apresence of any other fields.
2N/AThese files are parsed using the test_load_config() function. This
2N/Afunction has the following prototype:
2N/A int test_load_config(test_t, const char *, ...);
2N/AThe variable arguments are the keywords and handling functions. These
2N/Amust be supplied in pairs and the list is terminated with a NULL, like this:
2N/AThe test_config_load function will search for the named file (provided it
2N/Ais not an absolute path) in a few locations:
2N/A * relative to the current directory, exactly as specified
2N/A * relative to ../../cfg/ (if $STF_SUITE is undefined)
2N/AThe handling functions (keywordcb in the example above) have the following
2N/A typedef int (*test_cfg_func_t)(char **fields, int nfields, char **err);
2N/Aso for example, keywordcb should be declared thusly:
2N/A int keywordcb(char **fields, int nfields, char **err);
2N/AThese functions are called each time a paired keyword is seen in the file.
2N/A"fields" is an array of fields, pre-split with surrounding whitespace removed,
2N/Aand contains "nfields" items. Internal whitespace is unaffected.
2N/AThe function should return 0 on successful handling, or -1 on failure. In
2N/Athe event of failure, it should record an error string in "err" using
2N/Aasprintf() or strdup(). ("err" should be unmodified otherwise.)
2N/AThis parser is rather simplistic, and it lacks support for embedding "|"
2N/Afields in lines, and also doesn't support escaping, so you can't add "\"
2N/Aat the end of a line (if you need that, leave some trailing whitespace).
2N/AThere are also some internal limits on the length of lines (1K), and on the
2N/Anumber of fields (20). As this is only used for these test suites, this
2N/Ashould not be a significant limitation.
2N/A Astute readers may ask why invent a new configuration file, and why use
2N/A position based parsing instead of name value pairs. These files are
2N/A optimized for specific needs, and intended to support relatively dense
2N/A information in a format that is easy for humans to work with. JSON or XML
2N/A or even YAML could have served, but the overhead of a syntax was more than
2N/A we wanted to introduce. Test suites are free to use other formats if they
2N/A choose, but this simple format has the advantage of being built-in and