PreprocessorRef
The WML preprocessor
Wesnoth loads just one configuration file directly: data/game.cfg. However the WML preprocessor allows game.cfg to load in more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.
The preprocessor can interpret a simple language of string-expansions known as "macros." A macro should always be defined before the place where it needs to be used.
The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro, because it will cause an infinite loop. Changes to the preprocessor in 0.9.2 allow recursively nested #ifdefs, but recursively nested macro definitions ('#define') will still cause errors (but not necessarily error messages).
The following directives are used to create and use macros, i.e. shortcuts which reduce repetition of information. See UtilWML, UsefulWMLFragments for examples.
- #define symbol [parameters] newline substitution #enddef all subsequent occurences of {symbol [arguments]} (see below) will be replaced by substitution with all occurences of any parameter {parameter} within substitution replaced by the parameter's corresponding value in arguments. For example, the UNIT macro used below would be defined:
#define UNIT TYPE X Y## the ordering is important here;
## since WML does not distinguish
## data into different types, only
## the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE}## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef
(See SingleUnitWML for information on creating units using WML.)
- {symbol [arguments]} if symbol is defined, the preprocessor will replace this instruction by the expression symbol is defined as, using arguments as parameters. You can create multiple word arguments by using parentheses to restrain the argument. For example, while {UNIT Wolf Rider 18 24} will attempt to create a "Wolf" at (Rider,18), causing Wesnoth to crash, the macro {UNIT (Wolf Rider) 18 24} will create a "Wolf Rider" at (18,24) as it should. (UNIT is defined above). See the #define preprocessor instruction above for information on defining symbols, including symbols with arguments. Several symbols are defined in the normal game code; for reference they are listed in UtilWML.
Unlike the other preprocessor directives, #ifdef and #ifndef are not mere conveniences. They are necessary to distinguish between different modes of play.
- #ifdef symbol substitution-if-stored [#else substitution-if-not-stored] #endif If symbol has been stored, the whole block will be replaced by substitution-if-stored. If not, it will be replaced by substitution-if-not-stored if it is available. symbol can take the following values:
- a campaign difficulty level. Usually EASY, NORMAL, or HARD, it is decided by the key difficulties (see CampaignWML).
- a campaign ID. Each campaign stores a preprocessor ID. See define, CampaignWML.
- MULTIPLAYER is stored when the player is playing or setting up a multiplayer game (i.e. a game with scenario_type=multiplayer).
- TUTORIAL is stored when the player is playing the tutorial.
- APPLE is stored if the computer Wesnoth is being run on is an Apple. (this one is only available to the configuration of the game)
- PYTHON is stored if Python support is built in and available. Use this to for example show a warning when starting a campaign that uses Python AI's, if Python isn't available.
- #ifndef behaves exactly like #ifdef, except that it inverts the test sense; guarded text is included only if symbol has not been stored. (Available in 1.3.10 or later.)
#undef can be useful too if #ifdef is not enough.
- #undef symbol erases symbol (v1.1.1+svn)
These directives expand a file by including other files:
- {filename} if filename isn't a predefined symbol (see above), Wesnoth will assume it's a path to a file in the main data/ subdirectory of Wesnoth and include the file it points to here "as is". Forward slashes(/) should be used to separate directories from their elements, even if your platform uses a different symbol such as colon (:) or backslash (\).
- {~filename} similar to above, but the preprocessor assumes that the filename is relative to the user data directory. The user data directory varies depending on platform:
Platform | User Data Directory ------------------------- UNIX | ~/.wesnoth/data/ Mac OS X | ~/Library/Preferences/Wesnoth or ~/.wesnoth/data Windows | "main Wesnoth folder"\userdata
- {@filename} is a convenient way to make Wesnoth look for a file by that name in both the main and the user data directory. It is equivalent to writing {filename}{~filename}.
- {./filename} is similar to the {filename} directive, but is assumed to be relative to the directory which contains the file in which this appears. For example, if used in game.cfg, it is equivalent to {filename}.
- If filename points to a directory, the preprocessor will include all files in the directory filename, non-recursively and in alphabetical order. Starting in 1.3.3, some files in such directories are handled specially.
Template:DevFeature If there is a file named dir/_main.cfg in a directory referenced as {dir}, only that _main.cfg file is processed; it may include other files in itself, of course . This feature is useful for creating WML directories that are self-contained WML packages with their own initializations (like campaigns). This can replace the older convention of having a dir.cfg at the same level as dir which does {dir} somewhere in itself.
Template:DevFeature If there are files named dir/*/_main.cfg in a directory referenced as {dir}, where * is any subdirectories dir, then they all are processed (except if there is also a file named dir/_main.cfg). This means that if you have a layout like this:
dir/ dir/a/_main.cfg dir/a/other.cfg dir/b/_main.cfg dir/b/other.cfg dir/other.cfg
Then {dir} will process (in alphabetical order): dir/a/_main.cfg, dir/b/main.cfg, dir/other.cfg.
Template:DevFeature If there is a file named dir/_final.cfg in a directory referenced as {dir} (and no main.cfg, so that all files in the directory are processed normally) the _final.cfg is guaranteed to be processed after all other files in the directory.
Note that the parser was changed various times, so don't expect older Wesnoth version to behave exactly the same.