## 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 entity, as follows:

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

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

        </entity>

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

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

GXML supports both styles. Thus both of these work:

        <entity name="Fred">

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

        </entity>

        <entity>
            <name>Fred</name>

            name is %%%name%%%
        </entity>

## 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:

- For attributes declared in the start tag:
  - The start tag must enclose the entity where the variable is used. It does not need to be the immediate parent; the given start tag may be several levels up.
  - If there are several possible candidates, the most closely enclosing one will be chosen.
- For attributes that are sub-entities:
  - The attribute entity must be a peer of where the variable is used, or be enclosed by a common parent.
  - If there are several possible candidates, the most closely enclosing one will be chosen.
  - If there are several possible candidates at the same level (i.e. peers of each other), the first will be taken.

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 entities 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 entities 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 entity. 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