docs-mini/README.conditions

   1 CONDITIONS IN FLIGHTGEAR PROPERTY FILES
   2
   3 Written by David Megginson, david@megginson.com
   4 Last modified: $Date$
   5
   6 This document is in the Public Domain and comes with NO WARRANTY!
   7
   8
   9 1. Introduction
  10 ---------------
  11
  12 Some FlightGear property files contain conditions, affecting whether
  13 bindings or animations are applied.  For example, the following
  14 binding will apply only when the /sim/input/selected/engine[0]
  15 property is true:
  16
  17   <binding>
  18    <condition>
  19     <property>/sim/input/selected/engine[0]</property>
  20    </condition>
  21    <command>property-assign</command>
  22    <property>/controls/starter[0]</property>
  23    <value type="bool">true</value>
  24   </binding>
  25
  26 Conditions always occur within a property subtree named "condition",
  27 which is equivalent to an "and" condition.
  28
  29
  30 2. Comparison Operators
  31 -----------------------
  32
  33 The simplest condition is "property".  It resolves as true when the
  34 specified property has a boolean value of true (i.e. non-zero, etc.)
  35 and false otherwise.  Here is an example:
  36
  37   <condition>
  38    <property>/sim/input/selected/engine[0]</property>
  39   </condition>
  40
  41 For more sophisticated tests, you can use the "less-than",
  42 "less-than-equals", "greater-than", "greater-than-equals", "equals",
  43 and "not-equals" comparison operators.  These all take two operands,
  44 either two "property" operands or one "property" and one "value"
  45 operand, and return true or false depending on the result of the
  46 comparison.  The value of the second operand is always forced to the
  47 type of the first; for example, if you compare a string and a double,
  48 the double will be forced to a string and lexically compared.  If one
  49 of the operands is a property, it is always assumed to be first.  Here
  50 is an example of a comparison that is true only if the RPM of the
  51 engine is less than 1500:
  52
  53   <condition>
  54    <less-than>
  55     <property>/engines/engine[0]/rpm</property>
  56     <value>1500</value>
  57    </less-than>
  58   </condition>
  59
  60
  61 3. Boolean Operators
  62 --------------------
  63
  64 Finally, there are the regular boolean operators "and", "or", and
  65 "not".  Each one surrounds a group of other conditions, and these can
  66 be nested to arbitrary depths.  Here is an example:
  67
  68   <condition>
  69    <and>
  70     <or>
  71      <less-than>
  72       <property>/engines/engine[0]/rpm</property>
  73       <value>1500</value>
  74      </less-than>
  75      <greater-than>
  76       <property>/engines/engine[0]/rpm</property>
  77       <value>2500</value>
  78      </greater-than>
  79     <or>
  80     <property>/engines/engine[0]/running</property>
  81    </and>
  82   </condition>
  83
  84 The top-level "condition" is an implicit "and".
  85
  86
  87 4. Approximating if...else
  88 --------------------------
  89
  90 There is no equivalent to the regular programming 'else' statement in
  91 FlightGear conditions; instead, each condition separately must take
  92 the others into account.  For example, the equivalent of
  93
  94   if (x == 3) ... else if (y == 5) ... else ...
  95
  96 in FlightGear conditions is
  97
  98   <condition>
  99    <equals>
 100     <property>/x</property>
 101     <value>3</value>
 102    </equals>
 103    <not>
 104     <equals>
 105      <property>/y</property>
 106      <value>5</value>
 107    </not>
 108   </condition>
 109
 110 and then
 111
 112   <condition>
 113    <equals>
 114     <property>/y</property>
 115     <value>5</value>
 116    </equals>
 117    <not>
 118     <equals>
 119      <property>/x</property>
 120      <value>3</value>
 121    </not>
 122   </condition>
 123
 124 and then
 125
 126   <condition>
 127    <not>
 128     <equals>
 129      <property>/x</property>
 130      <value>3</value>
 131     </equals>
 132    </not>
 133    <not>
 134     <equals>
 135      <property>/y</property>
 136      <value>5</value>
 137    </not>
 138   </condition>
 139
 140 It's verbose, but it works nicely within existing property-based
 141 formats and provides a lot of flexiblity.
 142
 143
 144 5. Syntax Summary
 145 -----------------
 146
 147 Here's a quick syntax summary:
 148
 149 * <and>...</and>
 150
 151   Contains one or more subconditions, all of which must be true.
 152
 153 * <condition>...</condition>
 154
 155   The top-level container for conditions, equivalent to an "and" group
 156
 157 * <equals>...</equals>
 158
 159   Contains two properties or a property and value, and is true if the
 160   properties have equivalent values.
 161
 162 * <greater-than>...</greater-than>
 163
 164   Contains two properties or a property and a value, and is true if
 165   the second property or the value has a value greater than the first
 166   property.
 167
 168 * <greater-than-equals>...</greater-than-equals>
 169
 170   Contains two properties or a property and a value, and is true if
 171   the second property or the value has a value greater than or equal
 172   to the first property.
 173
 174 * <less-than>...</less-than>
 175
 176   Contains two properties or a property and a value, and is true if
 177   the second property or the value has a value less than the first
 178   property.
 179
 180 * <less-than-equals>...</less-than-equals>
 181
 182   Contains two properties or a property and a value, and is true if
 183   the second property or the value has a value less than or equal
 184   to the first property.
 185
 186 * <not>...</not>
 187
 188   Contains one subcondition, which must not be true.
 189
 190 * <not-equals>...</not-equals>
 191
 192   Contains two properties or a property and value, and is true if the
 193   properties do not have equivalent values.
 194
 195 * <or>...</or>
 196
 197   Contains one or more subconditions, at least one of which must be
 198   true.
 199
 200 * <property>...</property>
 201
 202   The name of a property to test.
 203
 204 * <value>...</value>
 205
 206   A literal value in a comparison.