How to read a DDLm dictionary
A DDLm dictionary provides a series of definitions for datanames. Each definition is contained within a "save frame", which is simply a block of text encompassed by
save_xyz _definition.id '_my.definition' _description.text 'This is what it means' ... save_
In this example, we say that the 'save frame name' is
xyz. Conventionally the save frame name is the same as the item being defined, but this is not required.
All of a dictionary's save frames are listed inside a single enclosing "data block", as required by the CIF syntax. Attributes in this data block (outside all of the save frames) relate to the dictionary as a whole, including version information, edit history, and dictionary name. So the basic structure of a DDLm dictionary looks like this:
#\#CIF_2.0 ####################### # The FROB dictionary # ####################### data_frob_dic _dictionary.name frob _dictionary.version 1.1 ... #Other dictionary information save_def1 ... save_ save_def2 ... save_ ## Many more save frame definitions # Possibly more attributes for the enclosing data block # End
Attributes within each of the save frames create semantic relationships between the definitions, as well as defining the datanames. The most important relationship is the 'category' that a dataname belongs to.
DDLm requires that all datanames belong to "categories". Categories are also defined within save frames. Just as a dataname is assigned to a category, categories themselves are assigned to a 'parent' category, with the exception of the single
Head category which acts as the parent of all categories within the dictionary.
Categories come in two main flavours:
Set categories, and
Loop categories, as stipulated by the
_definition.class attribute in a category definition.
Datanames belonging to a
Set category may not appear in a loop, that is, they take only a single value in a CIF datablock. Datanames in
Loop categories may be appear in loops. When a
Loop category is the child of another
Loop category, datanames in each category may be freely mixed in a single loop, or else datanames from each category may be separated into separate loops (a separate document describes in more detail the nature of this mixing). A
Set category may not be the child of a
Loop category. There is no particular meaning for any other parent-child combinations of
Basic attributes for assigning meaning to categories
The following main attributes are used to describe a category:
Head(once per dictionary)
Name of parent category
Name of this category
Conventionally, name of this category (unused)
Loop categories only - the values of this dataname are unique and so can be used to index the loop. This is the dataname used by dREL when using the
Loop categories only - the values of these datanames are collectively unique and can be used to index the loop. Either contains a single dataname which is given in
_category.key_id, or multiple datanames, none of which are the one given in
The following attributes must be provided in all dataname definitions.
The dataname as it will appear in a data file
When this definition was last edited
A human-readable definition for the dataname
The category that this dataname belongs to
The identifier of this dataname within a category
Whether or not values for this dataname appear in compound data types: 'Single' for a plain value, otherwise 'List' etc.
The type of the data values: Int, Real etc.
A dataname within a category is assigned an 'object id'. This allows a dataname to be referred to in
category.object notation, which is useful in dREL scripts (see below). While the actual dataname that appears in a datafile (as defined in
_definition.id) may also be written in this notation, it is not strictly required.
More information on attributes
The complete list of attributes can be found in file
ddl.dic, itself a DDLm dictionary. Mandatory attributes are listed in the
_dictionary_valid.application loop found towards the end of the file.
Both categories and dataname definitions can set the value of
_method.expression to an expression in dREL. For a dataname, this describes how values of the dataname may be derived from the values of other datanames. For categories, this describes how keys of the category (and, optionally, other dataname values in the category) can be determined from the values of other datanames. For example, the geom_bond category can create a list of interatomic bond lengths based on bonding radii contained in the file.