Difference between revisions of "SyntaxWML"

From The Battle for Wesnoth Wiki
(Empty Values: This section was not correct. The key=$empty work-around does not work with the format= attribute of the set_variable tag, for example. (I wonder if to_variable= would also work?))
(Tag and Attribute Structures: Note case sensitivity)
 
(93 intermediate revisions by 21 users not shown)
Line 1: Line 1:
 +
{{Translations}}
 
{{WML Tags}}
 
{{WML Tags}}
Wesnoth syntax has two basic elements: ''tags'' and ''attributes''.
 
Further, ''attributes'' consist of ''keys'' and ''values''.
 
Tag names and keys cannot contain whitespace.
 
Any line beginning with a pound ('''#''') sign is considered by
 
WML as a comment, except for preprocessor declarations beginning
 
with #.
 
* '''[tag-name] ''data'' [/tag-name]''' is a tag.  Tags are used to partition information.  A ''top level'' tag is one that is not inside any other tag.  Each top level tag describes something about the game.  Different tags work differently.  For information about how a certain tag works, see [[ReferenceWML]].
 
* '''[+tag-name] ''data'' [/tag-name]''' means that ''data'' will be considered as part of the data for the most recent [''tag-name''] tag.  The ''data'' of '''[+tag-name]''' will be considered as coming after all data in '''[tag-name]''', so attributes of '''[+tag-name]''' will replace attributes of the original '''[tag-name]'''.
 
* '''''key=value newline''''' is an ''attribute'', or an assignment of a value to a key.  When this line is processed, the value of ''key'' for the tag that the attribute is in is set or changed to ''value''.  All text from '=' until the end of the line is considered to be part of ''value''. Note that ''key'' is not a WML variable (with the exception of [[VariablesWML]]); the value it is set to has a use which is determined by C++ code, not WML code.  In order to change the value of a WML variable, you need to use '''[set_variable]''' (see [[InternalActionsWML]]).  '''There should be no space between the key and the '=' symbol!'''  If there is whitespace, the attribute assignment is ignored. Note that ''key'' should contain only alphanumerics or underscores (''a-zA-Z0-9_''); no ''+'' or ''-'' characters are allowed.
 
* '''''key1,key2,key3=value1,value2,value3 newline''''' is a multiple assignment.  If there are extra keys, they will be set to an empty value.  If there are extra values the last key will be set to the comma separated list of all remaining values.  It is the same as
 
  key1=value1
 
  key2=value2
 
  key3=value3
 
  
Although a value can be just text corresponding to a function of
+
The '''Wesnoth Markup Language''' ('''WML''') is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML.
its key (these values are displayed in quotes (') in
+
For guidelines on keeping these files easily human-readable, see [[ConventionsWML#Indentation|ConventionsWML]].
[[ReferenceWML]]), a value can also be encoded:
 
* '''"''multiple-line-value''"''' a multiple-line value must be enclosed in quotes, to prevent it being interpreted as a single-line value.  Note that ''multiple-line-value'' doesn't have to have multiple lines; it can simply be a single-line value enclosed in quotes for clarity.
 
* '''''_ "text"''''' is a ''translatable'' value.  ''text'' is English (US) text that will be displayed in-game at some point.  Gettext (see [[GetText]]) is used to determine what to display if English (US) is not the current language.
 
* '''''value-1 + value-2''''' can be used to concatenate two different strings. If you want to have a value that actually has a plus sign ('''+''') in it, you need to enclose the string containing the '''+''' character in quotes (see '''''"multiple-line-value"''''' above).
 
* '''''$variable-name''''' a ''variable'' value depends on the value of the WML variable ''variable-name''.  See [[VariablesWML]] for more information on WML-variable based values.
 
  
=== Empty Values ===
+
== Tag and Attribute Structures ==
Usually, wesnoth does not distinguish between a key that has not been provided, and a key that has been assigned an empty value.
 
  
Some tags permit a workaround to provide a key with an empty value. You can write
+
WML has a syntax containing two basic elements: ''tags'' and ''attributes''. Furthermore, ''attributes'' consist of ''keys'' and ''values''. For example:
  key=$empty
+
<syntaxhighlight lang="wml">
where 'empty' is a WML variable that has not been assigned yet. (This is not technically an empty value, and hence wesnoth will notice that this key has been provided, but will become empty during variable substitution.)
+
[tag]
 +
    key=value
 +
[/tag]
 +
</syntaxhighlight>
  
However, some tags actually do the variable substitution ''before'' they check if the value is empty. This applies to most commands in events, including the crucial [[InternalActionsWML|set_variable]] tag. For example, consider the problem of copying the value another_variable to some_variable. You might write
+
''Tags'' are used to partition information, while the data is contained in the ''attributes''. ''Keys'' identify the type of data to be stored and ''values'' are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each <code>key=value</code> line within a tag, the attribute identified by <code>key</code> has its data set to <code>value</code>.
  [set_variable]
+
Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.
     name=some_variable
+
<syntaxhighlight lang="wml">
     format="$another_variable"
+
[parent_tag]
     # does not work with another_variable is empty
+
     key1=value1
  [/set_variable]
+
     [child_tag]
 +
        key2=value2
 +
     [/child_tag]
 +
[/parent_tag]
 +
</syntaxhighlight>
  
The above example looks okay, because the format= key does not seem empty. However, if another_variable was empty, then wesnoth perform the substitution, resulting in format="" being an empty key. Then wesnoth will ignore the set_variable command, and some_variable would retain its value instead of becoming empty.
+
Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "[[ReferenceWML#WML_toplevel_tags|top-level tags]]" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored. The [[SchemaWML|WML schema]] defines what is allowed and where. Although it's not designed to be read by humans, you can [[ValidationFAQ|use it to automatically detect]] if you've done something wrong even in contexts where unrecognized keys and tags would be ignored, though it still won't work in contexts where you're allowed to define the contents however you like.
  
The workaround for an empty format= key in this case is to write
+
''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.
  [clear_variable]
 
    name=some_variable
 
  [/clear_variable]
 
  [set_variable]
 
    name=some_variable
 
    format="$another_variable"
 
  [/set_variable]
 
  
If another_variable is empty, then wesnoth will ignore the set_variable command, but some_variable will be empty because of the previous clear_variable command. (Another workaround might be to use the to_variable= key instead of the format= key.)
+
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.
  
=== Example ===
 
[scenario]
 
        id=Elves Besieged
 
        [side]
 
                side,gold=1,100
 
        [/side]
 
        [+side]
 
                recruit=Elvish Fighter,Elvish Archer
 
        [/side]
 
[/scenario]
 
In this example, [scenario] is a top level tag.  When these
 
lines are read, WML will know that there is a scenario with
 
the ID "Elves Besieged".  Later, when WML is told to play
 
that scenario, it will read the [side] tag and give 100 gold
 
to side 1.  Then it will read the [+side] tag.
 
It interprets this tag as belonging to side 1, since the
 
most recent [side] belonged to side 1.  So the [+side] tag
 
allows side 1 to recruit Elvish Fighters and Elvish Archers.
 
(Then it will crash, as the leader of side 1 has no unit type.
 
But this isn't really important.)
 
  
Notes: Normally the order and indentation of attributes and tags
+
=== Tag Amendment Syntax ===
does not matter, as long as the levels within tags are not changed.
 
So the above example could have been written:
 
[scenario]
 
          [side]
 
                  gold=100
 
                  side=1
 
          [/side]
 
          id=Elves Besieged
 
[/scenario]
 
Data inside tags should be separated with tabbing; see [[ConventionsWML]].
 
  
 +
Inserting a plus sign (<code>+</code>) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.
 +
<syntaxhighlight lang="wml">
 +
[tag]
 +
    key=value
 +
[/tag]
 +
[+tag]
 +
    key=value
 +
[/tag]
 +
</syntaxhighlight>
 +
 +
* All keys in the ''+tag'' will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].
 +
 +
* Any child tags of the ''+tag'' will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."
 +
 +
* It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.
 +
 +
=== Multiple Assignment Syntax ===
 +
 +
It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.
 +
<syntaxhighlight lang="wml">
 +
[tag]
 +
    key1,key2,key3=value1,value2,value3
 +
[/tag]
 +
</syntaxhighlight>
 +
would be the same as:
 +
<syntaxhighlight lang="wml">
 +
[tag]
 +
    key1=value1
 +
    key2=value2
 +
    key3=value3
 +
[/tag]
 +
</syntaxhighlight>
 +
* If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.
 +
* It is recommended not to use this syntax with keys which normally interpret commas specially (such as x and y in a [[StandardLocationFilter]]), to avoid confusion on which key receives which value. However, using <code>x,y=12,10</code> for single coordinates is widely used and is an exception to the recommendation.
 +
 +
=== Special Attribute Values ===
 +
 +
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|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|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|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 [[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.
 +
 +
== Comments ==
 +
 +
Comments are indicated by a pound sign (<code>#</code>) unless in double quotes. Unless the line forms a valid [[PreprocessorRef#Preprocessor_directives|preprocessor directive]], all text after the pound sign will be ignored by the WML engine. Note that if the beginning of the line is a valid preprocessor directive, which is then followed by ''another'' pound sign, the second pound sign will still be interpreted as a comment character. For example, this works:
 +
<syntaxhighlight lang="wml">
 +
#ifdef FOO
 +
#endif # FOO
 +
</syntaxhighlight>
 +
Whether or not doing so is a good idea is a stylistic choice.
 +
 +
It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.
 +
 +
Specially-formatted comments are frequently used to give commands to the Wesnoth [[MaintenanceTools|maintenance tools]] to suppress false positives and enhance their coverage, as well as for adding explanatory comments for [[GettextForWesnothDevelopers#Marking_up_strings_in_WML|translatable strings]].
  
 
== See Also ==
 
== See Also ==
  
 
* [[PreprocessorRef]]
 
* [[PreprocessorRef]]
 +
* [[ConventionsWML]]
 +
* [[SavefileWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Latest revision as of 03:36, 23 February 2024

[edit]WML Tags

A:

abilities, about, achievement, achievement_group, add_ai_behavior, advanced_preference, advancefrom, advancement, advances, affect_adjacent, ai, allied_with, allow_end_turn, allow_extra_recruit, allow_recruit, allow_undo, and, animate, animate_unit, animation, aspect, attack (replay, weapon), attack_anim, attacks (special, stats), avoid;

B:

base_unit, background_layer, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, checkbox, choice, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_palette, color_range, command (action, replay), continue, credits_group, criteria;

D:

damage, death, deaths, default, defend, defends, defense, delay, deprecated_message, destination, difficulty, disable, disallow_end_turn, disallow_extra_recruit, disallow_recruit, do, do_command, drains, draw_weapon_anim;

E:

editor_group, editor_music, editor_times, effect, else (action, animation), elseif, endlevel, end_turn (action, replay), enemy_of, engine, entry (credits, options), era, event, experimental_filter_ability, experimental_filter_ability_active, experimental_filter_specials, extra_anim;

F:

facet, facing, fake_unit, false, feedback, female, filter (concept, event), filter_adjacent, filter_adjacent_location, filter_attack, filter_attacker, filter_base_value, filter_condition, filter_defender, filter_enemy, filter_location, filter_opponent, filter_own, filter_owner, filter_radius, filter_recall, filter_second, filter_second_attack, filter_self, filter_side, filter_student, filter_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, found_item, for, foreach, frame;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, has_achievement, have_location, have_unit, heal_on_hit, heal_unit, healed_anim, healing_anim, heals, hide_help, hide_unit, hides;

I:

idle_anim, if (action, animation, intro), illuminates, image (intro, terrain), init_side, insert_tag, inspect, item, item_group;

J:

jamming_costs, join;

K:

kill, killed;

L:

label, language, leader, leader_goal, leadership, leading_anim, levelin_anim, levelout_anim, lift_fog, limit, literal, load_resource, locale, lock_view, lua;

M:

male, menu_item, message, micro_ai, missile_frame, modification, modifications, modify_ai, modify_side, modify_turns, modify_unit, modify_unit_type, move, move_unit, move_unit_fake, move_units_fake, movement_anim, movement costs, movetype, multiplayer, multiplayer_side, music;

N:

not, note;

O:

object, objective, objectives, on_undo, open_help, option, options, or;

P:

part, petrifies, petrify, place_shroud, plague, poison, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, progress_achievement, put_to_recall_list;

R:

race, random_placement, recall (action, replay), recalls, recruit, recruit_anim, recruiting_anim, recruits, redraw, regenerate, remove_event, remove_item, remove_object, remove_shroud, remove_sound_source, remove_time_area, remove_trait, remove_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, screen_fade, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_achievement, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, objective, set_menu_item), show_objectives, side, skirmisher, slider, slow, snapshot, sound, sound_source, source (replay, teleport), special_note, specials, split, stage, standing_anim, statistics, status, store_gold, store_items, store_locations, store_map_dimensions, store_reachable_locations, store_relative_direction, store_side, store_starting_location, store_time_of_day, store_turns, store_unit, store_unit_defense, store_unit_defense_on, store_unit_type, store_unit_type_ids, store_villages, story, swarm, sub_achievement, switch, sync_variable;

T:

target, team, teleport (ability, action), teleport_anim, terrain, terrain_defaults, terrain_graphics, terrain_mask, terrain_type, test, test_condition, test_do_attack_by_id, text_input, textdomain, theme, then, tile, time, time_area, topic, toplevel, trait, transform_unit, traveler, true, tunnel;

U:

unhide_unit, unit, unit_overlay, unit_type, unit_worth, units, unlock_view, unpetrify, unstore_unit, unsynced;

V:

value, variable, variables, variant, variation, victory_anim, village, vision_costs, volume;

W:

while, wml_message, wml_schema;

Z:

zoom;

The Wesnoth Markup Language (WML) is used to code almost everything in Wesnoth, including scenarios, units, savefiles, and the user interface layout. WML files are simple, human-readable text files, usually with the .cfg extension, with similarities to INI files and XML. For guidelines on keeping these files easily human-readable, see ConventionsWML.

Tag and Attribute Structures

WML has a syntax containing two basic elements: tags and attributes. Furthermore, attributes consist of keys and values. For example:

[tag]
    key=value
[/tag]

Tags are used to partition information, while the data is contained in the attributes. Keys identify the type of data to be stored and values are the actual data stored. When WML is processed, the tag identifies some unit of information, such as an action to perform or even an entire campaign. This gives a context for the attributes within the tag. For each key=value line within a tag, the attribute identified by key has its data set to value. Also allowed inside a tag is another tag. The inner tag is considered the child of the outer tag, as in the following example.

[parent_tag]
    key1=value1
    [child_tag]
        key2=value2
    [/child_tag]
[/parent_tag]

Every tag describes something different about the game; different tags work differently, with the allowed tags defined by context. There are several "top-level tags" that are allowed when not inside any other tag, and each tag defines which child tags (and which keys) it recognizes. Unrecognized tags and keys, such as the result of typos, sometimes produce error messages, but at other times they are ignored. The WML schema defines what is allowed and where. Although it's not designed to be read by humans, you can use it to automatically detect if you've done something wrong even in contexts where unrecognized keys and tags would be ignored, though it still won't work in contexts where you're allowed to define the contents however you like.

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 +, -, 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.


Tag Amendment Syntax

Inserting a plus sign (+) before a tag name allows one to append to an earlier tag (the most recent with the same name) rather than starting a new tag. This allows attributes to be added or replaced.

[tag]
    key=value
[/tag]
[+tag]
    key=value
[/tag]
  • All keys in the +tag will be set to the given values. If the keys did not exist in the most recent [tag] then they are added to that [tag]; otherwise their values will replace the old values in the most recent [tag].
  • Any child tags of the +tag will be appended to the children of the most recent [tag]. To be clear: none of those original child tags will be altered by this operation, since this is an "append" and not a "merge."
  • It is even possible to make tag amendments to a child tag after the parent tag has already closed. Using [+tag] syntax multiple times in a row (first for the parent, then for the child) will allow you to amend the more inward scopes.

Multiple Assignment Syntax

It is possible to set multiple attributes on a single line. This is done by listing the associated keys, followed by an equal sign, followed by the desired values.

[tag]
    key1,key2,key3=value1,value2,value3
[/tag]

would be the same as:

[tag]
    key1=value1
    key2=value2
    key3=value3
[/tag]
  • If there are extra keys, they will be set to an empty value. If there are extra values the last key will be set to the comma-separated list of all remaining values.
  • It is recommended not to use this syntax with keys which normally interpret commas specially (such as x and y in a StandardLocationFilter), to avoid confusion on which key receives which value. However, using x,y=12,10 for single coordinates is widely used and is an exception to the recommendation.

Special Attribute Values

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.

  • 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 – 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.
  • 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 comparisons to other values. Translatable values are intended for display on the screen, not for internal data. See TranslationsWML and GettextForWesnothDevelopers for more information.
  • key = "value1" + "value2": string concatenation is performed with the plus sign (+). 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 + 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.
  • 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.)
  • key = $variable: a variable substitution sets the key to the value of the indicated WML variable. This is indicated by the dollar sign ($) 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.
  • key = "$(formula-expression)": a formula expression sets the key to the value of the processed formula. This is indicated by a dollar sign ($) 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 (+) within a formula (without quotes, the plus sign represents string concatenation). Formula expressions are only supported where variable substitution is supported.
  • key = <<value>>: similar to a quoted value but stronger: the value is hidden from the 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.

Comments

Comments are indicated by a pound sign (#) unless in double quotes. Unless the line forms a valid preprocessor directive, all text after the pound sign will be ignored by the WML engine. Note that if the beginning of the line is a valid preprocessor directive, which is then followed by another pound sign, the second pound sign will still be interpreted as a comment character. For example, this works:

#ifdef FOO
#endif # FOO

Whether or not doing so is a good idea is a stylistic choice.

It is a very good coding convention to always add a space immediately following a pound sign for every comment. Not only does it avoid accidentally calling a preprocessor directive (for example, a commented line that begins with the word “define”) but it also makes comments stand further apart from the code.

Specially-formatted comments are frequently used to give commands to the Wesnoth maintenance tools to suppress false positives and enhance their coverage, as well as for adding explanatory comments for translatable strings.

See Also

This page was last edited on 23 February 2024, at 03:36.