This is the third part of a series on advanced trickery that can be done with fasmg. The other installments: part 1, part 2, part 4.
_______

When designing a macro for a general use, it is important to ensure that it works correctly when called in different contexts. The LOCAL directive allows to create private symbols for every instance of macro without interfering with an unknown environment. But sometimes a variable may be needed to be shared across the multiple macro calls. A globally defined symbol usually works well enough for this purpose, but it is something that may be interfered with. Let's consider the following example: These macros have a few issues. First, if someone defines symbol called GLOBAL_STATE for other purposes, it is going to interfere with them. A choice of rare and specific name for a global may help a bit, and if there are multiple global symbols needed, it is good to create a special namespace for them and attach this namespace to a global symbol with such specific name.
The other problem would show up if these macro were used inside the NAMESPACE block, because the the re-definition of GLOBAL_STATE would instead create a symbol in the other namespace. We have already seen the solution to this problem - it is enough to add the dot at the end of the identifier to make sure that the defined symbol is the same whose value is accessed on the right-hand side:

But there is also another option. There is a mechanism that allows the arguments to a macro to preserve the context for any identifiers inside them. The following example demonstrates this effect: The text of both data-generating lines that get assembled is the same, "db a", but the second one interprets the "a" identifier in the context in which the macro was called and generates the 3 instead of 0. This is achieved though a mechanism that could be interpreted as a kind of text "coloring". The value of parameter "arg" has an additional property, like a color of text, that makes first "db a" different from the second "db a". Now, if we define a macro inside another macro, then the text of that inner macro is going to preserve that "coloring". The following sample uses this mechanism to improve the definition of "state"/"switch" macros that were used as an example earlier: When the "setup GLOBAL_STATE" gets assembled, the "switch" macro is defined with a body containing the text:
        GLOBAL_STATE = GLOBAL_STATE xor (value)
The color used above shows the parts of the text that have the global context attached to them. The parts that are not specially colored are going to be interpreted in the context in which the macro gets executed. Now when "switch 8" line is assembled, the line generated by macro is:
        GLOBAL_STATE = GLOBAL_STATE xor (8)
This time there is an additional color which reflects that the contents of "value" parameter also preserves the context - this time the one in which the "switch" macro was called.

Therefore in this version both "switch" and "state" always use the global variable no matter what context they are used in. This bears a similarity to the concept of closure used in many programming languages.

The macros in the above sample correctly access their variable even though in the local namespace there is a variable defined with the same name. But, because their variable is global, the other code may still interfere with it. To make the variable completely outside the reach of others, we can use LOCAL directive. The LOCAL declaration creates a special parameter that replaces its name with the same text, but this time "colored" in such a way, that it carries the context unique to the instance of a macro: This simple trick also allows to further improve the encapsulation macros from the previous part:
The context that may be carried by the text of argument includes the namespace that applied to it and also the symbol that at the time was the "parent" for the identifiers starting with dot.

There is also one other place where this kind of context transfer occurs: the values of symbolic variables. When a symbol is defined with EQU or DEFINE, its entire value becomes equipped with the context that was present at the time of definition. When the text of such value is assigned to a parameter with MATCH or IRPV, the text's "colors" are preserved: The DISPLAY shows that the text extracted from LIST variable with MATCH is ".x, .x". But the texts of these two identifiers have different contexts attached to them, so the list really contains two different values.

If a MATCH cuts the text of an identifier into many parts, all parts preserve the "color" of their text. And if an identifier becomes patched up from the parts of text with many different "colors", only the context associated with the initial part has any effect on the recognition of this symbol.

In case it was needed that some text is returned back to the "neutral coloring" and interpreted in the current context, the RMATCH directive does this to the text of parameters it defines. The similar effect could also be achieved by converting the value of parameter into a string with the ` operator and then interpreting this pure text with EVAL.

But there is also a neat little trick based on the fact that only the context associated with the initial part of identifier has any effect. It is enough to prepend to parameter with "#" character to form an identifier interpreted in current context:

On a side note: the namespace that contains symbols declared with LOCAL is disconnected from the main tree of namespaces - in other words, the outer namespaces are not accessible from there. If such symbol is used as an argument to the NAMESPACE directive, suddenly all the built-in instructions of the assembler are going to become inaccessible, even the END NAMESPACE is not going to work: But, through the trickery of the recognition context transfer it is possible to "implant" some working instructions into this blank namespace: This could be an interesting playground, since in such namespace all the symbols are available for the taking and it would be possible to provide a directive set that would be completely distinct from the default ones.

Another small improvement to the encapsulation macros could be to include these definitions in the macro: These ensure that encapsulated source cannot modify the global $, $$ and $@ symbols with definitions like "$. = 0", they could only modify the local symbol. Therefore even in such cases the expressions defining the $% and $%% would still work correctly, because they access global symbols (thanks to the context preserved by DEFINE).

I noticed a more concise way to implant preexisting symbols into the local namespace:

This is indeed an interesting feature that I will definitely find uses for.

Edit: I just realized that this only implants them inside the body of the macro, which is also useful, and even makes namespace implanting more concise:



Edit2: Default arguments let you only list the imports once and you can use the imports in the local namespace until you call a macro or include a file.