diff --git a/docs-mini/README.conditions b/docs-mini/README.conditions new file mode 100644 index 000000000..10d9d040b --- /dev/null +++ b/docs-mini/README.conditions @@ -0,0 +1,206 @@ +CONDITIONS IN FLIGHTGEAR PROPERTY FILES + +Written by David Megginson, david@megginson.com +Last modified: $Date$ + +This document is in the Public Domain and comes with NO WARRANTY! + + +1. Introduction +--------------- + +Some FlightGear property files contain conditions, affecting whether +bindings or animations are applied. For example, the following +binding will apply only when the /sim/input/selected/engine[0] +property is true: + + + + /sim/input/selected/engine[0] + + property-assign + /controls/starter[0] + true + + +Conditions always occur within a property subtree named "condition", +which is equivalent to an "and" condition. + + +2. Comparison Operators +----------------------- + +The simplest condition is "property". It resolves as true when the +specified property has a boolean value of true (i.e. non-zero, etc.) +and false otherwise. Here is an example: + + + /sim/input/selected/engine[0] + + +For more sophisticated tests, you can use the "less-than", +"less-than-equals", "greater-than", "greater-than-equals", "equals", +and "not-equals" comparison operators. These all take two operands, +either two "property" operands or one "property" and one "value" +operand, and return true or false depending on the result of the +comparison. The value of the second operand is always forced to the +type of the first; for example, if you compare a string and a double, +the double will be forced to a string and lexically compared. If one +of the operands is a property, it is always assumed to be first. Here +is an example of a comparison that is true only if the RPM of the +engine is less than 1500: + + + + /engines/engine[0]/rpm + 1500 + + + + +3. Boolean Operators +-------------------- + +Finally, there are the regular boolean operators "and", "or", and +"not". Each one surrounds a group of other conditions, and these can +be nested to arbitrary depths. Here is an example: + + + + + + /engines/engine[0]/rpm + 1500 + + + /engines/engine[0]/rpm + 2500 + + + /engines/engine[0]/running + + + +The top-level "condition" is an implicit "and". + + +4. Approximating if...else +-------------------------- + +There is no equivalent to the regular programming 'else' statement in +FlightGear conditions; instead, each condition separately must take +the others into account. For example, the equivalent of + + if (x == 3) ... else if (y == 5) ... else ... + +in FlightGear conditions is + + + + /x + 3 + + + + /y + 5 + + + +and then + + + + /y + 5 + + + + /x + 3 + + + +and then + + + + + /x + 3 + + + + + /y + 5 + + + +It's verbose, but it works nicely within existing property-based +formats and provides a lot of flexiblity. + + +5. Syntax Summary +----------------- + +Here's a quick syntax summary: + +* ... + + Contains one or more subconditions, all of which must be true. + +* ... + + The top-level container for conditions, equivalent to an "and" group + +* ... + + Contains two properties or a property and value, and is true if the + properties have equivalent values. + +* ... + + Contains two properties or a property and a value, and is true if + the second property or the value has a value greater than the first + property. + +* ... + + Contains two properties or a property and a value, and is true if + the second property or the value has a value greater than or equal + to the first property. + +* ... + + Contains two properties or a property and a value, and is true if + the second property or the value has a value less than the first + property. + +* ... + + Contains two properties or a property and a value, and is true if + the second property or the value has a value less than or equal + to the first property. + +* ... + + Contains one subcondition, which must not be true. + +* ... + + Contains two properties or a property and value, and is true if the + properties do not have equivalent values. + +* ... + + Contains one or more subconditions, at least one of which must be + true. + +* ... + + The name of a property to test. + +* ... + + A literal value in a comparison.