In general the pattern for a macro that creates a module attribute in the calling code that is then accessed in the macro is something like this:
defmacro my_macro(opts) do
# Set up the module and fields from wherever they are derived
module = Keyword.get(opts, :module)
fields = Keyword.get(opts, :fields)
# Register and set the module attribute in the calling module at
# macro expansion time. At this time the calling module is
# still being compiled
calling_module = __CALLER__.module
Module.register_attribute(calling_module, :counter_cache_fields)
Module,put_attribute(calling_module, :counter_cache_fields, fields)
# Now the code that is injected in the caller
quote do
defmacro counter_cache_query(module) do
# CounterCache.__query__(unquote(module), @counter_cache_fields)
end
end
end
Hey @kip, one question: If I understand it right, __MODULE__ inside a quoted expression in a macro will expand to the invoking module like __CALLER__ outside of the quoted expression. So, I’m not sure I understood the difference, but I guess there’s a compilation order, would you mind explaining it a little bit more?
__MODULE__ always refers to the module being compiled. So when __MODULE__ is inside a quote block (assuming the macro returns the quote block), then __MODULE__ is expanded in the calling module. So yes, you are correct. In this case, __CALLER__.module in a macro outside a quote block is the same as __MODULE__ inside a quote block.
In your example, we need to access the caller outside the quote block. Because we need to guarantee that the module attribute is registered and set before the macro code is expanded in the caller. Therefore it needs to be executed in the context of the macro, not the context of the caller. And therefore we need to use __CALLER__.module approach.
Does that help? I find it useful to remember a few simple things about macros:
A macro is a function that accepts AST as parameters and is expected to return AST
A quote block returns AST and is the most common way to return AST from a macro. But its otherwise not special - you can quote in any code you like at compile time or runtime.
A macro is expanded at the time at which it is called. Macro expansion happens recursively until there is nothing left to expand.
A call to a macro replaces the macro call with the result of the macro call. It is interpolated at the calling site. And then compilation proceeds normally.
A macro is just normal Elixir code except for the requirement to accept AST and return AST so it can execute whatever you want - recognising that this code is executing during macro expansion at compile time, not at runtime.
Thanks, @kip, I think this is really helpful, but I still have some questions, for example:
defmodule Greeter do
defmacro greeting(name) do
quote do
Module.put_attribute(__MODULE__, :greeting, unquote(name))
end
end
defmacro __using__(opts) do
quote do
import Greeter
Module.register_attribute(__MODULE__, :greeting, accumulate: false)
def greet_inside() do
@greeting
end
end
end
end
defmodule Gentlemen do
use Greeter
greeting "Hello Sir"
def greet, do: @greeting
end
So, let’s see if I understand it right, the previous example will yield:
Considering that a macro is expanded when it’s called, so Greeter.__using__ is expanded first, adding the @greeting attribute to Gentlemen and defining the greet_inside() function, which outputs the @greeting attribute. So, greet_inside() outputs nil when its called because at compilation time the attribute was registered but no value was assigned to it yet. Then, the greeting macro is expanded and it adds "Hello Sir" to the @greeting attribute, and that’s why greet() outputs "Hello Sir". Is my understanding right? (does the code expands top to bottom sequentially like this?).
Considering I’m right, for this to work, greet_inside() has to be a macro otherwise @greeting would be evaluated to nil at that point. So I was expecting this to work:
defmacro greet_inside() do
quote do
@greeting
end
end
But it won’t, because when greet_inside() is imported and called (and expanded), I’m outside of a module (I’m testing it on iex) and I can’t access attributes outside of modules. I imagine that __CALLER__.module in that context won’t return anything either, so what are my other options?
I think I understood what you mean, but I’m having a hard time applying it for this scenario. I think it’s a little different because we are setting the attribute value after the macro that registered it? (unless macros are expanded all at once, so I wouldn’t have the reference to the attribute yet!?)
I realise this may just be an example, but in this example I don’t see what they need to use a module when import will work just as well and is clearer in most cases. Simplifying your example we get:
defmodule Greeter do
defmacro greeting(name) do
caller = __CALLER__.module
# Define the attribute and set it in the calling module
Module.register_attribute(caller, :greeting, accumulate: false)
Module.put_attribute(caller, :greeting, name)
# Code interpolated into the
# calling site
quote do
def greet_inside() do
@greeting
end
end
end
end
defmodule Gentlemen do
import Greeter
greeting "Hello Sir"
def greet, do: @greeting
end
Last thought, you might be wondering why this didn’t work:
defmacro __using__(opts) do
quote do
import Greeter
# This code will be inserted in the calling site and it will
# be executed at runtime, not compile time because it is
# in the quote block that will be inserted at the calling site
Module.register_attribute(__MODULE__, :greeting, accumulate: false)
def greet_inside() do
# Using @module_attribute requires that the module
# attribute exist *at compile time*. But the code above is
# only executed at runtime. Therefore the reference to
# @greeting will fail
@greeting
end
end
end
Hummmm, very very interesting… Thanks a lot for the explanations @kip! I think your example without use in particular made it a lot easier for me to understand. Also, the explanation about what is evaluated at runtime vs compile-time was on point, thanks a lot. I’ll start from here and I’ll read more about macros with that in mind, thanks a lot for sparring the time to educate me on the subject.
If perhaps someone finds this post in the future, I’ll leave a link to a gist with my final solution: Elixir's Ecto Counter Cache Manager · GitHub. Many thanks to @kip in special and the awesome Elixir documentation on the subject of macros.
Obs.: Working with macros is very fun, especially because Elixir makes metaprogramming very enjoyable compared to other languages. However, there’s a reason why the documentation warns us to proceed with caution haha .
.