How to read a DDLm dictionary

Overall syntax

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_ tokens:

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

Semantic structure

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.

Categories

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 Set and Loop categories.

Basic attributes for assigning meaning to categories

The following main attributes are used to describe a category:

_definition.scope

Must be Category

_definition.class

Set, Loop, or Head (once per dictionary)

_name.category_id

Name of parent category

_name.object_id

Name of this category

_definition.id

Conventionally, name of this category (unused)

_category.key_id

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 category[key] construction.

_category_key.name

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 _category.key_id

Dataname definitions

The following attributes must be provided in all dataname definitions.

_definition.id

The dataname as it will appear in a data file

_definition.update

When this definition was last edited

_description.text

A human-readable definition for the dataname

_name.category_id

The category that this dataname belongs to

_name.object_id

The identifier of this dataname within a category

_type.container

Whether or not values for this dataname appear in compound data types: 'Single' for a plain value, otherwise 'List' etc.

_type.contents

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.

dREL

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.