<fragment> Element Reference

The <fragment> element defines a sequence of XDDL elements that can later be referenced by a <structure> or another <fragment>. It provides a means of reuse.

Detail

%fragment definitions have an id attribute. This id must be unique among all fragments in the same file. These definitions can later be referenced by <fragment> elements with the href attribute.

This will in effect replace the referring <fragment> with the contents of the <fragment> defintion.

The id and href attributes are mutually exclusive.

Fragment definitions must appear as children of the <xddl> element and before the <structure> element.

Example

The following two files are effectively identical, and can be parsed with the same message:

    <?xml version="1.0" encoding="iso-8859-1" ?>
    <xddl>
     <structure>
      <field name="A" length="8"/>
      <field name="B" length="8"/>
      <field name="C" length="8"/>
     </structure>
    </xddl>

    no_frag.xddl

    # idm no_frag.xddl 010203

    Name                           Length Value    Hex        Description 
    A                              8      1        01         
    B                              8      2        02         
    C                              8      3        03         

    <?xml version="1.0" encoding="iso-8859-1" ?>
    <xddl>
      <fragment id="Frag">
        <field name="A" length="8"/>
        <field name="B" length="8"/>
        <field name="C" length="8"/>
      </fragment>
     <structure>
      <fragment href="#Frag"/>
     </structure>
    </xddl>

    frag.xddl

    # idm frag.xddl 010203

    Name                           Length Value    Hex        Description 
    A                              8      1        01         
    B                              8      2        02         
    C                              8      3        03         

Using this mechanic, the same fragment can be reused multiple times:

    <?xml version="1.0" encoding="iso-8859-1" ?>
    <xddl>
      <fragment id="Frag">
        <field name="A" length="8"/>
        <field name="B" length="8"/>
        <field name="C" length="8"/>
      </fragment>
     <structure>
      <fragment href="#Frag"/>
      <fragment href="#Frag"/>
      <fragment href="#Frag"/>
     </structure>
    </xddl>

    multi_frag.xddl

    # idm multi_frag.xddl 010203040506070809

    Name                           Length Value    Hex        Description 
    A                              8      1        01         
    B                              8      2        02         
    C                              8      3        03         
    A                              8      4        04         
    B                              8      5        05         
    C                              8      6        06         
    A                              8      7        07         
    B                              8      8        08         
    C                              8      9        09         

Expressions Within Fragments

Expressions within fragments are resolved with the context they are used. For example:

    <?xml version="1.0" encoding="iso-8859-1" ?>
    <xddl>
     <fragment id="f1">
      <switch expr="MessageID">
        <case value="1">
          <field name="x" length="8"/>
        </case>
        <default>
          <field name="y" length="8"/>
        </default>
      </switch>
     </fragment>

     <structure>
      <field name="MessageID" length="8"/>
      <fragment href="#f1"/>
     </structure>
    </xddl>

    resolve.xddl

    # idm resolve.xddl 01FF

    Name                           Length Value    Hex        Description 
    MessageID                      8      1        01         
    x                              8      255      FF         

In the above example, fragment f1 requires a MessageID field to be defined (it is used by the <switch> element's expr attribute). Before the fragment is referenced in the <structure> element, we see the MessageID <field> is defined, satisfying this requirement. Referencing the f1 fragment without a MessageID field first being defined would result in a parse error.

External Fragments

It is possible to insert <fragment> elements from other documents. For example, we can save the above XDDL fragment to the file frags.xddl:

    <?xml version="1.0" encoding="iso-8859-1" ?>
    <xddl>
     <fragment id="f1">
      <switch expr="MessageID">
        <case value="1">
          <field name="x" length="8"/>
        </case>
        <default>
          <field name="y" length="8"/>
        </default>
      </switch>
     </fragment>
    </xddl>

    frags.xddl

Then another file can use it:

    <?xml version="1.0" encoding="iso-8859-1" ?>
    <xddl>
     <structure>
      <field name="MessageID" length="8"/>
      <fragment href="frags.xddl#f1"/>
     </structure>
    </xddl>

    fragref.xddl

Recursive Fragment

As you may have noticed, there are similarities between fragments and macros in the C/C++ langauges. However, unlike macros, a <fragment> may reference other fragments, or even itself.

Here is an example of common messaging construct. As long as the more bit is set, an additional 7 bits of data is read. We can parse messages of this form with a recursive <fragment>:

    <?xml version="1.0" encoding="iso-8859-1" ?>
    <xddl>
     <comment>Recursive Fragment</comment>
     <fragment id="recurse">
      <field name="more" length="1"/>
      <field name="data" length="7"/>
      <if expr="more">
        <fragment href="#recurse"/>
      </if>
     </fragment>
     <structure>
      <fragment href="#recurse"/>
     </structure>
    </xddl>

    recurse.xddl

    # idm recurse.xddl @10000001100000101000001100000000

    Name                           Length Value    Hex        Description 
    more                           1      1        01         
    data                           7      1        01         
    more                           1      1        01         
    data                           7      2        02         
    more                           1      1        01         
    data                           7      3        03         
    more                           1      0        00         
    data                           7      0        00