GAMGI Formats: Introduction Identifiers

Introduction Identifiers
In GML, every non-root element can have a name, an identifier and at least a parent.

### name

Name attributes in GML files correspond to the object names used in GAMGI, which exist only to help users identify the objects. All objects in GAMGI have an alphanumeric name, given by users, to help object identification and selection. This name is shown everywhere an object needs to be identified, including dialogs, statubars and object trees. This name is not used by GAMGI itself for identification purposes or others (although GAMGI cross checks object names and numbers to ensure that they are consistent).

    Example: <atom ... name="Si"/> (default Si name)
    Allowed values: 20 alphanumeric characters maximum
    (defined in GAMGI_ENGINE_TOKEN) (optional)

### id

An id is used to uniquely identify an object when importing a file and is discarded as soon as the operation is completed. Apart from this condition of uniqueness, id is an alphanumeric attribute, exactly as name. There is no default for this parameter. Bonded atoms must have an id, so bonds can point to them.

Identifier attributes must be unique for each import or export operation, as they are used by GAMGI to relate elements that may not even be in the same file. Although GAMGI uses numbers as identifier attributes when exporting files, these are not related in any way with the object numbers used internally in GAMGI to identify the objects. Identifier attributes are required only when the respective elements must be referenced somewhere else, most notably in bonded atoms that must be referenced by the bonds.

    Example: <atom ... id="si1"/> (no default)
    Allowed values: 20 alphanumeric characters maximum
    (defined in GAMGI_ENGINE_TOKEN)
    (optional, required if bonded)

### parent

Usually the parent of a given object is identified by file context, as the object that immediately encloses it in the XML hierarchy. However the parent object can be explicitely indicated using the parent parameter, which points to the id parameter of the parent object.

    Example: <atom ... parent="layer1"/> (no default)
    Allowed values: 20 alphanumeric characters maximum
    (defined in GAMGI_ENGINE_TOKEN) (optional)

Objects can reference parents that are only defined later, perhaps in another file, or perhaps in another file included by another file, without any limit to the level of depth of nested files. For example, a bond in a file can reference atoms that are defined in a HTTP file, fetched from somewhere in the planet. Configuration data elements have fixed parents, so identifiers don't apply to them.

We note that an object can only reference other objects that are inside the block defined by its own parent. This important restriction was introduced to disable all kinds of weird referencing possibilities that are left open with global identifiers, where everything can point to everything, potentially destroying the strict hierarchy that XML files should have, and making it difficult for GAMGI and users alike to check and understand the objects true hierarchy.

Moreover, this mechanism can never be used to validate an object that has an impossible object enclosing it by pointing it to a correct parent. The XML hierarchical position of an object in a file must always be possible, independently of its parameters.

This automatically prevents, for example, atoms belonging to different layers from being bonded together, as bonds in one layer cannot see atoms that are in the other layer. To see both atoms, bonds would have to belong to the common window, which is forbiden, because windows cannot own bonds, only layers.

### Good:

    <gml>
      <bond parent1="1" parent2="2"/> bond can reference parents that are defined later
      <group>
        <atom id="1"/> atom is inside the bond scope (the current layer block)
      </group>
      <atom id="2"/>
    </gml>

### Bad:

    <gml>
      <atom id="1"/>
      <atom id="2"/>
      <group>
      <bond parent1="1" parent2="2"/> atoms are outside the bond scope (the group block)
      </group>
    </gml>

Home