Difference between revisions of "PreprocessorRef"

From The Battle for Wesnoth Wiki
m (Removed DevFeature)
(#deprecated: fix synopsis)
 
(45 intermediate revisions by 16 users not shown)
Line 1: Line 1:
 
{{WML Tags}}
 
{{WML Tags}}
== The WML preprocessor ==
+
== Overview ==
  
Wesnoth loads just one configuration file directly: '''data/_main.cfg'''.
+
Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.
However the WML preprocessor allows to include 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 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
+
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 that references itself, because it will cause errors (but, alas, not necessarily error messages).
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 errors
 
(but, alas, not necessarily error messages).
 
  
The following directives are used to create and use ''macros'',
+
== Preprocessor directives ==
i.e. shortcuts which reduce repetition of information.
 
See [[UtilWML]], [[UsefulWMLFragments]] for examples and [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the predefined core macros.
 
* '''#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;
+
The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.
                      ## 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]].
 
  
Note: Using the name-string of an existing macro as the name-string of a macro argument will always overwrite the original definition of the macro, e.g.:
+
The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.
#define VARIABLE
 
#enddef
 
#define MACRO VARIABLE
 
  {VARIABLE} # is calling for the argument, not for the macro above
 
#enddef
 
  
 +
'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.
  
Unlike the other preprocessor directives, #ifdef and #ifndef are not
+
=== #define ===
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''').
 
** '''DEBUG_MODE''' is stored when the player has launched wesnoth in debug mode (i.e. with '''-d''')
 
** '''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.
 
''#undef'' can be useful too if ''#ifdef'' is not enough.
 
* '''#undef ''symbol'' '''  erases ''symbol''
 
  
These directives expand a file by including other files, ''filename'' may not contain '..' or the directive will be skipped:
+
'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''
* '''{''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 '''data/''' subdirectory of the user data directory.  The ''user data directory'' varies depending on platform. See [[EditingWesnoth#Where_is_my_user_data_directory.3F|Where_is_my_user_data_directory?]]
 
  
* '''{./''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''}'''.
+
All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:
* 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. 
 
  
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.
+
<syntaxhighlight lang="wml">
 +
#define ENEMY_UNIT TYPE X Y
 +
## the ordering above is important, since the preprocessor 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
 +
</syntaxhighlight>
  
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:
+
(See [[SingleUnitWML]] for further information on creating units using WML.)
 +
 
 +
'''Important note:''' Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at ''disguising'' WML bloat, but they do nothing to ''alleviate'' it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom [[EventWML|events]] and [[InternalActionsWML#.5Bfire_event.5D|fire_event]] tags. See also: [[Wml_optimisation]].
 +
 
 +
=== #arg and #endarg ===
 +
 
 +
{{DevFeature1.13|7}}
 +
 
 +
Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.
 +
 
 +
For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:
 +
 
 +
<syntaxhighlight lang="wml">
 +
#define MESSAGE TEXT
 +
 
 +
#arg SPEAKER_ID
 +
narrator
 +
#endarg
 +
 
 +
#arg CAPTION
 +
#endarg
 +
 
 +
#arg SOUND
 +
#endarg
 +
 
 +
#arg IMG
 +
#endarg
 +
 
 +
[message]
 +
    speaker={SPEAKER_ID}
 +
    message={TEXT}
 +
    caption={CAPTION}
 +
    sound={SOUND}
 +
    image={IMG}
 +
[/message]
 +
#enddef
 +
</syntaxhighlight>
 +
 
 +
The caller of the macro can then decide which, if any, of the default values to override:
 +
<syntaxhighlight lang="wml">
 +
{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
 +
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
 +
{MESSAGE _"..."}
 +
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
 +
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
 +
</syntaxhighlight>
 +
 
 +
Note: as with #enddef, the final linebreak before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a linebreak in between.
 +
 
 +
=== #undef ===
 +
 
 +
'''Syntax:''' '''#undef ''symbol'' '''
 +
 
 +
Removes the previous definition of the macro named ''symbol''.
 +
 
 +
=== Inclusion directive {} ===
 +
 
 +
This directive can be used to include macros, single files or sets of files from a target directory.
 +
 
 +
==== File/directory inclusions ====
 +
 
 +
'''Syntax: {''path''}'''
 +
 
 +
Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.
 +
 
 +
The exact location in which the ''path'' will be resolved will depend on its prefix:
 +
 
 +
* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
 +
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
 +
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.
 +
 
 +
Information for locating the user data and game data directories can be found in [[EditingWesnoth]].
 +
 
 +
Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.
 +
 
 +
When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.
 +
 
 +
Some directories are handled in a special fashion according to their contents:
 +
 
 +
* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
 +
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
 
  dir/
 
  dir/
 
  dir/a/_main.cfg
 
  dir/a/_main.cfg
Line 78: Line 128:
 
  dir/b/other.cfg
 
  dir/b/other.cfg
 
  dir/other.cfg
 
  dir/other.cfg
Then '''{dir}''' will process (in alphabetical order): dir/a/_main.cfg, dir/b/main.cfg, dir/other.cfg.
+
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
 +
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
 +
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.
 +
 
 +
==== Macro inclusions ====
 +
 
 +
'''Syntax: {''symbol'' [''arguments''] [''optional arguments'']}'''
 +
 
 +
If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed '''after''' all normal arguments, however they can be specified in any order desired.
 +
 
 +
You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.
 +
 
 +
Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name '''and''' content:
 +
 
 +
<syntaxhighlight lang="wml">
 +
{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
 +
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong
 +
</syntaxhighlight>
 +
 
 +
This way even complex arguments can be passed:
 +
 
 +
<syntaxhighlight lang="wml">
 +
{MODIFY_UNIT (
 +
    [filter_adjacent]
 +
        canrecruit=yes
 +
    [/filter_adjacent]
 +
    ) side 2}
 +
</syntaxhighlight>
 +
 
 +
Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:
 +
 
 +
<syntaxhighlight lang="wml">
 +
#define VARIABLE
 +
#enddef
 +
#define MACRO VARIABLE
 +
    {VARIABLE} # is calling for the argument, not for the macro above
 +
#enddef
 +
</syntaxhighlight>
 +
 
 +
=== #ifdef and #ifndef ===
 +
 
 +
Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).
 +
 
 +
'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''
 +
 
 +
If ''symbol'' has been defined with '''#define''' or as a built-in macro, 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.
 +
 
 +
'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:
 +
 
 +
'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored''  [#else ''substitution-if-stored''] #endif'''
 +
 
 +
=== #ifhave and #ifnhave ===
 +
 
 +
'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''
 +
 
 +
Checks for the existence of a file. Uses the same relative paths as include directives (see below).
  
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.
+
Example:
  
If there is a file named ''dir/_initial.cfg'' in a directory referenced as '''{''dir''}''' (and no ''main.cfg'', so that all files in the directory are processed normally) the ''_initial.cfg'' is guaranteed to be processed ''before'' all other files in the directory.
+
<syntaxhighlight lang="wml">
 +
#ifhave ~add-ons/My_Addon/_main.cfg
 +
    {MY_ADDON_MACROS}
 +
#endif
 +
</syntaxhighlight>
  
 +
'''#ifnhave'''  does the opposite of '''#ifhave''':
  
 +
'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''
  
Note that the parser was changed various times, so don't expect older Wesnoth version to behave exactly the same.
+
=== #ifver and #ifnver ===
 +
 
 +
'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''
 +
 
 +
Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.
 +
 
 +
Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.
 +
 
 +
Example:
 +
<syntaxhighlight lang="wml">
 +
#ifver WESNOTH_VERSION >= 1.9.7+
 +
    [message]
 +
        speaker=narrator
 +
        message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
 +
    [/message]
 +
#else
 +
#ifver WESNOTH_VERSION == 1.9.7
 +
    [message]
 +
        speaker=narrator
 +
        message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
 +
    [/message]
 +
#endif
 +
#endif
 +
</syntaxhighlight>
 +
 
 +
'''#ifnver'''  does the opposite of '''#ifver''':
 +
 
 +
'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''
 +
 
 +
=== #error ===
 +
 
 +
'''Syntax:''' '''#error [''message'']'''
 +
 
 +
Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.
 +
 
 +
Please note that in spite of the example below, it is '''not''' advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.
 +
 
 +
Example:
 +
<syntaxhighlight lang="wml">
 +
#ifver WESNOTH_VERSION < 1.11.10
 +
#error This add-on does not support Wesnoth 1.11.10!
 +
#endif
 +
</syntaxhighlight>
 +
 
 +
=== #warning ===
 +
 
 +
'''Syntax:''' '''#warning [''message'']'''
 +
 
 +
Causes the WML preprocessor to emit a warning upon encountering the line. The message will '''only''' be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.
 +
 
 +
Example:
 +
<syntaxhighlight lang="wml">
 +
#ifver WESNOTH_VERSION < 1.11.10
 +
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
 +
#endif
 +
</syntaxhighlight>
 +
 
 +
=== #deprecated ===
 +
 
 +
{{DevFeature1.13|11}}
 +
 
 +
'''Syntax:''' '''#deprecated 1 ''message'''''
 +
 
 +
'''Syntax:''' '''#deprecated 2 ''version'' ''message'''''
 +
 
 +
'''Syntax:''' '''#deprecated 3 ''version'' ''message'''''
 +
 
 +
'''Syntax:''' '''#deprecated 4 ''message'''''
 +
 
 +
The effect of this directive depends on whether it appears within a macro definition.
 +
 
 +
* If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple '''#deprecated''' directives at toplevel in a single file will result in separate messages.
 +
* If it appears inside a macro definition ('''#define ... #enddef'''), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple '''#deprecated''' directives within a single macro will be merged into one message.
 +
 
 +
Note that deprecation messages will only appear if they have been set to. {{DevFeature1.13|12}} This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)
 +
 
 +
If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided ''version'' will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [[InterfaceActionsWML#.5Bdeprecated_message.5D|[deprecated_message]]] for the meaning of the various ''level'' values.
 +
 
 +
== Built-in macros ==
 +
 
 +
The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.
 +
 
 +
* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
 +
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
 +
* '''MULTIPLAYER''': defined when in multiplayer mode.
 +
* '''TUTORIAL''': defined when playing the tutorial campaign.
 +
* '''EDITOR''': defined when running the built-in map editor.
 +
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).
 +
* '''APPLE''': defined while processing the main game data when running on Mac OS X.
 +
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.
 +
* '''CURRENT_FILE''': Expands to the name of the current WML file.
 +
* '''CURRENT_DIRECTORY''': Expands to the name of the directory of {CURRENT_FILE}, I assume?
 +
* '''LEFT_BRACE''': {{DevFeature1.15|2}} Expands to <code>{</code>.
 +
* '''RIGHT_BRACE''': {{DevFeature1.15|2}} Expands to <code>}</code>.
 +
 
 +
Note that the macros above are only those generated by wesnoth engine itself. For a list of macros defined outside engine, see here: https://www.wesnoth.org/macro-reference.html
 +
 
 +
== Command-line preprocessor ==
 +
 
 +
'''Syntax: --preprocess ''&lt;source file/directory>'' ''<target directory>'' '''
 +
 
 +
Or the short form:
 +
 
 +
'''Syntax: -p ''&lt;source file/directory>'' ''<target directory>'' '''
 +
 
 +
You can specify a list of predefined defines with:
 +
 
 +
'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''
 +
 
 +
comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.
 +
 
 +
The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.
 +
 
 +
The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.
 +
 
 +
If by chance, the simple macro define doesn't suffice, you can use:
 +
 
 +
'''Syntax: --preprocess-input-macros <file>'''
 +
 
 +
To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.
 +
 
 +
There is also the possibility to export the preprocessed defines/macro list with:
 +
 
 +
'''Syntax: --preprocess-output-macros [<target file>]'''
 +
 
 +
This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario  would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.
 +
 
 +
If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.
 +
 
 +
Some examples:
 +
 
 +
* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
 +
-p ~/wesnoth/data/campaigns/tutorial ~/result
 +
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
 +
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
 +
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
 +
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD
 +
 
 +
If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.
  
 
== See Also ==
 
== See Also ==
 +
 
* [[SyntaxWML]]
 
* [[SyntaxWML]]
 
* [[ReferenceWML]]
 
* [[ReferenceWML]]
 
  
 
[[Category: WML Reference]]
 
[[Category: WML Reference]]

Latest revision as of 23:59, 19 October 2019

[edit]WML Tags

A:

abilities, about, add_ai_behavior, advance, 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, attack_anim, attacks, avoid;

B:

base_unit, berserk, binary_path, break, brush;

C:

campaign, cancel_action, candidate_action, capture_village, case, chance_to_hit, change_theme, chat, choose, clear_global_variable, clear_menu_item, clear_variable, color_adjust, color_range, command (action, replay), continue, 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, era, event, 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_vision, filter_weapon, filter_wml, find_path, fire_event, firststrike, floating_text, for, foreach, frame, full_heal;

G:

game_config, get_global_variable, goal, gold, gold_carryover;

H:

harm_unit, has_ally, has_attack, has_unit, 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), illuminates, image, 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, portrait, post_movement_anim, pre_movement_anim, primary_attack, primary_unit, print, 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_unit_overlay, repeat, replace_map, replace_schedule, replay, replay_start, reset_fog, resistance (ability, unit), resistance_defaults, resource, return, role, rule;

S:

save, scenario, scroll, scroll_to, scroll_to_unit, secondary_attack, secondary_unit, section, select_unit, sequence, set_extra_recruit, set_global_variable, set_menu_item, set_recruit, set_specials, set_variable, set_variables, sheath_weapon_anim, show_if (message, set_menu_item), show_objectives, side, skirmisher, 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_type, store_unit_type_ids, store_villages, story, swarm, switch, sync_variable;

T:

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

U:

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

V:

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

W:

while, wml_message, wml_schema;

Z:

zoom;

Overview

Wesnoth loads just one configuration file directly: data/_main.cfg. However the WML preprocessor allows to include 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 that references itself, because it will cause errors (but, alas, not necessarily error messages).

Preprocessor directives

The following directives are used to create and use macros, i.e. shortcuts which reduce repetition of information. See the macro reference for the list of predefined core macros.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

Note: In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

#define

Syntax: #define symbol [parameters] <newline> substitution #enddef

All subsequent occurences of {symbol [arguments]} (see below) will be replaced by the contents of the substitution block, with all occurrences of any parameter {parameter} within substitution replaced by the corresponding value in arguments. For example, the ENEMY_UNIT macro for the macro inclusion example below could be defined as follows:

#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor 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 further information on creating units using WML.)

Important note: Although macros may look like they're simplifying the code, they do not help with wml bloating. Macros are very good at disguising WML bloat, but they do nothing to alleviate it. So instead of using macros to generate redundant and repetitive instructions, you should be considering how to eliminate redundancy through programming techniques of abstraction. The most popular way to improve your code is using custom events and fire_event tags. See also: Wml_optimisation.

#arg and #endarg

(Version 1.13.7 and later only)

Defines an optional argument for a macro along with its default value. Optional arguments can be used to make a macro more flexible and to allow its user to specify certain parameters only when necessary.

For example, one could define a shortcut macro for [message] with only one required argument (the text displayed), but several optional ones:

#define MESSAGE TEXT

#arg SPEAKER_ID
narrator
#endarg

#arg CAPTION
#endarg

#arg SOUND
#endarg

#arg IMG
#endarg

[message]
    speaker={SPEAKER_ID}
    message={TEXT}
    caption={CAPTION}
    sound={SOUND}
    image={IMG}
[/message]
#enddef

The caller of the macro can then decide which, if any, of the default values to override:

{MESSAGE _"Halt!" SPEAKER_ID="Guard Captain"}
{MESSAGE _"Two days pass..." IMG=wesnoth-icon.png SOUND=ambient/morning.ogg}
{MESSAGE _"..."}
{MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
{MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}

Note: as with #enddef, the final linebreak before #endarg is included in the default value. This means that if the symbol is used in the middle of a line, you should place the #endarg immediately after the value has ended, without a linebreak in between.

#undef

Syntax: #undef symbol

Removes the previous definition of the macro named symbol.

Inclusion directive {}

This directive can be used to include macros, single files or sets of files from a target directory.

File/directory inclusions

Syntax: {path}

Includes the file with the specified path, which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The path may not contain .. or the inclusion will be skipped.

The exact location in which the path will be resolved will depend on its prefix:

  • {path}: If path isn't a known macro (see below), the game will assume it's a relative path to a file in the main game data/ directory and include it.
  • {~path}: As above, but instead of the game data directory, the path is resolved relative to the user data/ directory, where user made add-ons can normally be found.
  • {./path}: The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in EditingWesnoth.

Forward slashes (/) should always be used as the path delimiter, even if your platform uses a different symbol such as colons (:) or backslashes (\)! It is also very important to respect the actual letter case used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When path points to a directory instead of a file, the preprocessor will include all files found within with the .cfg extension, in alphabetical order; files without this extension (such as .map or .png files) are ignored.

Some directories are handled in a special fashion according to their contents:

  • If there's a file named _main.cfg in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
  • If there are files named _main.cfg in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg

Using {dir} will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.

  • If there's a file named _final.cfg but no _main.cfg, the file is guaranteed to be included and processed after all the other files in the directory.
  • If there's a file named _initial.cfg but no _main.cfg, the file is guaranteed to be included and processed before all the other files in the directory.

Macro inclusions

Syntax: {symbol [arguments] [optional arguments]}

If the macro named symbol is defined, the preprocessor will replace this instruction by the expression symbol was previously defined as, using arguments as parameters. The number of normal arguments must be exactly the same as in the original definition or an error will occur. Optional arguments can only be placed after all normal arguments, however they can be specified in any order desired.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in {ENEMY_UNIT Wolf Rider 18 24} the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use {ENEMY_UNIT (Wolf Rider) 18 24}.

Optional arguments can also be delimited by placing parentheses, however they must be placed around both the argument name and content:

{MESSAGE _"I'll smash you!" (SPEAKER_ID=Bridge Troll) } # Correct
{MESSAGE _"I'll smash you!" SPEAKER_ID=(Bridge Troll) } # Wrong

This way even complex arguments can be passed:

{MODIFY_UNIT (
    [filter_adjacent]
        canrecruit=yes
    [/filter_adjacent]
    ) side 2}

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

#define VARIABLE
#enddef
#define MACRO VARIABLE
    {VARIABLE} # is calling for the argument, not for the macro above
#enddef

#ifdef and #ifndef

Unlike the other preprocessor directives, #ifdef and #ifndef are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see Built-in macros below).

Syntax: #ifdef symbol substitution-if-defined [#else substitution-if-not-defined ] #endif

If symbol has been defined with #define or as a built-in macro, 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.

#ifndef is the exact opposite of #ifdef, reversing the logic:

Syntax: #ifndef symbol substitution-if-not-stored [#else substitution-if-stored] #endif

#ifhave and #ifnhave

Syntax: #ifhave path substitution-if-path-exists [#else substitution-if-path-does-not-exist] #endif

Checks for the existence of a file. Uses the same relative paths as include directives (see below).

Example:

#ifhave ~add-ons/My_Addon/_main.cfg
    {MY_ADDON_MACROS}
#endif

#ifnhave does the opposite of #ifhave:

Syntax: #ifnhave path substitution-if-path-does-not-exist [#else substitution-if-path-exists] #endif

#ifver and #ifnver

Syntax: #ifver symbol operator version-number <newline> substitution-if-condition-met [#else substitution-if-condition-not-met] #endif

Compares a version number defined in a macro against an argument for conditional block inclusions, like #ifdef and #ifhave. operator is one of == (equal), != (not equal), < (less), <= (less or equal), > (greater), >= (greater or equal). The specified symbol should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Versions with text suffixes are sorted in binary order and come after all versions with the same number. The most common suffixes begin with "+", but as this represents multiple possible versions, comparing versions against it is not recommended.

Example:

#ifver WESNOTH_VERSION >= 1.9.7+
    [message]
        speaker=narrator
        message= _ "I’m on Wesnoth 1.9.7+, 1.9.8 or later!"
    [/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
    [message]
        speaker=narrator
        message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
    [/message]
#endif
#endif

#ifnver does the opposite of #ifver:

Syntax: #ifnver symbol operator version-number <newline> substitution-if-condition-not-met [#else substitution-if-condition-met] #endif

#error

Syntax: #error [message]

Causes the WML preprocessor to fail unconditionally upon encountering the line. For add-ons, this will cause the game to display an error and return to the titlescreen if the add-on is required for the user's action (such as playing a campaign or loading a saved game). For core WML, this will cause the game to quit entirely.

Please note that in spite of the example below, it is not advisable to use this mechanism in published add-ons for version or feature-checking, since the message is not displayed in a form that permits translation and the additional trace information may confuse players. This directive is only intended as a debugging aid for content creators.

Example:

#ifver WESNOTH_VERSION < 1.11.10
#error This add-on does not support Wesnoth 1.11.10!
#endif

#warning

Syntax: #warning [message]

Causes the WML preprocessor to emit a warning upon encountering the line. The message will only be relayed to stderr, not to the player in the game UI. This directive is only intended as a debugging aid for content creators.

Example:

#ifver WESNOTH_VERSION < 1.11.10
#warning On Wesnoth 1.11.9 or earlier, bug workarounds enabled!
#endif

#deprecated

(Version 1.13.11 and later only)

Syntax: #deprecated 1 message

Syntax: #deprecated 2 version message

Syntax: #deprecated 3 version message

Syntax: #deprecated 4 message

The effect of this directive depends on whether it appears within a macro definition.

  • If it appears at file level, outside any macro definition, then it immediately outputs a warning saying that the file is deprecated, with the provided message. Multiple #deprecated directives at toplevel in a single file will result in separate messages.
  • If it appears inside a macro definition (#define ... #enddef), then it doesn't output anything. Instead, it marks the macro as deprecated. When that macro is later used, only then will the preprocessor output a warning saying that the macro is deprecated, with the provided message. Multiple #deprecated directives within a single macro will be merged into one message.

Note that deprecation messages will only appear if they have been set to. (Version 1.13.12 and later only) This can be done by enabling debug mode, or by going to Advanced Preferences and setting the log-level for the deprecation logdomain. (This can also be done on the command-line.)

If you provide a deprecation level of 2 or 3, it is required to indicate the earliest version in which the feature could be removed. However, if you provide a deprecation level of 1 or 4, any provided version will instead be parsed as part of the message, so you will probably not want to provide one at all. Other deprecation levels are not valid. See the documentation for [deprecated_message] for the meaning of the various level values.

Built-in macros

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

  • A campaign define symbol (see define in CampaignWML): defined when playing a single-player campaign.
  • A campaign difficulty level, usually EASY, NORMAL or HARD (see difficulties in CampaignWML): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
  • MULTIPLAYER: defined when in multiplayer mode.
  • TUTORIAL: defined when playing the tutorial campaign.
  • EDITOR: defined when running the built-in map editor.
  • DEBUG_MODE: defined when the game has been launched in debug mode (i.e. with -d or --debug in the command line).
  • APPLE: defined while processing the main game data when running on Mac OS X.
  • WESNOTH_VERSION: defined containing just the game version number when running the WML preprocessor.
  • CURRENT_FILE: Expands to the name of the current WML file.
  • CURRENT_DIRECTORY: Expands to the name of the directory of {CURRENT_FILE}, I assume?
  • LEFT_BRACE: (Version 1.15.2 and later only) Expands to {.
  • RIGHT_BRACE: (Version 1.15.2 and later only) Expands to }.

Note that the macros above are only those generated by wesnoth engine itself. For a list of macros defined outside engine, see here: https://www.wesnoth.org/macro-reference.html

Command-line preprocessor

Syntax: --preprocess <source file/directory> <target directory>

Or the short form:

Syntax: -p <source file/directory> <target directory>

You can specify a list of predefined defines with:

Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will preprocess first the common config files in the main game data/ directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

Syntax: --preprocess-input-macros <file>

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

Syntax: --preprocess-output-macros [<target file>]

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If file/directory and target directory are not absolute paths, they will be considered relative to the game's executable path.

Some examples:

  • Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
  • Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
  • Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches --log-debug=all or --log-info=all to the command line, so you can see how things are preprocessed in detail.

See Also

This page was last edited on 19 October 2019, at 23:59.