WML for Complete Beginners: Chapter 9 - Revision history

Celtic Minstrel: Use syntax highlighting

2023-01-29T20:41:29Z

Use syntax highlighting

Celtic Minstrel: Nicer index and navigation

2023-01-29T19:21:10Z

Nicer index and navigation

William: /* Macro Arguments */

2015-11-10T09:16:55Z

‎Macro Arguments

Implementor37: Added link to the next chapter of WML_for_Complete_Beginners (Chapter 10)

2015-03-17T16:56:25Z

Added link to the next chapter of WML_for_Complete_Beginners (Chapter 10)

Iceiceice at 21:20, 6 April 2014

2014-04-06T21:20:01Z

Artisticdude: Created page with '==Chapter 9: Macros== Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customer…'

2013-04-02T17:38:37Z

Created page with '==Chapter 9: Macros== Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customer…'

New page

==Chapter 9: Macros==

Have you ever needed to perform a task where you did the exact same thing several times? For instance, maybe you work at a cafe and you have three customers who want the exact same item: a (...)

There are also instances in programming where you need the computer to perform the exact same task multiple times. But each time you need the computer to perform that same task again, you would have to write the same code again. There would be a lot of repetitious code, and it would take forever to write. Wouldn't it be great if we could do that task multiple times without having to result to writing the code out multiple times? Well, with macros, you can.

You can think of macros as a special kind of variable. Just like you can store a long sentence in a variable and substitute it in several messages later on so that you don't have to write out the sentence several times, you can store WML code in a macro and simply call the macro wherever you would have to write all the code contained in the macro. When the scenario is loaded, the preprocessor will automatically substitute the code contained in the macro wherever the macro is called, for the duration of that scenario.

This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:

[event]
name=start
[message]
speaker=Leader
message= _ "What do you think our plan should be, Stooge?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "I said, what do you think our battle plan should be?"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
[/message]
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
[message]
speaker=Leader
message= _ "Grrr..."
[/message]
[/event]

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:

#define STOOGE_REPLY
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
#enddef

Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"

===The Parts of a Macro===

Macros consist of three elements: the macro preprocessor directives, the macro symbol, and the macro body.

====The Macro Preprocessor Directives====
The macro preprocessor directives consist of the strings "#define" and "enddef". They tell the game where the macro begins and ends. Just like the preprocessor directives in the "_main.cfg" file, the macro preprocessor directives must be entirely lowercase and be spelled correctly.

====The Macro Symbol====
The macro's symbol is the string of uppercase characters following the opening preprocessor directive that identifies the macro. Think of it as the macro's id. Symbols can only include alphanumeric characters and underscores, and should be capitalized throughout. In the case of the example above, the macro symbol would be:
STOOGE_REPLY

====The Macro Body====
The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

====Calling A Macro====
Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]
with the following line:
{STOOGE_REPLY}

Basically, this tells the game that whenever it comes across an instance of this line:
{STOOGE_REPLY}
it should substitute the following code in place of that line:
[message]
speaker=Stooge
message= _ "WHAT?"
[/message]

===Macro Arguments===

@@ Line 1: / Line 1: @@
 ==Chapter 9: Macros==
@@ Line 95: / Line 97: @@
 ===Macro Arguments===
-Next Chapter:
+{{Navigation|[[WML for Complete Beginners: Chapter 8|'''Chapter 8'''<br>Non-scalar Variables]]|[[WML for Complete Beginners: Chapter 10|'''Chapter 10'''<br>Logic]]}}
 [[Category:WML_for_Complete_Beginners]]

@@ Line 95: / Line 95: @@
 ===Macro Arguments===
 [[WML for Complete Beginners: Chapter 10]]
 [[Category:WML_for_Complete_Beginners]]

← Older revision		Revision as of 16:56, 17 March 2015
Line 94:		Line 94:

	===Macro Arguments===		===Macro Arguments===
		+
		+	[[WML for Complete Beginners: Chapter 10]]

	[[Category:WML_for_Complete_Beginners]]		[[Category:WML_for_Complete_Beginners]]

← Older revision		Revision as of 21:20, 6 April 2014
Line 94:		Line 94:

	===Macro Arguments===		===Macro Arguments===
		+
		+	[[Category:WML_for_Complete_Beginners]]

@@ Line 10: / Line 10: @@
 This can be a confusing topic, so let's illustrate with some actual WML examples. Here we have the noble leader and the hard-of-hearing stooge trying to formulate their battle plan at the start of the scenario:
+<syntaxhighlight lang=wml>
- [event]
+[event]
      name=start
-     [message]
+    [message]
-         speaker=Leader
+        speaker=Leader
-         message= _ "What do you think our plan should be, Stooge?"
+        message= _ "What do you think our plan should be, Stooge?"
-     [/message]
+    [/message]
-     [message]
+    [message]
-         speaker=Stooge
+        speaker=Stooge
-         message= _ "WHAT?"
+        message= _ "WHAT?"
-     [/message]
+    [/message]
-     [message]
+    [message]
-         speaker=Leader
+        speaker=Leader
-         message= _ "I said, what do you think our battle plan should be?"
+        message= _ "I said, what do you think our battle plan should be?"
-     [/message]
+    [/message]
-     [message]
+    [message]
-         speaker=Stooge
+        speaker=Stooge
-         message= _ "WHAT?"
+        message= _ "WHAT?"
-     [/message]
+    [/message]
-     [message]
+    [message]
-         speaker=Leader
+        speaker=Leader
-         message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
+        message= _ "WHAT DO YOU THINK OUR BATTLE PLAN SHOULD BE?!"
-     [/message]
+    [/message]
-     [message]
+    [message]
-         speaker=Stooge
+        speaker=Stooge
-         message= _ "WHAT?"
+        message= _ "WHAT?"
-     [/message]
+    [/message]
-     [message]
+    [message]
-         speaker=Leader
+        speaker=Leader
-         message= _ "Grrr..."
+        message= _ "Grrr..."
-     [/message]
+    [/message]
- [/event]
+[/event]
 Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
-     [message]
+<syntaxhighlight lang=wml>
-         speaker=Stooge
+    [message]
-         message= _ "WHAT?"
+        speaker=Stooge
-     [/message]
+        message= _ "WHAT?"
 three times, let's stick the code in a macro named "STOOGE_REPLY". Create a new text document in the "macros" folder inside your campaign folder. Name it "my_macros.cfg". Now open the file in a text editor (if you haven't already) and enter the following code:
+<syntaxhighlight lang=wml>
- #define STOOGE_REPLY
+#define STOOGE_REPLY
-     [message]
+    [message]
-         speaker=Stooge
+        speaker=Stooge
-         message= _ "WHAT?"
+        message= _ "WHAT?"
-     [/message]
+    [/message]
- #enddef
+#enddef
 Now save the file. Hooray, you have just created your first macro! Now go to the scenarios folder and open the "my_first_campaign"
@@ Line 73: / Line 77: @@
 ====The Macro Body====
 The macro body is the code that is contained in the macro. Everything between the preprocessor directives (with the exception of the macro symbol) is considered by the game to be the macro body. In this case, the macro body is:
-     [message]
+<syntaxhighlight lang=wml>
-         speaker=Stooge
+    [message]
-         message= _ "WHAT?"
+        speaker=Stooge
-     [/message]
+        message= _ "WHAT?"
 ====Calling A Macro====
 Now that we have created our macro and understand what it does and what its respective parts are, let's return to our scenario and scroll to the start event that contains the dialogue between the leader and the stooge. Replace each instance of this code:
-     [message]
+<syntaxhighlight lang=wml>
-         speaker=Stooge
+    [message]
-         message= _ "WHAT?"
+        speaker=Stooge
-     [/message]
+        message= _ "WHAT?"
 with the following line:
- {STOOGE_REPLY}
+<syntaxhighlight lang=wml>
 Basically, this tells the game that whenever it comes across an instance of this line:
- {STOOGE_REPLY}
+<syntaxhighlight lang=wml>
 it should substitute the following code in place of that line:
-     [message]
+<syntaxhighlight lang=wml>
-         speaker=Stooge
+    [message]
-         message= _ "WHAT?"
+        speaker=Stooge
-     [/message]
+        message= _ "WHAT?"
 ===Macro Arguments===