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.

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

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

• wml.remove_children(config, child_tag_name)

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

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

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.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 do the pairs and ipairs functions. Integer indices will contain tag tables, a two-element table where the first element is the name of the tag and the second element is another vconfig representing the tag's contents. String indices represent keys in the config. There are 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

• (game only) 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

• (game only) wml.variables.variable ↔ variable_contents
• (game only) 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.get_variable_array 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

• (game only) wml.variables_proxy.variable ↔ proxy
• (game only) 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

• (game only) 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

• (game only) 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

• (game only) 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