PreprocessorRef - Revision history

Laela: /* Built-in macros */ https://github.com/wesnoth/wesnoth/pull/11208

2026-06-18T21:06:55Z

‎Built-in macros: https://github.com/wesnoth/wesnoth/pull/11208

Bssarkar: /* Macro inclusions */ Mention empty argument passing

2026-06-12T14:27:02Z

‎Macro inclusions: Mention empty argument passing

Pentarctagon: /* #deprecated */

2026-04-13T15:42:13Z

‎#deprecated

Bssarkar: /* Macro inclusions */ mention that space inside "" is preserved

2026-04-07T14:14:32Z

‎Macro inclusions: mention that space inside "" is preserved

Bssarkar: /* #deprecated */ version is actually mandatory for deprecation levels 2/3

2026-04-04T05:52:41Z

‎#deprecated: version is actually mandatory for deprecation levels 2/3

Bssarkar: /* #deprecated */ Add more explanation about #deprecated arguments, and mention optionality

2026-03-29T16:36:11Z

‎#deprecated: Add more explanation about #deprecated arguments, and mention optionality

Bssarkar: /* #define */ Mention define/enddef non-nesting requirement (cf. GNA #21343)

2026-03-20T15:50:21Z

‎#define: Mention define/enddef non-nesting requirement (cf. GNA #21343)

Bssarkar: /* #define */ Convert to named link

2024-11-03T15:21:57Z

‎#define: Convert to named link

Pentarctagon: /* #arg */

2024-08-29T23:47:31Z

‎#arg

Pentarctagon: /* #arg */

2024-08-29T23:43:16Z

‎#arg

@@ Line 335: / Line 335: @@
 * '''APPLE''': defined while processing the main game data when running on Mac OS X. This primarily exists to switch Control for Command in hotkeys, which is why there are no defines for other platforms.
 * '''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 preprocessor path of the parent directory for the current WML file (e.g. for <code>&lt;user data dir&gt;/data/add-ons/My_Addon/_main.cfg</code> this evaluates to <code>~add-ons/My_Addon</code>).

@@ Line 179: / Line 179: @@
 You can create multiple word arguments by using parentheses to delimit the contents. If they are already quoted, space inside quotes will be preserved even without parentheses. 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:
@@ Line 187: / Line 192: @@
 </syntaxhighlight>
-This way even complex arguments can be passed:
+This way even complex arguments can be passed, such as code blocks that span multiple lines:
 <syntaxhighlight lang="wml">

@@ Line 306: / Line 306: @@
 '''Syntax:''' '''#deprecated 4 [''message'']'''
-The first argument is the deprecation level, while ''version'' is the Wesnoth version where this deprecated file/macro is supposed to be removed. ''message'' is the optional deprecation message. The recommended usage is to provide ''message''.
+The first argument is the deprecation level, while ''version'' is the first Wesnoth version where this deprecated file/macro might to be removed. ''message'' is the optional deprecation message. The recommended usage is to provide ''message''.
 The effect of this directive depends on whether it appears within a macro definition.

@@ Line 178: / Line 178: @@
 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}'''.
+You can create multiple word arguments by using parentheses to delimit the contents. If they are already quoted, space inside quotes will be preserved even without parentheses. 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:

@@ Line 300: / Line 300: @@
 '''Syntax:''' '''#deprecated 1 [''message'']'''
-'''Syntax:''' '''#deprecated 2 [''version'' ''message'']'''
+'''Syntax:''' '''#deprecated 2 ''version'' [''message'']'''
-'''Syntax:''' '''#deprecated 3 [''version'' ''message'']'''
+'''Syntax:''' '''#deprecated 3 ''version'' [''message'']'''
 '''Syntax:''' '''#deprecated 4 [''message'']'''
-The first argument is the deprecation level, while ''message'' is the optional deprecation message, and ''version'' is the optional Wesnoth version where this deprecated file/macro is supposed to be removed. (Although optional, the recommended usage is to provide ''message'' and ''version''.)
+The first argument is the deprecation level, while ''version'' is the Wesnoth version where this deprecated file/macro is supposed to be removed. ''message'' is the optional deprecation message. The recommended usage is to provide ''message''.
 The effect of this directive depends on whether it appears within a macro definition.

@@ Line 298: / Line 298: @@
 {{DevFeature1.13|11}}
-'''Syntax:''' '''#deprecated 1 ''message'''''
+'''Syntax:''' '''#deprecated 1 [''message'']'''
-'''Syntax:''' '''#deprecated 2 ''version'' ''message'''''
+'''Syntax:''' '''#deprecated 2 [''version'' ''message'']'''
-'''Syntax:''' '''#deprecated 3 ''version'' ''message'''''
+'''Syntax:''' '''#deprecated 3 [''version'' ''message'']'''
-'''Syntax:''' '''#deprecated 4 ''message'''''
+'''Syntax:''' '''#deprecated 4 [''message'']'''
 The effect of this directive depends on whether it appears within a macro definition.

@@ Line 22: / Line 22: @@
 '''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 inclusions|macro inclusion]] example below could be defined as follows:
+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''. <code>#define-#enddef</code> blocks cannot be nested inside another <code>#define</code>, as of Wesnoth 1.19.
 <syntaxhighlight lang="wml">

@@ Line 45: / Line 45: @@
 (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]].
+'''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|WML Optimisation]].
 ==== Whitespace in Macros ====

@@ Line 108: / Line 108: @@
 {MESSAGE _"Welcome!" CAPTION=_"Elóndra's shop of wonders" IMG=portraits/elves/shyde.png}
 {MESSAGE _"*smash*" SPEAKER_ID="Bridge Troll" SOUND=mace.ogg}
 </syntaxhighlight>

@@ Line 80: / Line 80: @@
 #arg SPEAKER_ID
-narrator
+narrator#endarg
 #arg CAPTION