README Oracc Home SEARCH DOCUMENTATION

Creative Commons License

ORACC Home


Introduction


Tutorial


Commands


Variables


Example XCF


Example result


xcf.rnc


xcf-result.rnc


Resources

XCF: XML Configuration Files

(http://oracc.org/ns/xcf/1.0)

Steve Tinney
Version of 2019-10-13

Introduction

XCF is an XML vocabulary for setting program configuration values; one day there will be a more user-friendly ASCII front end.

Tutorial

An XCF file is a collection of settings for variables that will be used by a program to decide where to get and put data and other actions. Most variables are simple name and value pairs and are set with the command:

<set var="[NAME]" to="[VALUE]"/>

In the examples, terms in uppercase and with square brackets around them are place-holders.

Some variables are more complex, and consist of collections of name and value pairs; in this case, the content of the set element is a sequence of key elements each of which has a k attribute giving the key-name and a to attribute giving the value of the key:

<set var="[NAME]">
  <key k="[KEY1]" to="[VALUE1]"/>
  <key k="[KEY2]" to="[VALUE2]"/>
</set>

Each program documents its own configurable variables; some may be given only once, some may be repeated, some may be optional. No special rules apply to repeatable variables; they are just given more than once.

One convenient feature of the XCF system is that simple variables which have been defined exactly once can be used in subsequent definitions; this means, e.g., that directory names can be built up in pieces (we call these substitution variables):

<set var="basedir" to="/home"/>
<set var="userdir" to="$basedir/cdl"/>

Substitution variables are prefixed with a dollar sign ($) and must consist only of letters, numbers and the underscore character (_). If a substitution variable is followed immediately by letters, numbers or underscores it must be enclosed in curly brackets:

<set var="basedir" to="/home/"/>
<set var="userdir" to="${basedir}cdl"/>

Commands

xcf
A configuration file is always wrapped in the xcf element which must be used with the default namespace xmlns="http://oracc.org/ns/xcf/1.0".
set
The set element always takes a var attribute giving the name of the variable whose value is being assigned. Variable names are restricted to being a sequence of one or more of the following characters: A-Z a-z 0-9 _ (underscore).
to
The to attribute always gives a value to be assigned to the variable.
key
The key element combines a naming attribute, k, with the assignment attribute to.

Variables

Simple
Simple values are always assigned as strings using the to attribute.
Table
A table is a collection of keys and values.
Substitution
Simple values used in replacements are preceded by a dollar sign and wrapped in curly brackets when necessary using the $<variable> syntax; to include a dollar sign in a to value simply double it (i.e., $$). To protect a variable name from following letters and numbers, wrap it in curly brackets.
Builtins
Some variables are predeclared:
Variable nameBuilt-in definition
cdl/usr/local/share/cdl

Example XCF

<xcf xmlns="http://oracc.org/ns/xcf/1.0">
  <set var="doc" to="$cdl/doc/XMD"/>
  <set var="catdir" to="$cdl/catalog"/>
  <set var="keydata" to="$catdir/lib/keydata.xml"/>
  <set var="logfile" to="$catdir/results/log.xml"/>
  <set var="loghtml" to="$doc/lastlog.html"/>
  <set var="sources" to="$catdir/sources"/>
  <set var="results" to="$catdir/results"/>
  <set var="catalog">
    <key k="path"     to="$sources"/>
    <key k="basename" to="P"/>
    <key k="type"     to="fxr"/>
  </set>
  <set var="catalog">
    <key k="path"     to="$sources"/>
    <key k="basename" to="Q"/>
    <key k="type"     to="fxr"/>
  </set>
</xcf>

Example result

Users don't need to know about the results of transforming the input configuration file; nor do programmers if they simply use the documented API. For the curious, though, this is the result of processing the example input given above:

<?xml version="1.0" encoding="utf-8"?>
<xr:xcf-result xmlns:xr="http://oracc.org/ns/xcf-result/1.0">
  <catalog>
    <basename>P</basename>
    <path>/usr/local/share/cdl/catalog/sources</path>
    <type>fxr</type>
  </catalog>
  <catalog>
    <basename>Q</basename>
    <path>/usr/local/share/cdl/catalog/sources</path>
    <type>fxr</type>
  </catalog>
  <catdir>/usr/local/share/cdl/catalog</catdir>
  <cdl>/usr/local/share/cdl</cdl>
  <doc>/usr/local/share/cdl/doc/XMD</doc>
  <keydata>/usr/local/share/cdl/catalog/lib/keydata.xml</keydata>
  <logfile>/usr/local/share/cdl/catalog/results/log.xml</logfile>
  <loghtml>/usr/local/share/cdl/doc/XMD/lastlog.html</loghtml>
  <results>/usr/local/share/cdl/catalog/results</results>
  <sources>/usr/local/share/cdl/catalog/sources</sources>
</xr:xcf-result>

The XDF loader serializes the loaded variables as XML in the format above to validate them against the program-specific schema if one is provided.

With the CDLG documentation system the normal way of creating XCF documentation and the validating schemas for a configuration type is within the XDF documentation for the program or subsystem. See the XDF config documentation in general and the XMD documentation on xmdmanager.plx's configuration for a working example.

xcf.rnc

default namespace = "http://oracc.org/ns/xcf/1.0"
namespace      xi = "http://www.w3.org/2001/XInclude"

start =
  element xcf { (element set { set.model } | xinclude)* }

set.model = attribute var { token } , (to | kto+)

to = (to.attr | to.elem+)

to.attr = attribute to { text }

to.elem = element to { to.attr }

kto = 
   element key { 
     attribute k { token } ,
     to.attr
   }

xinclude = element xi:include { attribute href { xsd:anyURI } }

xcf-result.rnc

This is actually just a schema template; the XDF system generates a configuration-specific schema complete with variable-typing constraints which is actually used to validate the results of loading a configuration.

default namespace = ""
namespace xr = "http://oracc.org/ns/xcf-result/1.0"

start = element xr:xcf-result { element * { text }* }

Resources


Questions about this document may be directed to the Oracc Steering Committee (osc at oracc dot org).