TUCS Users' Guide

About this document

This document is intended for end users of TUCS, that is users of programs that use TUCS. If you are a developer and want to know about using TUCS in you project, please consult the Developers' Guide.

If you have specific questions, you should also check out the FAQ.

This document is intended to be easily readable, which means that some details are omitted, and the definitions are sometimes sloppy. For more exact definitions see the Specifications.

What is TUCS?

TUCS stands for The Unified Configuration System. It is a system library that manages persistent, hierarchical configuration information, providing an abstract interface for applications to access these configurations. Let's expand this more.

Applications often need to 'remember' some information between sessions. The common solution is to save this information into a configuration file, and retrieve it during the next session. Sometimes configuration files contain essential parameters for the application to function properly, and users have to edit these files to change some parameters. Most of the applications manage their own configuration files, each using its own file format, file locations, and strategy.

TUCS provides a service to manage these configurations in a common way. Under TUCS, a configuration is a collection of settings, with a hierarchical structure: some settings are groups, which contain further settings. All the settings on a system form a single tree, and the settings of one application is a subtree of this. For example 'app.myeditor.font.size' is a setting of the application MyEditor.

TUCS can store the settings in text files resembling typical configuration files, but it can use other storage methods. An application which wants to read/write configurations using TUCS need not known the exact location or format of these files, but it should talk to TUCS using only the abstract API, and let TUCS manage the lower-level details.

Currently TUCS has two storage layers: multiple simple text files (the default), and a single text file. There are other possible storage layers: binary file/files, XML files, remote network server, a database, etc.

TUCS has some other features worthy of mentioning:

- handling of scopes. It is a common scenario that a user overrides the system-wide default value of a setting. TUCS handles such cases automatically, determining which value to use, and which one to set.

- standalone smart configuration editors, which can edit configurations in the absence of the creating application, but still using meta-information stored in the settings.

An Example

Let's start with a simple settings example. This example shows the settings of a hypothetical text editor MyEdit. It uses the format used by the simple text file storage layer.

# MyEdit Config File

font group {
 family string courier
 size   int    12
 dpi    int    75
}

print group {
 command    string   "enscript -2rG"
 selection  boolean  false
 raw        boolean  true
}

recently_opened_files list string {
 /home/adam/doc.rtf
 /home/adam/frams/sources/testconv.cpp
 /home/adam/frams/sources/test5.cpp
 /home/adam/frams/gdk/list.h
 /home/adam/frams/gdk/list.cpp
}

toolbar_on  boolean true
default_url string  "ftp://localhost/welcome.msg"
mailcmd     string  "=mail -s \"%s\""

# I changed this to yellowish, I don't like white (joe)
bgcolor       string  "#ffffdd"

backupcopies  boolean  true
statusbar     boolean  true
width         integer  726
wordwrap      boolean  true
fillcolumn    integer  79
usefillcolumn boolean  true
height        integer  528
toolbar_position string Left
forecolor     string   "#000000"

Settings

Under TUCS, the basic unit for configurations is a setting. In short, a setting is a name-value pair: it has a unique name used to refer to it, and it has a value. TUCS organises all the settings in a single hierarchical structure, by grouping settings into subgroups. This structure is analoguous to a file hirarchy in a file system. (In this analogy, settings correspond to files, and groups correspond to directories. And much as in the file system a directory is a special file, a setting group is a special setting.)

The full name of a setting reflects its place in the hierarchy. For example 'app.myeditor.font.size' is a setting which belongs to the subgroup 'app.myeditor.font', which belongs to the group 'app.myeditor', and so on.

Each setting also has a type. A setting can be a container setting (which contains other settings), or a simple setting. A simple setting can be of one of the basic types: string, decimal integer number, character, boolean, real number, binary data. A container setting is either a group or a list.

The name of a setting is used to identify the setting within its group. The name must be a single word, e.g. 'size'. A name can contain letter, digits, and underscore ('_'), but must start with a letter (exception: lists). Setting names are case-insensitive, so 'LineWidth' and 'Linewidth' all refer to the same setting.

The full name of a setting, called its locator, is formed by joining the names of all its supergroups using a dot ('.'). If setting 'size' is in group 'font' which is in 'myeditor' which is in 'app', then its full name is 'app.myeditor.font.size'. Names can also be used relative to another setting: for example, relative to the group 'app.myeditor' the given setting is 'indenting.linewidth'.

TUCS Users' Guide

About this document

What is TUCS?

An Example

Settings

Storage Layers

Meta settings

TUCS Utilities