SyntaxWML - Revision history

Celtic Minstrel: /* Tag and Attribute Structures */ Note case sensitivity

2024-02-23T03:36:23Z

‎Tag and Attribute Structures: Note case sensitivity

Celtic Minstrel: Fix formerly-internal link

2024-02-22T03:46:48Z

Fix formerly-internal link

Celtic Minstrel: Move section to VariablesWML

2024-02-22T03:45:11Z

Move section to VariablesWML

Show changes

Celtic Minstrel: /* Scalar */ Note the existence of boolean values

2024-02-22T03:23:53Z

‎Scalar: Note the existence of boolean values

Celtic Minstrel: /* Variable Substitution */ Formula substitution is described above, not below (also add a direct link to it)

2024-02-21T14:44:24Z

‎Variable Substitution: Formula substitution is described above, not below (also add a direct link to it)

Celtic Minstrel: /* Special Attribute Values */ Fix the anchors

2024-02-21T14:41:48Z

‎Special Attribute Values: Fix the anchors

Celtic Minstrel: /* Special Attribute Values */ Add anchors that other things can link to

2024-02-21T14:38:02Z

‎Special Attribute Values: Add anchors that other things can link to

Celtic Minstrel: /* Variable Substitution */

2024-02-21T14:31:26Z

‎Variable Substitution

Celtic Minstrel: /* Variable Substitution */ Formatting fixup and consistency

2024-02-21T14:29:57Z

‎Variable Substitution: Formatting fixup and consistency

Celtic Minstrel: /* Variable Substitution */ Rewrite the description in an attempt to be more complete

2024-02-21T14:28:11Z

‎Variable Substitution: Rewrite the description in an attempt to be more complete

← Older revision		Revision as of 03:36, 23 February 2024
Line 29:		Line 29:
	''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.		''Keys should not be confused with variables!'' A common mistake among beginners is to make up undocumented key names. Instead, consult the WML Reference to find allowed key names for each tag. For a list of all tags with links to their documentation, see the "WML Tags" navigation box.

−	Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they cannot contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed. A key or tag name beginning with a digit or even consisting of entirely digits is permitted.	+	Also, tag and key names follow a special format. They will contain only alphanumeric characters and underscores; in particular, they cannot contain <code>+</code>, <code>-</code>, or whitespace. The values, however, may contain such characters when needed. A key or tag name beginning with a digit or even consisting of entirely digits is permitted. Tag and key names are case sensitive.

@@ Line 76: / Line 76: @@
 * {{Anchor|value concatenation|2='''key = "value1" + "value2"'''}}: ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left.  To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes. If two non-quoted values are concatenated, they will have a space inserted between them, but if either value is quoted, no space will be inserted.
 * {{Anchor|escaping quotes|2='''key = "quoted ""double quoted value"" value"'''}}: ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
-* {{Anchor|variable substitution basics|2='''key = $variable'''}}: a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just  a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].''
+* {{Anchor|variable substitution basics|2='''key = $variable'''}}: a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just  a special case of general variable substitution, as variables can be substituted within other values. See [[VariablesWML]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].''
 * {{Anchor|formula substitution|2='''key = "$(formula-expression)"'''}}: a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
 * {{Anchor|macro-protected string|2='''key = <<value>>'''}}: similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string. This can also be combined with the translatable mark, in case curly braces are needed in translatable text.

@@ Line 92: / Line 92: @@
 === Kinds of Variables ===
 ==== Scalar ====
-A scalar variable can store a single string or number.
+A scalar variable can store a single string, number, or boolean value.
 <syntaxhighlight lang="wml">
@@ Line 98: / Line 98: @@
      name=my_variable
      value="sample value"
 [/set_variable]
 </syntaxhighlight>

@@ Line 156: / Line 156: @@
 A dollar sign at the end of a string or followed by a character that's not an identifier will be left alone. If it's followed by a pipe, the pipe will be removed.
-Variable substitutions (and also formula substitutions, see below for more details) in a string are processed one at a time from right to left. That is, the engine finds the last dollar sign, substitutes that variable in, and then moves on to the next one in the resulting string. This means that the result of one variable substitution can affect the next one.
+Variable substitutions (and also formula substitutions, see [[#formula substitution|above]] for more details) in a string are processed one at a time from right to left. That is, the engine finds the last dollar sign, substitutes that variable in, and then moves on to the next one in the resulting string. This means that the result of one variable substitution can affect the next one.
 For example, consider the substitution <code>$house_$colour|.title</code>. First the "colour" variable is substituted in. If it contains "blue", the result is <code>$house_blue.title</code>, so the game will then look for a container variable called "house_blue" and substituted in its "title" key. On the other hand, if the "colour" variable contains "red", the result of the first substitution is <code>$house_red.title</code>, so the engine will instead look for a container variable called "house_red" and substitute in ''its'' "title" key.

@@ Line 72: / Line 72: @@
 Although an attribute's value can be just text corresponding to the function of its key, a value can also be encoded in many other ways, each with a specific purpose.
-* {{Anchor|quoted values|'''key = "value"'''}}: a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break without quotes would otherwise end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped &ndash; without quotes, all leading and trailing spaces would be removed, and internal runs of spaces would be replaced by a single space. It is never wrong to use quotes with correct WML.
+* {{Anchor|quoted values|2='''key = "value"'''}}: a ''quoted value'' is a value surrounded by quotes. This is often unnecessary as single-line values are typically interpreted as intended. However, quotes are required in order to specify multiple-line values (a line break without quotes would otherwise end the value). Quotes may also be required to cancel the special meaning of other characters, and they prevent spaces from being stripped &ndash; without quotes, all leading and trailing spaces would be removed, and internal runs of spaces would be replaced by a single space. It is never wrong to use quotes with correct WML.
-* {{Anchor|translatable strings|'''key = _"value"'''}}: a ''[[translatable]] value'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data.  See [[TranslationsWML]] and [[GettextForWesnothDevelopers]] for more information.
+* {{Anchor|translatable strings|2='''key = _"value"'''}}: a ''[[translatable]] value'' is a value that is subject to translations, and should be used for all text intended to be shown to a player (most notably seen in [story], [message], and the name= key in unit definitions). A translatable value is surrounded by quotes and preceded by an underscore (_). In terms of WML syntax, it behaves very much like a quoted value, other than being unsuitable for [[ConditionalActionsWML#Condition_Tags|comparisons to other values]]. Translatable values are intended for display on the screen, not for internal data.  See [[TranslationsWML]] and [[GettextForWesnothDevelopers]] for more information.
-* {{Anchor|value concatenation|'''key = "value1" + "value2"'''}}: ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left.  To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes. If two non-quoted values are concatenated, they will have a space inserted between them, but if either value is quoted, no space will be inserted.
+* {{Anchor|value concatenation|2='''key = "value1" + "value2"'''}}: ''string concatenation'' is performed with the plus sign (<code>+</code>). If a plus sign appears outside quotes in a value, it means that the string/value on its right will be appended to the string/value on its left.  To have an actual plus sign in a value, the string containing the <code>+</code> character must be surrounded by quotes (a quoted value or a translatable value). Quotes are not strictly necessary around the pre-concatenated values, but they are advisable so that it is easy to tell where the values begin and end and to spot some kinds of mistakes. If two non-quoted values are concatenated, they will have a space inserted between them, but if either value is quoted, no space will be inserted.
-* {{Anchor|escaping quotes|'''key = "quoted ""double quoted value"" value"'''}}: ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
+* {{Anchor|escaping quotes|2='''key = "quoted ""double quoted value"" value"'''}}: ''doubled quotes'' can be used to create quote marks within a quoted or translatable value. The doubled quote mark in the value produces one quote mark in the stored data and does not terminate the quoted value. (These do not necessarily need to be used in pairs.)
-* {{Anchor|variable substitution basics|'''key = $variable'''}}: a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just  a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].''
+* {{Anchor|variable substitution basics|2='''key = $variable'''}}: a ''variable substitution'' sets the key to the value of the indicated WML variable. This is indicated by the dollar sign (<code>$</code>) and is really just  a special case of general variable substitution, as variables can be substituted within other values. See [[#Variable_Substitution|below]] for more information on values based on WML variables. (Note that some keys require their data to be a variable name, not the variable's value; in that case there would be no dollar sign.) ''Variable substitution is supported in only a few contexts, such as in [[IntroWML]] and [[EventWML]].''
-* {{Anchor|formula substitution|'''key = "$(formula-expression)"'''}}: a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
+* {{Anchor|formula substitution|2='''key = "$(formula-expression)"'''}}: a ''formula expression'' sets the key to the value of the processed formula. This is indicated by a dollar sign (<code>$</code>) followed by a parenthesized expression. See [[Wesnoth Formula Language]] for more information on formula basics, data types, and built-in functions. Quotes around the formula are not strictly necessary in all cases, but they are advisable, particularly since quotes are the only way to use a plus sign (<code>+</code>) within a formula (without quotes, the plus sign represents string concatenation). ''Formula expressions are only supported where variable substitution is supported.''
-* {{Anchor|macro-protected string|'''key = <<value>>'''}}: similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string. This can also be combined with the translatable mark, in case curly braces are needed in translatable text.
+* {{Anchor|macro-protected string|2='''key = <<value>>'''}}: similar to a quoted value but stronger: the value is hidden from the [[PreprocessorRef|preprocessor]], which will see all text therein as literal. Useful with [[LuaWML]] or whenever a literal curly brace ("{", a US-ASCII 0x7B) is needed in any text string. This can also be combined with the translatable mark, in case curly braces are needed in translatable text.
 == Variables ==

@@ Line 150: / Line 150: @@
 When writing scenario events ([[EventWML]]) and filters, a scalar variable can generally be substituted in the right-hand side of any '''key=value''' assignment. To do this, enclose the full variable name to be queried between a dollar sign (<code>$</code>) and a pipe (<code>|</code>). The variable name should be the entire dot-separated path, where each component is an identifier (consisting of English letters, Arabic digits, and underscores) optionally followed by a pair of square brackets containing either a number or another substitution. The number represents the array index. When such a substitution appears in the text, the content which has previously been put into this variable name is used instead of the name of the variable.
-In certain situations, the <code>|</code> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no <code>|</code>, variable names span identifier characters (as defined in the preceding paragraph), balanced square brackets and some periods. Doubled periods, final periods (followed by a non-alphanumeric character), and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using <code>$|</code>), then it will be replaced by just <code>$</code>, giving you an easy way to include a dollar sign in an interpolated string.
+In certain situations, the <code>|</code> that marks the end of the variable name to be queried can be omitted. The exact rule is: if there is no <code>|</code>, variable names span identifier characters (as defined in the preceding paragraph), balanced square brackets and some periods. Doubled periods, final periods (followed by a non-identifier character), and some periods that would result in an illegal variable name will not be included. If the variable name ends up being empty (e.g. when using <code>$|</code>), then it will be replaced by just <code>$</code>, giving you an easy way to include a dollar sign in an interpolated string.
 {{DevFeature1.13|2}} If you want to substitute a default value when the variable is uninitialized or empty, add a question mark (<code>?</code>) followed by the default value after the variable name, eg <code>$varname?default text|</code>. In this case, the pipe (<code>|</code>) is required. The default text can be anything at all, as long as it doesn't contain a pipe. (There exists no mechanism to escape a pipe so it can be included in the default text.)

@@ Line 147: / Line 147: @@
 === Variable Substitution ===
-Whenever using a $ in front of a variable name, the content which has previously been put into this variable name is used instead of the name of the variable. For example:
 <syntaxhighlight lang="wml">
 [event]
@@ Line 163: / Line 179: @@
 The WML code above will cause Delfador to say "Hello, Konrad... How are you?" on turn 1.
 ==== Literal Mode ====
-There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <tt>$</tt> will not have special significance. The following places use the literal mode:
+There are a few places where the substitution mode is literal. In these places, attribute value are used exactly as provided, nothing is substituted, and the <code>$</code> will not have special significance. The following places use the literal mode:
-* value of '''literal=''' inside [set_variable]
+* The value of '''literal=''' inside [set_variable]
-* contents of '''[literal]''' inside [set_variables]
+* The contents of '''[literal]''' inside [set_variables]
-* the special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start
+* The special [[SyntaxWML#The_.5Bvariables.5D_tag|[variables]]] tag, used to give initial values to many variables upon scenario start
 * In general, anything that's not nested inside '''[event]''', '''[command]''', '''[tunnel]''', '''[story]''', or a filter. For example, the '''[unit_type]''' tag cannot use variable substitution (except in filters).