Difference between revisions of "SyntaxWML"

From The Battle for Wesnoth Wiki
 
(reformat)
Line 2: Line 2:
 
Further, ''attributes'' consist of ''keys'' and ''values''.
 
Further, ''attributes'' consist of ''keys'' and ''values''.
 
Tag names and keys cannot contain whitespace.
 
Tag names and keys cannot contain whitespace.
Any line beginning with a pound ('''#''') sign is considered by WML as
+
Any line beginning with a pound ('''#''') sign is considered by
a comment, except for preprocessor declarations beginning with #.
+
WML as a comment, except for preprocessor declarations beginning
* '''[''tag-name//] ''data'' [///tag-name'']''' is a tag.
+
with #.
  Tags are used to partition information.
+
* '''[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]].
  A ''top level'' tag is one that is not inside any other tag.
+
* '''[+tag-name] ''data'' [tag-name]''' means that ''data'' will be considered as part of the data for the most recent [''tagname''] tag.  The ''data'' of '''[+tag-name]''' will be considered as coming after all data in '''[tag-name]''', so attributes of '''[+tagname]''' will replace attributes of the original '''[tagname]'''.
  Each top level tag describes something about the game.
+
* '''''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.
  Different tags work differently.
+
* '''''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
  For information about how a certain tag works, see [[ReferenceWML]].
+
  key1=value1
* '''[+''tag-name//] ''data'' [///tag-name//]''' means that ''data''
+
  key2=value2
  will be considered as part of the data for the most recent [''tagname'']
+
  key3=value3
  tag.  The ''data'' of [+//tag-name''] will be considered as coming after
 
  all data in [''tag-name//], so attributes of [+//tagname''] will replace
 
  attributes of the original [''tagname''].
 
* '''''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.
 
* '''''key1//,//key(s)2//=//value1//,//value(s)2'' ''newline''''' is the same as
 
  '''''key1//=//value1'' ''newline'' ''key(s)2//=//value(s)2'' ''newline'''''.
 
  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.
 
  
Although a value can be just text corresponding to a function of its
+
Although a value can be just text corresponding to a function of
key (these values are displayed in quotes (''''''') in [[ReferenceWML]]),
+
its key (these values are displayed in quotes (') in
a value can also be encoded:
+
[[ReferenceWML]]), a value can also be encoded:
* '''"''multiple-line-value''"''' a multiple-line value must be enclosed in
+
* '''"''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.
  quotes, to prevent it being interpreted as a single-line value.
+
* '''''_ "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.
  Note that ''multiple-line-value'' doesn't have to have multiple lines;
+
* '''''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).
  it can simply be a single-line value enclosed in quotes for clarity.
+
* '''''$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.
* '''_ "''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.
 
  
 
Example:
 
Example:
Line 90: Line 59:
 
* [[PreprocessorRef]]
 
* [[PreprocessorRef]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 

Revision as of 12:58, 26 August 2005

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 [tagname] tag. The data of [+tag-name] will be considered as coming after all data in [tag-name], so attributes of [+tagname] will replace attributes of the original [tagname].
  • 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.
  • 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 its key (these values are displayed in quotes (') in 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.

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


See Also