Standard Config is a system library for Linux, that provides a simple command line and config file interface. It comes with two command line utilities for processing config files, which allow them to be accessed in various ways, and for config files containing default options to be automatically compiled directly into a binary. Config files can be used as simple databases, and as a simpler replacement for JSON and XML.
There are 5 main sources of config options: fixed system config file (for options that can’t be changed), command line, user config file, system config file, and built-in defaults. The built-in default options are stored in a C source archive, which can also be used for other files (eg. icons). They are created by the stdconfig-csrca command, and encapsulated within a C header file.
Config files store options in a hierarchical (tree) structure, each being either a directory, or having a value. Values are specified as integers, floating points or text, and as single values or in arrays. The command line also allows option path names to be specified by separating them with slashes. All command line arguments that are options must be specified as either -option=value or -option, with the latter being equivalent to -option=1. Command line arguments can by specified in any order, and those that don’t start with a dash are interpreted as files, and all stored in the files option.
This package was written from scratch, starting on 2001-08-31, in GNU C, using Emacs and Vi, and the command line (ie. old school).
Options can be specified in config files or via the command line. However, command line option values are always text, except for switches (which are equal to 1, and stored as 1, not “1”).
Command line options are always preceded by a single hyphen, and its value (unless it’s a switch) is given by an equals sign, without any spaces.
Option names are case insensitive, and follow similar rules to C identifiers (only letters, numerals, ‘-‘ and ‘_’, except that the first character cannot be a numeral).
Option values have 6 basic data types: flag (boolean), unsigned integer, signed integer, double precision floating point, long precision floating point and string.
Each of the 6 basic data types has an array equivalent. Ie. options (that aren’t directories) can store one value, or a list of them.
Options are arranged within directories, with the default directory being the same as the program name, allowing different names of the same program (eg. via symbolic links) to have different options.
Every option name always refers to a value: if there is no option by that name, its value defaults to zero or an empty string.
All options can be parsed without having to know whether they’re short, long or switches. Unfortunately, this means that short options have to be specified separately. Eg. rm -r -f ... instead of rm -rf ....
Short option names (those with a single letter) can be specified using a compiled in list of synonyms.
Command line arguments that aren’t options are all gathered together under the files option.
Special characters can be escaped using standard notation. Eg. “\n” for a newline, “\” for a slash, etc.
Supports both line and block comments.
# comment 1
// comment 2
/* comment 3 */
#{ comment 4 #}
command {
option-1 1;
option-2 0.2;
directory-2 {
option-3 "three";
}
files "file-1", "file-2", "file-3";
}
directory-3 {
directory-4 {
option-4 1, 2, 3;
option-5 3.1415927, 1.618034, 2.7182818;
}
option-6 "";
}
> command file-1 -option-1 -option-2=0.2 -directory-2/option-3=three -/directory-3/directory-4/option-4=1,2,3 -/directory-3/directory-4/option-5=3.1415927,1.618034,2.7182818 -/directory-3/option-6="" file-2 file-3
Also have a look at the default config files in the defaults/ directory, and the example start files included in the Startd package.
stdconfig-tool: Converts config files between text and packed binary formats. Translates config files into HTML lists and tables. Accesses option values from config files, for use by scripts.
stdconfig-csrca: Packs files into C Source Archives, and represents them as array variables within C header files. Allows files to be stored within binaries, and accessed just like memory mapped files - similar to Windows resources, but for arbitrary files.
stdconfig-sizes: Simply displays Standard Config’s data types and the standard C equivalents, and their storage sizes.
See the INSTALL file for generic install instructions - this package uses the Autoconf compilation and installation system.
Each option and its value or values are stored in a node of a singly linked tree, with option indices instead of names, which index a NULL terminated string array. Most library functions are for searching config trees, accessing option values and manipulating option names and paths of option names. The option search and value access functions assume options always have a value, and default to 0, or either the empty string or NULL, if an option cannot be found. There are many slightly different access functions that automatically convert an option’s value from that in which it is stored. These functions operate on either a config option node, or a StdConfig structure, which contains pointers to a standard config tree and its associated option names string array. StdConfig structures can be replaced with NULL, to reference the library’s default one.
StdConfig structures are created by init functions that construct a config tree by reading config files and interpreting command line arguments. The last config file, for default options, is contained within a C source archive (similar to PAK files used by the game Quake), specified by a defaults buffer. There is no way to detect that an option wasn’t provided by the user, since they’re drawn from multiple sources, and because specifying or not specifying an option shouldn’t be a option value in itself.
The library also contains a number of utility functions, that are intended (ideally) for inclusion into standard C libraries. This includes the snprintfdate function, which is a superior alternative to strftime, since dates are specified simply as the number of seconds since 1970, in floating point, and it offers a greater number of conversion specifiers. It’s possible to convert the date into “earth date” format, which is year, day of year, and second of day. There are also various string functions, and NULL terminated string array equivalents. One of these string functions is strcpysz which is similar to strlcpy.
The library itself is licensed under the GNU Lesser General Public Licence (LGPL), to allow it to be linked into non GNU General Public Licence (GPL) programs, while the command line utilities are licensed under the GPL. This is because it is more important to encourage standard configuration on Linux (and similar systems), than restrict use by proprietary programs.
The major version of the GPL and LGPL used is only 2, in rejection of version 3’s social engineering. Forks of Standard Config and code that links to the library may use GPL version 2, version 3, or later versions.
Found a bug? Please send the details to bugs@cinfinity.info. Mention the program being used, package (with version or release number) it came from, command line or config file options, and ideally the backtrace provided by gdb (with the bt command). Please don’t send core files (unless requested).
Any ideas for improvements can be sent to marks@cinfinity.info.
If you want to make a contribution, you can send patches to patches@cinfinity.info. I can’t guarantee I’ll accept them though, since Startd is designed to be minimalist, so for anything substantial, you should probably ask first. Patches should be in unified diff format, created with diff -u <original file> <modified file>. Nb. I don’t use git or any other source code version control system, since I believe that every package should have a single author, and that large projects should ideally be broken down into a number of independent libraries.
My name is Mark Skinner. I’m an Australian, self taught computer programmer, with a degree in engineering (specifically, computer control systems).
I write all my source code using a simple text editor, and compile and test it via the command line. My Xwindow GUI consists of a text editor, web browser and a number of terminals.
Last modified: 2022-05-15 07:09:40 UTC.