ConditionalWML - Revision history

Voris: Redirecting to renamed ConditionalActionsWML page.

2009-03-22T00:19:38Z

Redirecting to renamed ConditionalActionsWML page.

Voris: Initial creation. Split off from InternalActionsWML since it seemed to deserve standalone documentation.

2009-03-21T23:32:22Z

Initial creation. Split off from InternalActionsWML since it seemed to deserve standalone documentation.

New page

{{WML Tags}}

Conditional WML is used to describe conditions must be met before an action can take place and to encapsulate the actions which will take place if the conditions are met and, in some cases, what actions will take place if they are not met.

== Condition Tags ==

These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions|Conditional Actions]].

; [have_unit]
: A unit with greater than zero hit points matching this filter exists.
:* [[StandardUnitFilter]] '''*''': Selection criteria. <br />'''* Note:''' ''Does '''not''' check for matching units in the recall list!''
:* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

; [have_location]
: A location matching this filter exists.
:* [[StandardLocationFilter]]: Selection criteria.
:* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".

; [variable]
: Test the value of a WML variable (see [[VariablesWML]]) against another value.
:* '''name''': The name of the variable to test.
:* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:
:** '''contains''': ''$name'' contains this string value.
:** '''equals''': ''$name'' is equal (string wise) to this value.
:** '''not_equals''': ''$name'' is not equal (string wise) to this value.
:** '''numerical_equals''': ''$name'' is equal (numerically) to this value.
:** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.
:** '''greater_than''': ''$name'' is greater than this value.
:** '''greater_than_equal_to''': ''$name'' is greater than or equal to this value.
:** '''less_than''': ''$name'' is less than this value.
:** '''less_than_equal_to''': ''$name'' is less than or equal to this value.
:** '''boolean_equals''': ''$name'' has an equivalent boolean value. '''*'''
:** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value. '''*'''<br />'''*''' When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.<br />These values are evaluated as ''false'': '''no''', '''false''', '''off''', '''0''', and '''0.0'''<br />These values are evaluated as ''true'': '''yes''', '''true''', '''on''', '''1''', and '''0.1''' (and any other non-zero number)

=== Meta Condition Tags ===

These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.

; [and]
: A condition which must evaluate to true in addition to any others. Useful as a bracket for complex conditions, but not strictly necessary.
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.

; [or]
: A condition which, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one '''[or]''' condition is true, the conditions have been met for an action to take place. (See [[AdvancedConditionalWML|Example]])
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.

; [not]
: A condition which reverses the evaluation of the contained condition(s).
:* [[#Condition Tags|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.

== Conditional Actions ==

These internal actions describe actions that should be executed only if certain conditions (in almost all cases described using [[#Condition Tags|Condition Tags]]) are met.

=== [if] ===

Executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.

* '''[then]''': Contains a set of action tags which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.

* '''[else]''': Contains a set of action tags which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.

=== [switch] ===

The '''[switch]''' tag is a special case because it does not use [[#Condition Tags|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable.

* '''variable''': The name of the variable to check.
* '''[case]''': Case tag which forms a block containing:
** '''value''': The value to test the variable's value against.
** <Action WML>: Action WML ([[InternalActionsWML]], [[DirectActionsWML]], [[InterfaceActionsWML]], etc.) to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
* '''[else]''': Else tag which forms a block of action WML ([[InternalActionsWML]], [[DirectActionsWML]], [[InterfaceActionsWML]], etc.) to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.

Example usage:
[switch]
variable=foo
[case]
value="A"
... WML if foo=A ...
[/case]
[case]
value="B"
... WML if foo=B ...
[/case]
[else]
... WML if not foo=A nor foo=B ...
[/else]
[/switch]

=== [while] ===

Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags|conditions]] are no longer met. Executes a maximum of 1024 iterations per invocation.

* [[#Condition Tags|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.

* '''[do]''': contains actions that should be executed repeatedly until some condition is false.

The '''[while]''' tag is useful for iterating over an array.
An array is a list of values.
The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.
Note that if '''number''' is the value of the variable '''variable''',
the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.

==== 'FOREACH' Macro ====
This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the '''FOREACH''' and '''NEXT''' macros documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].

==== 'REPEAT' Macro ====
This macro simplifies the use of a '''[while]''' tag to execute the same action(s) repeatedly for a specified number of times. To use it, use the '''REPEAT''' macro documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].

== See Also ==
* [[VariablesWML]]
* [[InternalActionsWML]]
* [[DirectActionsWML]]
* [[InterfaceActionsWML]]
* [[EventWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

← Older revision		Revision as of 00:19, 22 March 2009
Line 1:		Line 1:
−	~~{{WML Tags}}~~	+	#REDIRECT [[ConditionalActionsWML]]
−
−	Conditional WML is used to describe conditions must be met before an action can take place and to encapsulate the actions which will take place if the conditions are met and, in some cases, what actions will take place if they are not met.
−
−	~~== Condition Tags ==~~
−
−	~~These tags describe conditions which must be met before an action can take place. Some or all of them are used in the various [[#Conditional Actions\|Conditional Actions]].~~
−
−	~~; [have_unit]~~
−	~~: A unit with greater than zero hit points matching this filter exists.~~
−	~~:* [[StandardUnitFilter]] '''''': Selection criteria. <br />''' Note:''' ''Does '''not''' check for matching units in the recall list!''~~
−	~~:* '''count''': ''(Optional)'' If used, a number of units equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".~~
−
−	~~; [have_location]~~
−	~~: A location matching this filter exists.~~
−	~~:* [[StandardLocationFilter]]: Selection criteria.~~
−	~~:* '''count''': ''(Optional)'' If used, a number of locations equal to the value must match the filter. Accepts a number, range, or comma separated range. If not used, the default value is "1-99999".~~
−
−	~~; [variable]~~
−	~~: Test the value of a WML variable (see [[VariablesWML]]) against another value.~~
−	~~:* '''name''': The name of the variable to test.~~
−	~~:* ''<comparison>'': '''One''' of the following keys must be used to compare the value of the named variable, represented as ''$name'' below, against another value:~~
−	~~:** '''contains''': ''$name'' contains this string value.~~
−	~~:** '''equals''': ''$name'' is equal (string wise) to this value.~~
−	~~:** '''not_equals''': ''$name'' is not equal (string wise) to this value.~~
−	~~:** '''numerical_equals''': ''$name'' is equal (numerically) to this value.~~
−	~~:** '''numerical_not_equals''': ''$name'' is not equal (numerically) to this value.~~
−	~~:** '''greater_than''': ''$name'' is greater than this value.~~
−	~~:** '''greater_than_equal_to''': ''$name'' is greater than or equal to this value.~~
−	~~:** '''less_than''': ''$name'' is less than this value.~~
−	~~:** '''less_than_equal_to''': ''$name'' is less than or equal to this value.~~
−	~~:** '''boolean_equals''': ''$name'' has an equivalent boolean value. '''*'''~~
−	:** '''boolean_not_equals''': ''$name'' does not have an equivalent boolean value. ''''''<br />'''''' When values are evaluated as boolean values they are checked to see if they are ''false'' or ''true''.<br />These values are evaluated as ''false'': '''no''', '''false''', '''off''', '''0''', and '''0.0'''<br />These values are evaluated as ''true'': '''yes''', '''true''', '''on''', '''1''', and '''0.1''' (and any other non-zero number)
−
−	~~=== Meta Condition Tags ===~~
−
−	These tags aren't really conditions, themselves. Instead they are wrapped around condition tags to group them into multiple conditions that must all be met, lists of conditions that only one must be met, or conditions that must not be met. These are handled in order in any combination you can think of. One important thing to remember is if you are using '''[or]''' tags, the first conditional statement should ''not'' have an '''[or]''' tag wrapped around it.
−
−	~~; [and]~~
−	~~: A condition which must evaluate to true in addition to any others. Useful as a bracket for complex conditions, but not strictly necessary.~~
−	~~:* [[#Condition Tags\|Condition Tags]]: If these evaluate to true, the '''[and]''' tag evaluates to true.~~
−
−	~~; [or]~~
−	: A condition which, if it evaluates to true, is all that is necessary for the conditions to be met. In other words, if all other conditions are false, but one '''[or]''' condition is true, the conditions have been met for an action to take place. (See [[AdvancedConditionalWML\|Example]])
−	~~:* [[#Condition Tags\|Condition Tags]]: If these evaluate to true, the '''[or]''' tag evaluates to true.~~
−
−	~~; [not]~~
−	~~: A condition which reverses the evaluation of the contained condition(s).~~
−	~~:* [[#Condition Tags\|Condition Tags]]: If these evaluate to true, the '''[not]''' tag evaluates to false. If these evaluate to false, the '''[not]''' tag evaluates to true.~~
−
−	~~== Conditional Actions ==~~
−
−	~~These internal actions describe actions that should be executed only if certain conditions (in almost all cases described using [[#Condition Tags\|Condition Tags]]) are met.~~
−
−	~~=== [if] ===~~
−
−	~~Executes actions only if conditions described in the contained [[#Condition Tags\|conditions]] are met.~~
−
−	* [[#Condition Tags\|Condition Tags]]: Conditions which must be met for the actions in the '''[then]''' tag to be executed.
−
−	* '''[then]''': Contains a set of action tags which should be executed if all conditions evaluate as true ''or'' if any single '''[or]''' tag evaluates as true.
−
−	* '''[else]''': Contains a set of action tags which should be executed if any condition evaluates as false ''and'' '''all''' of the '''[or]''' tags evaluate as false.
−
−	~~=== [switch] ===~~
−
−	~~The '''[switch]''' tag is a special case because it does not use [[~~#~~Condition Tags\|Condition Tags]] to control whether actions are performed. Instead, it executes different sets of actions based on the value of a variable.~~
−
−	* '''variable''': The name of the variable to check.
−	* '''[case]''': Case tag which forms a block containing:
−	** '''value''': The value to test the variable's value against.
−	** <Action WML>: Action WML ([[InternalActionsWML]], [[DirectActionsWML]], [[InterfaceActionsWML]], etc.) to execute if the variable matches the value. (The rest of the '''[case]''' block after the '''value''' attribute.)
−	* '''[else]''': Else tag which forms a block of action WML ([[InternalActionsWML]], [[DirectActionsWML]], [[InterfaceActionsWML]], etc.) to execute if no '''[case]''' block contains a '''value''' matching the value of the '''variable'''.
−
−	~~Example usage:~~
−	~~[switch]~~
−	~~variable=foo~~
−	~~[case]~~
−	~~value="A"~~
−	~~... WML if foo=A ...~~
−	~~[/case]~~
−	~~[case]~~
−	~~value="B"~~
−	~~... WML if foo=B ...~~
−	~~[/case]~~
−	~~[else]~~
−	~~... WML if not foo=A nor foo=B ...~~
−	~~[/else]~~
−	~~[/switch]~~
−
−	~~=== [while] ===~~
−
−	Like the '''[if]''' tag, executes actions only if conditions described in the contained [[#Condition Tags\|conditions]] are met. Additionally, the '''[while]''' tag ''continues'' to execute the actions until the contained [[#Condition Tags\|conditions]] are no longer met. Executes a maximum of 1024 iterations per invocation.
−
−	* [[#Condition Tags\|Condition Tags]]: Conditions which must be met for the actions in the '''[do]''' tag to be executed.
−
−	* '''[do]''': contains actions that should be executed repeatedly until some condition is false.
−
−	~~The '''[while]''' tag is useful for iterating over an array.~~
−	~~An array is a list of values.~~
−	~~The ''number''th value in the array '''array''' is stored in the WML variable '''''array''[number]'''.~~
−	~~Note that if '''number''' is the value of the variable '''variable''',~~
−	~~the expression '''$''array''[$variable]''' will return the ''number''th value in ''array''.~~
−
−	~~==== 'FOREACH' Macro ====~~
−	This macro simplifies the use of a '''[while]''' tag to create a ''for-each'' iteration format. This is useful, for example, when you want to iterate over each row in a table. To use it, use the '''FOREACH''' and '''NEXT''' macros documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].
−
−	~~==== 'REPEAT' Macro ====~~
−	This macro simplifies the use of a '''[while]''' tag to execute the same action(s) repeatedly for a specified number of times. To use it, use the '''REPEAT''' macro documented [http://www.wesnoth.org/macro-reference.xhtml#file:utils.cfg here].
−
−	~~== See Also ==~~
−	* [[VariablesWML]]
−	* [[InternalActionsWML]]
−	* [[DirectActionsWML]]
−	* [[InterfaceActionsWML]]
−	* [[EventWML]]
−	* [[ReferenceWML]]
−
−	[[~~Category: WML Reference~~]]