GAMGI Formats: Introduction Entities

Introduction Entities
XML Entities are a mechanism to reuse data defined elsewhere, in the same or in different files. Internal entities define blocks of data which can then be included in the same file. External entities declare local or remote files, which can then be included in the same or in other files. For example:

    <?xml version="1.0"?>
    <!DOCTYPE gml
    [
    <!ENTITY internal "<atom element='H' x='0.0' y='0.0' z='0.0'/>">
    <!ENTITY local SYSTEM "/opt/gamgi/gamgi/dat/atom/hydrogen.xml">
    <!ENTITY remote SYSTEM "http://www.gamgi.org/dat/atom/hydrogen.xml">
    ]>
    <gml>
      &internal;
      &local;
      &remote;  three atoms coming from different sources
    </gml>

Internal and external entities must start and end at the same level of hierarchy, otherwise an error is flagged, even if the whole contents is correct. The same is true for the " and ' symbols, used to distinguish the two levels of strings in the entity declarations, which must be nested correctly.

Internal and external identities can be called recursively, without limit for the number of nested levels, so data block A can call data block B which in turn can call data block C, and file A can include file B which in turn can include file C.

Internal entities must be defined before they are used, so block C must be defined before block B and block B must be defined before block A. External entities must be declared in the main file, so files B and C must be declared in file A. File A must have a header, with a version attribute, while file B and file C may have a header but cannot have a version attribute.

### Good:

    <?xml version="1.0"?>
    <!DOCTYPE gml
    [
    <!ENTITY atom "<atom element='H' x='0.0' y='0.0' z='0.0'/>">
    <!ENTITY layer "<layer> &atom; </layer>">
    <!ENTITY window "<window> &layer; </window>">
    ]>
    <gml>
      &window; a window containing a layer containing an atom
    </gml>

    main file:
    <?xml version="1.0"?>
    <!DOCTYPE gml
    [
    <!ENTITY layer "/opt/gamgi/gamgi/dat/layer/layer.xml">
    <!ENTITY atom "/opt/gamgi/gamgi/dat/atom/hydrogen.xml">
    ]>
    <gml>
      &layer; a layer containing an atom
    </gml>

    /opt/gamgi/gamgi/dat/layer/layer.xml file:
    <?xml encoding="UTF-8"?>
    <layer>
      &atom;
    </layer>

    /opt/gamgi/gamgi/dat/atom/hydrogen.xml file:
    <?xml encoding="UTF-8"?>
    <atom element='H' x='0.0' y='0.0' z='0.0'/>

### Bad:

    <?xml version="1.0"?>
    <!DOCTYPE gml
    [
    <!ENTITY layer "<layer name="base'/>'> the symbols " and ' are not correctly nested
    ]>
    <gml>
      &layer;
    </gml>

    <?xml version="1.0"?>
    <!DOCTYPE gml
    [
    <!ENTITY atom "element='H' x='0.0' y='0.0' z='0.0'/>">
    ]>
    <gml>
      <atom
        &atom; when this entity starts and ends the hierarchy is different
    </gml>

    <?xml version="1.0"?>
    <!DOCTYPE gml
    [
    <!ENTITY window "<window> &layer; </window>"> layer is not defined yet
    <!ENTITY layer "<layer> </layer>">
    ]>
    <gml>
      &window;
    </gml>

Home