Conditional XML¶

Several of the pygcam XML files allow sections of the XML to be conditional on the values of configuration variables. I call this “Conditional XML”. It is implemented by reading an XML file, processing it to find <CONDITIONAL> elements, and processing these to determine what portion of the conditional XML to include in the output stream read by pygcam.

This feature allows you to choose among different modes of running your project based on the value of a configuration variable. For example, you might use different options in your project or scenario XML files depending on whether you are running individual GCAM scenarios or a Monte Carlo Simulation. Note that you can set configuration variables in ~/.pygcam.cfg, or as environment variables, which are imported into the configuration variable space with a leading $ to distinguish them from “normal” configuration variables.

The individual file types supporting Conditional XML describe the elements that can be made conditional. This file serves to consolidate the documentation of the Conditional XML syntax.

XML elements¶

The outermost element of a conditional section is <CONDITIONAL>, which takes no attributes. It must contain:

Exactly one of <TEST>, <AND>, or <OR>.
Exactly one <THEN> … </THEN> element, which contains XML to insert if the test evaluates to True
An optional <ELSE> … </ELSE> element, which can contain XML to insert if the test evaluates to False.

Example¶

In this brief example, the project file variable mcsFlag is set to either --mcs or the empty string, depending on the value of the configuration variable RunMCS.

<project name="paper1">
   <vars>
      <CONDITIONAL>
         <TEST var="RunMCS" value="1" type="bool"/>
         <THEN>
            <var name="mcsFlag">--mcs</var>
         </THEN>
         <ELSE>
            <var name="mcsFlag"></var>
         </ELSE>
      </CONDITIONAL>
    </vars>
...
</project>

<TEST>¶

This element provides the basic comparison functionality. Each <TEST> must specify a variable and a value. If not given, the comparison operator (op) is assumed to be equality. Available operators are listed below.

If not type is specified, variables are coerced to strings before comparison. If a type of str, int, float, or bool is indicated, values are coerced to that type before comparison.

Attribute	Required	Default	Values
var	yes	(none)	text
value	yes	(none)	text
op	no	‘==’	(see below)
type	no	‘str’	‘str’, ‘int’, ‘float’, ‘bool’

The comparison operators all compare the value of configuration variable var (A) to the given value (B). Note that all environment variables are loaded into the configuration dictionary and are accessible by name, prefixed by $ as in a UNIX shell.

Note that in XML you should specify < and > as < and %gt;, which can be a nuisance, thus FORTRAN text style operators are also provided.

=, ==, or eq: A equals B
!= or ne: A does not equal B
< or lt: A is less than B
<= or le: A is less than or equal to B
> or gt: A is greater than B
>= or ge: A is greater than or equal to B

Example¶

<TEST var="RunMCS" value="1" type="bool"/>

<AND>¶

The <AND> element takes no attributes. It can contain any number of <TEST>, <AND>, or <OR> elements. It evaluates to True if all of its direct children elements evaluate to True. The evaluation of elements stops as soon as one evaluates to False.

Example¶

The following example requires both that variable RunMCS has a “True” value, and that OtherVar equals “foo”.

<AND>
  <TEST var="RunMCS" value="1" type="bool"/>
  <TEST var="OtherVar" value="foo"/>
</AND>

<OR>¶

The <OR> element takes no attributes. It can contain any number of <TEST>, <AND>, or <OR> elements. It evaluates to True if any of its direct children elements evaluate to True. The evaluation of elements stops as soon as one evaluates to True.

Example¶

The following example requires that variable RunMCS has a “True” value, or, that OtherVar equals “foo” (or both).

<OR>
  <TEST var="RunMCS" value="1" type="bool"/>
  <TEST var="OtherVar" value="foo"/>
</OR>