View source for WML for Complete Beginners: Chapter 9

{{Translations}}<div style="float:right">{{:WML for Complete Beginners}}</div>

==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:
<syntaxhighlight lang=wml>
[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]
</syntaxhighlight>

Notice how each time the leader says something, Stooge says the exact same thing: "WHAT?" Rather than having to write
<syntaxhighlight lang=wml>
    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]
</syntaxhighlight>
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
    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]
#enddef
</syntaxhighlight>

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:
<syntaxhighlight lang=wml>
    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]
</syntaxhighlight>

====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:
<syntaxhighlight lang=wml>
    [message]
        speaker=Stooge
        message= _ "WHAT?"
    [/message]
</syntaxhighlight>
with the following line:
<syntaxhighlight lang=wml>
{STOOGE_REPLY}
</syntaxhighlight>

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

===Macro Arguments===

{{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]]