LuaAPI/wml

The wml module contains functions for working with WML tables. This module is available starting in 1.14.0.

A WML table is a specially-formatted Lua table representing WML tags and values. For more detail on the format of WML tables, see LuaWML.

Functions

wml.attribute_count

(Version 1.15.3 and later only)

• wml.attribute_count(config) → count

Returns the number of attributes in the specified WML table.

wml.child_array

• wml.child_array(config, child_tag_name) → array

Like #wml.child_range, but returns an array instead of an iterator. Useful if you need random access to the children.

wml.child_count

• wml.child_count(config, child_tag_name) → count

Returns the number of children in the config with the given tag name.

wml.child_range

• wml.child_range(config, child_tag_name) → iterator ⇒ wml table

Returns an iterator over all the sub-tags of a WML object with the given name.

local u = wesnoth.units.find_on_map{ id = "Delfador" }[1]
for att in wml.child_range(u.__cfg, "attack") do
    wesnoth.message(tostring(att.description))
end

wml.find_child

(Version 1.15.3 and later only)

• wml.find_child(config, [tag_name], filter) → child or nil, index

Finds a child of the given config that matches the given filter, and returns the child or nil if not found. The index of the child is also returned. If a tag name is specified, the search is restricted to that tag.

wml.get_child

• wml.get_child(config, child_tag_name, [id]) → child_table

Returns the first sub-tag of a WML object with the given name.

local u = wesnoth.units.find_on_map{ id = "Delfador" }[1]
local costs = wml.get_child(u.__cfg, "movement_costs")
wesnoth.message(string.format("Delfador needs %d points to move through a forest.", costs.forest))

If a third parameter is passed, only children having a id attribute equal to it are considered.

wml.get_nth_child

• wml.get_nth_child(config, child_tag_name, n) → child_table

Returns the nth sub-tag of a WML object with the given name.

wml.remove_child

• wml.remove_child(config, child_tag_name)

Deletes the first child tag with the given name. This does not work on vconfig objects, however.

wml.remove_children

(Version 1.17.0 and later only)

• wml.remove_children(config, child_tag_name, ...)

Deletes all child tags with the given names. This does not work on vconfig objects, however. You can pass as many tag names as you want as separate arguments.

wml.tag

• wml.tag.tag_name(contents) → tag_table

Returns a table representing a tag within a WML table; can be used to create subtags with less brackets. It's common to use direct-table invocation for this, omitting the function parentheses.

wesnoth.wml_actions.event { name = "new turn", wml.tag.message { speaker = "narrator", message = "?" } }

wml.clone

(Version 1.15.0 and later only)

• wml.clone(wml_table) → cloned_table

Returns a clone (deep copy) of the passed WML table.

wml.equal

(Version 1.15.3 and later only)

• wml.equal(config, config) → true or false

Tests whether two WML objects are equal. Equal objects will produce an empty diff, and will be serialized to the same string.

wml.valid

(Version 1.15.3 and later only)

• wml.valid(table) → is_wml

Tests whether the passed table represents a valid WML table. It will also return true if passed a vconfig.

wml.matches_filter

• wml.matches_filter(WML table, filter) → boolean

Test if a config matches a WML filter (as [filter_wml]).

wml.load

(Version 1.15.0 and later only)

• wml.load(file, [defines, [schema]]) → config

Loads WML from a file and optionally validates it against a schema. The file and schema (if present) must both be a valid WML path, and the schema must point to a SchemaWML file. All built-in schema files can be found directly in the "schema" folder – for example, "schema/game_config.cfg" is the schema for an add-on's (and core's) _main.cfg.

The second parameter can either be a boolean specifying whether or not to preprocess the file (defaults to true), or an array of macros to be defined in the preprocessor (which of course implies the file will be preprocessed). The second form only allows specifying names to be defined. It does not allow setting a value or anything more complex.

wml.parse

(Version 1.15.0 and later only)

• wml.parse(string, [schema]) → config

Parses a string containing WML code and optionally validates it against the provided schema. Unlike load, this function does not run the preprocessor, though #textdomain directives will still be recognized.

wml.merge

(Version 1.15.3 and later only)

• wml.merge(base table, merge data, [mode]) → merged config

Merges two WML tables recursively, using the specified mode. Possible modes are merge, replace, and append. The modes work the same as in [set_variables]. The mode only affects how child tags are merged; merging of attributes is always done the same way. The default mode is merge.

wml.diff

(Version 1.15.3 and later only)

• wml.diff(left, right) → diff config

Compares two WML tables and produces an output table in DiffWML detailing their differences.

wml.patch

(Version 1.15.3 and later only)

• wml.patch(base, diff) → patched config

Takes a WML table and a diff in DiffWML format and returns a new WML table modified according to the diff's instructions.

wml.interpolate

(Version 1.15.3 and later only)

• wml.interpolate(template, variables) → interpolated config

Interpolates variables into a WML table, including [insert_tag]. This is the same as what a vconfig does implicitly, but can use any valid WML table as a source of variables.

local variables = {
  -- A scalar variable
  number = 100,
  -- An array variable with two entries
  wml.tag.list{value = 42, rank = 3},
  wml.tag.list{value = 21, rank = 1},
}
local subst = {
  key = "$number",
  wml.tag.insert_tag{
    name = "entry",
    variable = "list"
  }
}
local result = wml.interpolate(subst, variables)
print(wml.tostring(result))

The above code will output the following WML in the Lua console:

key=100
[entry]
  rank=3
  value=42
[/entry]
[entry]
  rank=1
  value=21
[/entry]

wml.tostring

• wml.tostring(wml_table) → string

Takes a userdata with metatable wml object or a wml table and dumps its content into a pretty string. (Version 1.15.0 and later only) The string output is syntactically valid WML that if parsed would produce the same config.

wml.variables["number"] = 100
local vconfig = wml.tovconfig({ key = "$number", another_key = true,
    {"a_subtag", { a_key_in_the_subtag = "foo" }}
})
wesnoth.message(wml.tostring(vconfig))
wesnoth.message(wml.tostring(vconfig.__literal))

wml.tovconfig

• ♟⌖ wml.tovconfig(config) → vconfig

Converts a WML table into a proxy object which performs variable substitution on the fly. The proxy object can for most intents and purposes be treated as a read-only table - the length operator works as expected, as does the ipairs function. The pairs function also works, but it is a little different than on a plain table - it will return only the attributes of the vconfig and not the tags. See LuaWML for more information about the structure of a vconfig (which is the same as the structure of a WML table). A vconfig has four special keys (__literal, __parsed, __shallow_literal, __shallow_parsed) which correspond to the functions in this module by the same name, but in most cases it is better to use the functions.

wml.variables["varname"] = "to_be_deleted"

-- correct
wesnoth.wml_actions.clear_variable { name = "to_be_deleted" }
-- error: try to delete a variable literally called "$varname"
wesnoth.wml_actions.clear_variable { name = "$varname" }
-- correct: "$varname" is replaced by "to_be_deleted" at the right time
wesnoth.wml_actions.clear_variable(wml.tovconfig { name = "$varname" })

wml.literal

• wml.literal(config) → wml_table

Returns the __literal field of its argument if it is a userdata, the argument itself otherwise. If the argument is nil, it returns an empty table. This function is meant to be called when a WML action handler can be called indifferently from WML (hence receiving a userdata) or from Lua (hence possibly receiving a table).

function wml_actions.display_literal_value(cfg)
   cfg = wml.literal(cfg)
   wesnoth.message(tostring(cfg.value)) 
end

Note: when the argument is a plain table, the function returns it as is. In particular, modifying the fields of the returned table causes the original table to be modified too.

wml.parsed

• wml.parsed(config) → wml_table

Returns the __parsed field of its argument if it is a userdata, the argument itself otherwise. See also #wml.literal.

wml.shallow_literal

• wml.shallow_literal(config) → wml_table

Returns the __shallow_literal field of its argument if it is a userdata, the argument itself otherwise. See also #wml.literal.

wml.shallow_parsed

• wml.shallow_parsed(config) → wml_table

Returns the __shallow_parsed field of its argument if it is a userdata, the argument itself otherwise. See also #wml.literal.

wml.all_variables

• ♟⌖ wml.all_variables → table

Returns a copy of all the WML variables currently set in the form of a WML table.

for key, value in pairs(wml.all_variables) do
    if type(value) == "table" then
        print(key, value[1], value[2])
    else
        print(key, value)
    end
end

wml.variables

• ♟⌖ wml.variables.variable ↔ variable_contents
• ♟⌖ wml.variables[variable_path] ↔ variable_contents

This table grants read-write access to the WML variables by their fully-qualified name. Looking up a non-existent variable yields nil; otherwise, it returns a scalar for a WML attribute and a table for a WML object. The format of the table is described in LuaWML#Encoding WML objects into Lua tables.

wesnoth.fire("store_unit", { variable="my_unit", { "filter", { id="hero" } } })
local heros_hp = wml.variables["my_unit[0].hitpoints"]
wesnoth.message(string.format("The 'hero' unit has %d hitpoints.", heros_hp))

Note that, if the variable name happens to designate a sequence of WML objects, only the first one (index 0) is fetched. If all the WML objects with this name should have been returned, use #wml.array_access.get instead. If you need a specific one, include the index in the lookup key.

Assigning to a key in this table converts the Lua object to a WML variable if possible. For a table, a WML object is created; otherwise, an attribute is created. Note that you cannot assign a simple array as it will be mistaken for a WML table and give an error. Assigning nil clears the variable.

wml.variables["my_unit.hitpoints"] = heros_hp + 10

wml.variables_proxy

• ♟⌖ wml.variables_proxy.variable ↔ proxy
• ♟⌖ wml.variables_proxy[variable_path] ↔ proxy

Similar to wml.variables, but if the variable is a container, then the fields of the returned table are then proxies to the WML objects with the same names; reading/writing to them will directly access the WML sub-variables. Note that this is still somewhat experimental and doesn't allow you to fully treat variables as if they were standard Lua tables.

wml.array_access.get

• ♟⌖ wml.array_access.get(var_name, [context]) → array of variable_contents

Fetches all the WML container variables with given name and returns a table containing them (starting at index 1). The context specifies where to get variables from. You can pass either a unit or a side as the context in order to get an array from the unit variables or side variables, respectively.

function get_recall_list(side)
    wesnoth.fire("store_unit", { x = "recall", variable = "LUA_recall_list" })
    local l = wml.array_access.get "LUA_recall_list"
    wml.variables.LUA_recall_list = nil
    return l
end

wml.array_access.get_proxy

• ♟⌖ wml.array_access.get_proxy(var_name) → array of proxies

Creates proxies for all the WML container variables with given name and returns a table containing them (starting at index 1). This function is similar to #wml.array_access.get, except that the proxies can be used for modifying WML containers. Note that changes to the returned array itself will not be reflected in the variable, however; only changes to the array elements.

wml.array_access.set

• ♟⌖ wml.array_access.set(varname, array, [context])

Creates WML container variables with given name from given table. The context specifies where to put the variables. You can pass either a unit or a side as the context in order to set an array in the unit variables or side variables, respectively.

wml.array_access.set("target", { {t=t1}, {t=t2}, {t=t3} })
-- target[0].t <- t1; target[1].t <- t2; target[2].t <- t3

wml.array_variables

• ♟⌖ wml.array_variables.variable ↔ array of variable_contents
• ♟⌖ wml.array_variables[variable_path] ↔ array of variable_contents

Like wml.variables, except that it works on arrays as with wml.array_access.get and wml.array_access.set. This is a little more convenient when working with global WML variables rather than unit or side variables.

wml.eval_conditional

• ♟ wml.eval_conditional(conditional_tags) → boolean

Returns true if the conditional described by the WML table passes. Note: WML variables are substituted.

local result = wml.eval_conditional {
  wml.tag.have_unit { id = "hero" },
  wml.tag.variable { name = "counter", numerical_equals = "$old_counter" }
}

Note: Prior to 1.15.13, this was available as wesnoth.eval_conditional.

wml.fire

• ♟ wml.fire(tag, parameters)
• (Version 1.17.17 and later only) ♟ wml.fire.tag(parameters)

Fire a WML action tag. Note: WML variables are substituted into the parameters table.

Note: Prior to 1.15.13, this was available as wesnoth.fire. The second form was available through helper.set_wml_action_metatable.

wml.error

• ♟ wml.error(message)

Interrupts the current execution and displays a WML error message. This is intended for error messages in the implementaton of custom ActionWML or ConditionalWML tags. For errors in a Lua API, the built-in error function is a more suitable choice.

local names = cfg.name or wml.error("[clear_variable] missing required name= attribute.")