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.
=
,==
, oreq
: A equals B!=
orne
: A does not equal B<
orlt
: A is less than B<=
orle
: A is less than or equal to B>
orgt
: A is greater than B>=
orge
: 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>