Difference between revisions of "VariablesWML/How to use variables"
(Created page with '== 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 su…') |
(Added page 1 and two) |
||
| Line 2: | Line 2: | ||
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. | 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 === | ===Under the burning sun === | ||
| − | == Variable definitions == | + | ==== 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. | 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 : | 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’. | 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 == | + | ==== Variables creation and manipulation ==== |
Even if WML variables contents have no precise types1, we shall discuss two kinds: | 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 single value, like a number, a character string | ||
: - variables holding a compound value, i.e. a pack of single values. | : - variables holding a compound value, i.e. a pack of single values. | ||
| − | They’re often called containers in the documentation. | + | They’re often called containers in the documentation. Simple variables are created using the tag '''[set_variable]''': |
[set_variable] | [set_variable] | ||
name=simpleVariable | name=simpleVariable | ||
| Line 18: | Line 18: | ||
[/set_variable] | [/set_variable] | ||
The tag defines the name and the value of the variable. | The tag defines the name and the value of the variable. | ||
| − | Next, we can access the variable value | + | |
| + | Next, we can access the variable value using the variable name prefixed with a dollar sign $. | ||
[modify_unit] | [modify_unit] | ||
[filter] | [filter] | ||
| Line 25: | Line 26: | ||
moves=$simpleVariable | moves=$simpleVariable | ||
[/modify_unit] | [/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: | + | 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] | [modify_unit] | ||
[filter] | [filter] | ||
| Line 33: | Line 36: | ||
[/modify_unit] | [/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). | 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: | For example: | ||
[set_variable] | [set_variable] | ||
| Line 44: | Line 48: | ||
[/set_variable] | [/set_variable] | ||
We shall not use '''[set_variable]''' tag anymore. Instead, we shall use the '''VARIABLE''' shortcut: | We shall not use '''[set_variable]''' tag anymore. Instead, we shall use the '''VARIABLE''' shortcut: | ||
| + | |||
____________________________ | ____________________________ | ||
:<sup>1)</sup> In computering words, they are not '''strongly typed.''' | :<sup>1)</sup> In computering words, they are not '''strongly typed.''' | ||
Revision as of 18:16, 18 September 2013
Contents
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:
____________________________
- 1) In computering words, they are not strongly typed.