Using GXML: Variables

by Josh Carter < josh@multipart-mixed.com >
May 10, 2001


Basic Variable Substitution

The syntax of a variable is as follows, for a variable called "name":

    %%%name%%%

How exactly the value of "name" is determined is somewhat complicated. XML specifies a standard format for attributes of an element, as follows:

    <element
        name = "Fred"
        date = "July 4, 2034"
    >

    (this is the content of the element; "name" and "date" are
    in scope here.)

    </element>

The way everyone's used to seeing XML attributes written, however, is using enclosing elements, e.g.:

    <element>
        <name>Fred</name>
        <date>July 4, 2034</date>
    </element>

GXML supports both styles. Thus both of these work:

    <element name="Fred">

    name is %%%name%%%
    (will be "Fred")

    </element>

    <element>
        <name>Fred</name>

        name is %%%name%%%
    </element>

Variable Scoping

This is easy stuff if you're used to programming. I'll tell you the formal rules first, but you can skip to the examples if you like. The following rules apply for determining if a attribute is in scope, that is, accessible through a variable:

It's probably easiest to see with an example. First, where attributes are declared in the start tag:

    <manager name="Fred">

        <employee name="Bob">
            name is %%%name%%%
            (will be "Bob" here)
        </employee>

        name is %%%name%%%
        (will be "Fred" here)
    </manager>

    name is %%%name%%%
    (will be undefined here)

Now for the case where attributes are elements themselves:

    <manager>
      <name>Fred</name>

        <employee>
            <name>Bob</name>
            <name>Bo3b</name>
            
            (multiple personalities, maybe?)

            name is %%%name%%%
            (will be "Bob" here)
        </employee>

        name is %%%name%%%
        (will be "Fred" here)
    </manager>

    name is %%%name%%%
    (will be undefined here)

Bending the Scoping Rules

I'm sure there are some CS hard-core types who would get infuriated over this feature, but GXML will allow you to get around some scoping constraints. You can "drill down," as it were, into elements which are within your scope to get enclosed values which aren't. Again, this is easier seen than described:

    <manager>
      <name>Fred</name>

        <employee>
            <name>Bob</name>
        </employee>
    </manager>

    name is %%%name%%%
    (will be undefined here because it's not in scope, but:)

    name is %%%manager:name%%%
    (will be "Fred")

    name is %%%manager:employee:name%%%
    (will be "Bob")

Thus the syntax is using colons to indicate a drill-down into a given element. In practice I've only found this feature useful in conjunction with the "foreach" command, but maybe you'll put GXML to some other use (or abuse) that requires this.


Default Values

Variables can have default values specified by "-default" appended to their name. Default values will only be used once all other rules for resolving a variable have been tried. Thus:

    <org-chart name-default="unnamed person">

    <manager name="Fred">

        <employee name="Bob">
            name is %%%name%%%
            (will be "Bob" here)
        </employee>

        name is %%%name%%%
        (will be "Fred" here)
    </manager>

    name is %%%name%%%
    (will be "unnamed person")

    <org-chart>

Default values are especially useful when using templates, since a template can use many variables but also specify defaults, enabling the user to only specify things that are different from the defaults.

On to Templates!

Back to the GXML Guide

Back to the gxml2html Guide


Copyright (c) 2001-2002 Josh Carter