MCA Documentation on the MCAssembly language

• Home
• Documentation
• MCIL
• Variables
• Internal functions
• Types
• Scopes
• Blocks
• Control statements
• Macros
• Tutorial
• Language Introduction

Macros are an important structure in MCA - they allow you to easily repeat common code, in a similar way to traditional functions and constants.

Structure

To define a macro, use the following structure:

#MACRO_NAME expression
// or
#MACRO_NAME() expression
// or
#MACRO_NAME(parameters) expression

Where MACRO_NAME is the name of the macro, parameters are a list of parameters to the expression, and expression is the code to be executed when the macro is used.

Once a macro is defined, its name can be used anywhere an identifier would be valid - this means you can effectively use it as a variable for most cases.

Macro names are case insensitive, however it is good practice to use all uppercase names with underscores between words.

Hoisting

Macros are always 'hoisted' to the top of the file - this means that they are available both before and after they are defined in the code.

As a result, the following is valid:

Code:

SAY_SOMETHING("hi");

#SAY_SOMETHING(message) /say {message};

Scope and Parameters

When a macro is called, a new scope is created for the macro (for more info on scopes, see the Scope reference page). As a result, the macro cannot access variables defined outside of itself, apart from variables defined in the global scope. The exception to this is parameters.

Parameters are provided in the same way as Blocks - a comma-separated list of variable names. When the macro is called, the values provided in the brackets will be placed in the variable names provided, in the macros scope. When dealing with parameters, it is important to understand the difference between pass-by-value and pass-by-reference variables. This is covered in more detail in the Block reference page.

Note that MCA does not support closures unlike languages such as Javascript. Instead, only variables in the global scope, and variables in the current scope, are accessible. For more information, see the Scope reference page.

Overloads

MCA supports 'overloaded' macros. These are macros with the same name, but a different number of parameters. The macro to be executed will be determined based on the number of parameters provided. This can be used, for example, to provide default parameter values, or slightly different handling for different parameters.

To create an overloaded macro, simply provide the macro multiple times. For example:

Code:

#MY_MACRO(one) {
    /say one parameter: {one};
}
#MY_MACRO(one, two) {
    /say two parameters: {one}, {two};
}
#MY_MACRO(one, two, three) {
    /say three parameters: {one}, {two}, {three};
}

MY_MACRO("just one");
MY_MACRO("hey look", "its a parameter", "and thats the third");

Becomes:

/say one parameter: just one
/say three parameters: hey look, its a parameter, and thats the third