VariablesWML/How to use variables

WML Variables HowTo (or Descent into Darkness)

In this document, we shall try to explain WML variables and their use with some details. We’ll start under the burning sun of lawful ordinary use, but, step by step, we shall go deeper in the shadows of necromancy, exploring undocumented features and hidden pits as we may. The first part should be understandable by any beginner, but the last one most probably requires a good WML understanding.

Under the burning sun

Variable definitions

This section and the next one can be skipped if you already know what variables are and how to use them. Variables are some kind of container a programmer can use to store pieces of information (s)he needs to manipulate : numbers, names, sentences, and anything else. In most programming languages, variables must be declared before they can be used. Declaration is an instruction giving a name (used later to refer to the variable) and a type, which defines the kind of content of the variable (number, characters strings, and so on). Later in the program, instructions can be used to store and retrieve the content of the container, which is most often called the value of the variable. In WML, variables need no declaration and their value have no precise type¹⁾. This means a new variable will be created at the first time the programmer stores something in it. And that (s)he can store anything in it. Variables use memory, so it’s good practice to clear them when they’re not needed anymore. Variables names are freely chosen by the programmer with some restrictions. They should not be the name of a language instruction (keyword) or operator. In WML, you can use quite any name or sentence to name a variable, but you shouldn’t if you want to shun subtle problems. A classical rule is :

- variable name should begin with a letter

- variable names should only contain letters (not accented) and numbers and the underscore _ character.

No spaces, no accented letters, no special characters, no minus and plus signs, etc… Those names are always safe and correctly interpreted by the engine as variables names. Note that some special characters are forbidden in variable names: $ , . | {} [] = because they have a special meaning we shall see later. I would strongly suggest to avoid common tags names like “event” “side” and too long names like: “name_of_the_guy_who_killed_the_orc_on_last_turn” which is not the same as: “name_of_the_gyu_who_killed_the_orc_on_last_turn”, but it’s not really obvious at first glance. It’s a common error to type wrongly a variable name: in WML this don’t rise any error message, but the variable will have no value, giving most probably what you don’t expect. Last but not least, variables names are case sensitive: in other words, ‘aVar’ is not the same as ‘avar’.

Variables creation and manipulation

Even if WML variables contents have no precise types1, we shall discuss two kinds:

- variables holding a single value, like a number, a character string

- variables holding a compound value, i.e. a pack of single values.

They’re often called containers in the documentation. Simple variables are created using the tag [set_variable]:

[set_variable]
    name=simpleVariable
    value=36
[/set_variable]

The tag defines the name and the value of the variable.

Next, we can access the variable value using the variable name prefixed with a dollar sign $.

[modify_unit]
    [filter]
        id=$unit.id
    [/filter]
    moves=$simpleVariable
[/modify_unit]

This sets the moves of the unit to 36 since simpleVariable holds 36.

When the line is executed, the value 36 is substituted to $simpleVariable, so it works as if we wrote:

[modify_unit]
    [filter]
        id=$unit.id
    [/filter]
    moves=36
[/modify_unit]

Using the same tag, we can change the value of simpleVariable, or make some arithmetic (see the tag documentation for the whole list).

For example:

[set_variable]
    name=simpleVariable
    sub=30
[/set_variable]

will change the value to 6 of course. We can even set the variable to another value type:

[set_variable]
    name=simpleVariable
    value="Delfador the Great"
[/set_variable]

We shall not use [set_variable] tag anymore. Instead, we shall use the VARIABLE shortcut:

____________________________

¹⁾ In computering words, they are not strongly typed.

{VARIABLE simpleVariable "Delfador the Great"}

stands for:

[set_variable]
    name=simpleVariable
    value="Delfador the Great"
[/set_variable]

We shall not use the arithmetic variations of set_variable' either. Instead we shall use the formulaAI syntax which is much more natural. Instead of:

[set_variable]
     name=simpleVariable
     value=35
[/set_variable]
[set_variable]
      name=simpleVariable
      add=$anotherVariable
[/set_variable]

we shall write:

[set_variable]
    name=simpleVariable
    value="$(35 + $anotherVariable)"
[/set_variable]

# or

{VARIABLE simpleVariable "$(35 + $anotherVariable)"}

The formulaAI syntax is easy to use, the important thing is to always put the formula in this sequence: “$( … here comes the formula … )” In other words, $simpleVariable can be written everywhere you want to use the value of simpleVariable. Clearing variables can be done using the [clear_variable] tag:

[clear_variable]
    name=simpleVariable
[/clear_variable]

# or using the following macro to delete more than one variable {CLEAR_VARIABLE simpleVariable,anotherOne,count}²⁾

Containers

What is a container ? It is a variable holding more than a simple value. A good example is the

                                                                                             ____________________________

²⁾ Please note the CLEAR_VARIABLE macro will not work if your variables names contain spaces or commas. It’s one good reason to avoid them.