How to Use Macros in Elixir

Welcome back to this third part of our four-part series on metaprogramming in Elixir.

Previously, we established the underlying behavior of macros.

Now we will dive into the various applications of macros in Elixir using open-source Elixir libraries.

Let's go!

Using Macro Wrappers to Extend Elixir Module Behavior

Macros can extend module behavior by adding new functions through wrappers that behave similarly to inheritance in object-oriented programming (OOP).

To extend a module, we use use — this is syntactic sugar that performs the following for us:

1defmodule Foo do
2  defmacro __using__(opts) do
3    quote do
4      # Extend another module’s behavior here
5    end
6  end
7end
8
9defmodule Bar do
10  use Foo
11  # equivalent to calling these two expressions
12  # require Foo
13  # Foo.__using__([])
14end

The __using__ callback macro extends the behavior of Bar. It is injected into the callsite and expanded.

We will be using the following terminology:

Wrapper — a module that extends other modules like Foo.
Inheritor — a module that uses wrappers like Bar, inheriting behavior.

Let’s design a wrapper.

Say we are building a website that relies on several APIs to work. Assuming we use an HTTP client like HTTPoison and each API request has common configurations like request/response data type, we can handle the API requests in three ways:

Set up each API request separately.
Compose API requests by chaining functions that configure each request.
Build a wrapper that automatically configures each API request per request.

While each of these approaches has its merits, we will focus on the last approach.

HTTPoison offers a wrapper for building basic API wrappers through HTTPoison.Base. It handles aspects of an API request like setting up the endpoint and parsing the request/response body.

We will build another wrapper on top of this that will enable inheritors to achieve our business requirements:

Parse all request/response bodies to/from JSON.
Generate an API URL, given a base URL and an endpoint for the base URL.
Configure the request headers to accept JSON and set the content type to JSON.
Parse and handle response bodies.

The wrapper should produce inheritors like:

1defmodule DogWrapper do
2  use BaseWrapper, base_url: "https://api.dogs.com"
3
4  def upload(name, breed) do
5    case post?("upload", %{"name" => name, "breed" => breed}) do
6      {:ok, response} -> {:ok, response["link"]}
7      {:error, error} -> {:error, error}
8    end
9  end
10end
11
12defmodule CatWrapper do
13  use BaseWrapper, base_url: "https://api.cats.com"
14
15  def upload(name, breed, talkative) do
16    case post?("upload", %{"name" => name, "breed" => breed, "talkative" => talkative}) do
17      {:ok, response} -> {:ok, response["url"]}
18      {:error, error} -> {:error, error}
19    end
20  end
21end
22
23defmodule AnimalLovers do
24  def upload(:dog, name, breed) do
25    case DogWrapper.upload(name, breed) do
26      {:ok, link} -> redirect(link)
27      {:error, error} -> redirect_error(error)
28    end
29  end
30
31  def upload(:cat, name, breed, talkative) do
32    case CatWrapper.upload(name, breed, talkative) do
33      {:ok, link} -> redirect(link)
34      {:error, error} -> redirect_error(error)
35    end
36  end
37end

The inheritors do not contain any cumbersome API request logic. Instead, they focus on extracting data from the responses and executing the business logic.

Additionally, the wrapper integrates a base URL into the API requests, so inheritors provide only the endpoint.

Now we know what we want to accomplish, let’s build the wrapper.

First, we define our wrapper, calling it BaseWrapper. This module will define the __using__ callback.

opts is a keyword list that will hold the base_url of the inheritor, and it is bound to the quote.

location option for quote ensures that any errors will directly point to the line in the BaseWrapper.

Any behavior defined in quote will be injected into the inheritor.

1defmodule BaseWrapper do
2  defmacro __using__(opts) do
3    quote location: :keep, bind_quoted: [opts: opts] do
4      # behavior goes here
5    end
6  end
7end

Then, we extend our inheritor to use the basic behavior from HTTPoison.Base.

1# quote
2use HTTPoison.Base

Now, we want to retrieve the base URL from opts. We do not need to unquote opts as it was bound.

1# quote
2base_url = Keyword.get(opts, :base_url)

With that, we can begin configuring our wrapper using HTTPoison.Base.

HTTPoison.Base defines several callbacks used to process requests and responses.

We will override these callbacks to implement the behavior we want.

1# quote
2# Modify request headers to include necessary information about the API
3def process_request_headers(headers) do
4  h = [
5    {"Accept", "application/json"},
6    {"Content-Type", "application/json"}
7  ]
8
9  headers ++ h
10end
11
12# Generate the URL for the endpoint using a base URL received from the inheritor
13def process_url(endpoint), do: URI.merge(URI.parse(unquote(base_url)), endpoint) |> to_string()
14
15# Automatically encode request body to JSON
16def process_request_body(body), do: Jason.encode!(body)
17
18# Automatically decode request body from JSON
19def process_response_body(body), do: Jason.decode!(body)

Finally, we want to parse responses from POST requests based on the HTTP status code of the response.

1# quote
2def post?(endpoint, body) do
3  # post is available as we have used HTTPoison.Base which will perform the necessary imports for us
4  # post receives only the endpoint of the request as process_url prepends the base URL already
5  response = post(endpoint, body)
6  # We defer the parsing of the response to a function within the BaseWrapper module.
7  # Reasons for doing so will be discussed later
8  BaseWrapper.parse_post(response)
9end
10
11# BaseWrapper
12def parse_post({:ok, %HTTPoison.Response{status_code: code, body: body}})
13    when code in 200..299 do
14  {:ok, body}
15end
16
17def parse_post({:ok, %HTTPoison.Response{body: body}}) do
18  IO.inspect(body)
19  error = body |> Map.get("error", body |> Map.get("errors", ""))
20  {:error, error}
21end
22
23def parse_post({:error, %HTTPoison.Error{reason: reason}}) do
24  IO.inspect("reason #{reason}")
25  {:error, reason}
26end

Putting all this together, we have a module that looks like this:

1defmodule BaseWrapper do
2  defmacro __using__(opts) do
3    quote location: :keep, bind_quoted: [opts: opts] do
4      use HTTPoison.Base
5
6      base_url = Keyword.get(opts, :base_url)
7
8      def process_request_headers(headers) do
9        h = [
10          {"Accept", "application/json"},
11          {"Content-Type", "application/json"}
12        ]
13
14        headers ++ h
15      end
16      def process_url(endpoint), do: URI.merge(URI.parse(unquote(base_url)), endpoint) |> to_string()
17      def process_request_body(body), do: Jason.encode!(body)
18      def process_response_body(body), do: Jason.decode!(body)
19
20      # Function injected at compile-time to parse and act on responses accordingly
21      def post?(url, body) do
22        response = post(url, body)
23        BaseWrapper.parse_post(response)
24      end
25    end
26  end
27
28  def parse_post({:ok, %HTTPoison.Response{status_code: code, body: body}})
29      when code in 200..299 do
30    {:ok, body}
31  end
32
33  def parse_post({:ok, %HTTPoison.Response{body: body}}) do
34    IO.inspect(body)
35    error = body |> Map.get("error", body |> Map.get("errors", ""))
36    {:error, error}
37  end
38
39  def parse_post({:error, %HTTPoison.Error{reason: reason}}) do
40    IO.inspect("reason #{reason}")
41    {:error, reason}
42  end
43end

We've used macro wrappers to extend module behavior. Now, let's focus our attention on performing batch imports using wrappers.

Batch Imports with Macro Wrappers

We can use wrappers to perform batch imports in inheritors.

We can define a group of imports/aliases/requires that will be available during compile-time without performing the imports manually in the inheritor.

This is useful when several inheritors require the same set of imports and is best illustrated in Hound — a browser automation testing library:

1# lib/hound/helpers.ex
2defmacro __using__([]) do
3  quote do
4    import Hound
5    import Hound.Helpers.Cookie
6    import Hound.Helpers.Dialog
7    import Hound.Helpers.Element
8    import Hound.Helpers.Navigation
9    import Hound.Helpers.Orientation
10    import Hound.Helpers.Page
11    import Hound.Helpers.Screenshot
12    import Hound.Helpers.SavePage
13    import Hound.Helpers.ScriptExecution
14    import Hound.Helpers.Session
15    import Hound.Helpers.Window
16    import Hound.Helpers.Log
17    import Hound.Helpers.Mouse
18    import Hound.Matchers
19    import unquote(__MODULE__)
20  end
21end

Hound overrides __using__ to import a host of helper modules available to the inheritor.

The inheritors are always going to be test suites written by other developers. It is convenient and easy to maintain imports through use Hound.Helpers.

Next up, wrappers can also override and dynamically generate functions. Let's see how that works.

Macro Wrappers Define Functions to Override

Like a child class overrides a method in its parent class in OOP, wrappers can define some base behavior for functions and allow inheritors to override this behavior.

This is achieved using defoverridable.

Phoenix uses this to great effect by allowing inheritors of Phoenix.Controller.Pipeline to override functions like init and call to include context-specific behavior.

However, if a custom behavior isn't necessary — i.e. the function is not overwritten — the base behavior will be used instead:

1# lib/phoenix/controller/pipeline.ex
2defmacro __using__(opts) do
3  quote bind_quoted: [opts: opts] do
4    # ...
5
6    @doc false
7    def init(opts), do: opts
8
9    @doc false
10    def call(conn, action) when is_atom(action) do
11      conn
12      |> merge_private(
13        phoenix_controller: __MODULE__,
14        phoenix_action: action
15      )
16      |> phoenix_controller_pipeline(action)
17    end
18
19    @doc false
20    def action(%Plug.Conn{private: %{phoenix_action: action}} = conn, _options) do
21      apply(__MODULE__, action, [conn, conn.params])
22    end
23
24    defoverridable init: 1, call: 2, action: 2
25  end
26end

Macro Wrappers Dynamically Generate Functions

You can also use unquote fragments to dynamically define an arbitrary number of functions. These functions are injected into a module during compile-time. This is especially useful when working with dynamic data or data that comes from an API.

This article will focus on the former, as Metaprogramming Elixir includes a wonderful example of dynamically defining functions for API responses under the code/hub/.

Let's say we are building a script that reads a list of groceries and generates functions for each category. These functions will operate on each unique category and the items within it.

For simplicity, each function will be the category's name and print the contents of the category.

The grocery list will use the following format — <category>:<comma separated list>:

1// groceries.txt
2dinner:carrots,potatoes,curry,chicken cubes
3supplies:paper,pencils
4school:folder,binder

We can read this file in an Elixir script:

1# groceries.exs
2defmodule Groceries do
3  @filename "groceries.txt"
4  for line <- File.stream!(Path.join([__DIR__, @filename]), [], :line) do
5    # line represents each line of the groceries list
6  end
7end

We've extracted the lines of groceries, now we can parse each line:

1# for
2[category, rest] = line |> String.split(":") |> Enum.map(&String.trim(&1))
3groceries = rest |> String.split(",") |> Enum.map(&String.trim(&1))

Then we can define our dynamic functions.

We use unquote as an argument for def. def is also a macro, so expands the unquote along with anything in its body during compilation. This is known as an unquote fragment.

1# for
2def unquote(String.to_atom(category))() do
3  readable_list = Enum.join(unquote(groceries), " and ")
4  IO.puts("Groceries in #{unquote(category)} include #{readable_list}")
5end

Putting it all together, we get the following script:

1# groceries.exs
2defmodule Groceries do
3  @filename "groceries.txt"
4  for line <- File.stream!(Path.join([__DIR__, @filename]), [], :line) do
5    [category, rest] = line |> String.split(":") |> Enum.map(&String.trim(&1))
6    groceries = rest |> String.split(",") |> Enum.map(&String.trim(&1))
7
8    def unquote(String.to_atom(category))() do
9      readable_list = Enum.join(unquote(groceries), " and ")
10      IO.puts("Groceries in #{unquote(category)} include #{readable_list}")
11    end
12  end
13end
14
15iex(1)> Groceries.dinner
16Groceries in dinner include carrots and potatoes and curry and chicken cubes
17:ok
18iex(2)> Groceries.school
19Groceries in school include folder and binder
20:ok

Now let's turn our attention to implementing domain-specific languages (DSLs) using macros.

Implement Domain-Specific Languages using Macros

Domain-Specific Languages (DSLs) are "computer language(s) specialized to a particular application domain."

DSLs can be built and used in Elixir to solve business requirements.

As the official DSL tutorial points out:

You don’t need macros in order to have a DSL: every data structure and every function you define in your module is part of your Domain-specific language.

However, we will cover a simple implementation of a DSL using macros to demonstrate how that would look.

The simplest example of a DSL is from ExUnit, a built-in testing framework (taken from the ExUnit documentation):

1defmodule AssertionTest do
2  use ExUnit.Case, async: true
3
4  test "the truth" do
5    assert true
6  end
7end

test is a macro that registers a new test case.

These test cases are collated using accumulating module attributes. Then, when the test suite executes, all of the declared test cases are executed.

You can find a simplified implementation and explanation of this DSL in the official tutorial.

Absinthe — an implementation of the GraphQL specification — has a DSL for defining schemas.

1# lib/absinthe/schema/notation.ex
2defmacro object(identifier, attrs, do: block) do
3  {attrs, block} =
4    case Keyword.pop(attrs, :meta) do
5      {nil, attrs} ->
6        {attrs, block}
7
8      {meta, attrs} ->
9        meta_ast =
10          quote do
11            meta unquote(meta)
12          end
13
14        block = [meta_ast, block]
15        {attrs, block}
16    end
17
18  __CALLER__
19  |> recordable!(:object, @placement[:object])
20  |> record!(
21    Schema.ObjectTypeDefinition,
22    identifier,
23    attrs |> Keyword.update(:description, nil, &wrap_in_unquote/1),
24    block
25  )
26end

object is a macro that generates the GraphQL schema.

We define it as a macro because we're accessing compile-time information through __CALLER__, and we're attempting to work with the module's metadata. Defining it as a macro loads the schemas during compile-time.

Even the routing functions in Phoenix are a DSL.

Alchemist Camp's 'Creating a DSL for our router' video series explains how to implement a routing system similar to Phoenix's.

It's time to move on to Abstract Syntax Trees (ASTs): how they can be traversed and when to use prewalk vs. postwalk macros.

Traversing Abstract Syntax Trees (ASTs)

We introduced ASTs in part one of this series. You can traverse an existing AST to extract information about — or modify — the structure of the AST to:

Improve performance
Simplify the AST
Perform computations based on the structure of the AST

As the modification of ASTs is a niche process and context-dependent, we will focus on how traversal is performed rather than the specific application of traversal.

Going Back to the Roots of ASTs

Before we can understand the traversal of ASTs, we have to get to grips with the core data structure of ASTs.

Source code is parsed into trees — data structures that house hierarchical tree data. They begin with a root node, followed by a set of sub-trees — children nodes.

Each node includes a reference to its children. Each childless node is known as a leaf.

The figure below illustrates the basic anatomy of a tree:

Order of Traversal in ASTs

Now that we know the underlying data structure of an AST, we can tackle the problem of traversing an AST/tree.

Elixir uses depth-first traversal in either pre-order or post-order.

Depth-first traversal follows a node down to its children recursively until reaching a leaf. The sibling of the node is moved to next, and the recursion repeats.

Depth-first search of tree data structures

(Source: Wikimedia Commons)

If we use our example, the nodes are visited in the following order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7.

Pre-order and post-order traversal refer to how depth-first traversal occurs:

Pre-order traversal starts from the root node and traverses depth-first through the AST until the right-most leaf is reached.

In our tree, the nodes would be visited in the following order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7.

Post-order traversal starts from the left-most leaf of each sub-tree and traverses in depth-first fashion until we reach the root node.

In our tree, the nodes would be visited in the following order: 2 -> 4 -> 5 -> 7 -> 6 -> 3 -> 1. The traversal happens upwards towards the root node.

Regardless of the traversal order, the traversal occurs recursively until the "end condition" — i.e., right-most leaf for pre-order and root node for post-order.

In Elixir, functions represent each type of traversal:

Macro.prewalk — performs depth-first, pre-order traversal
Macro.postwalk — performs depth-first, post-order traversal
Macro.traverse — performs depth-first traversal and both pre and post-order traversal on the AST

By traversing the tree in a given order, we can extract information about the AST and use it to modify the AST.

We define functions that will be executed recursively on every node during traversal. These functions are similar to map.

The input is the currently visited node, while the output is a modified/untouched node.

Prewalk vs. Postwalk Macros

You might ask: "What is the benefit of using pre-order traversal over post-order traversal, and vice versa?"

In most scenarios, there is no difference between the two as both will traverse the AST.

However, you'll have a preference for postwalk or prewalk if the operation is order-sensitive — i.e., if you require the traversal to start at the root node or the left-most leaf first.

This may happen when the operation aims to match the first node (in order) against a given condition and only perform the operation on that node. We would rather have the traversal find the node quickly to operate as soon as possible.

In this case, prewalk is preferred over postwalk if the node appears at the beginning of the AST.

1Macro.prewalk(ast, fn
2  {:match, [], args} -> foo(args)
3  otherwise -> otherwise
4)

Another consideration is unintended infinite recursion. Take this example:

1Macro.prewalk({:foo, [], [:bar]}, fn
2  {:foo, [], _} -> {:foo, [], [{:foo, [], [:bar]}]}
3  otherwise -> otherwise
4end)

In this prewalk, the function matches any node that calls the foo function and replaces it with a recursive call to foo, with foo as the argument.

This will produce an infinite AST that, when converted to Elixir code, will look something like foo(foo(foo(...))).

prewalk is recursively executed on an AST — usually until it reaches the right-most leaf, indicating the AST's end. However, as the AST expands infinitely in the above example, there will never be a right-most leaf, hence infinite recursion.

Using postwalk instead avoids this issue as we simply replace the node once and move on upwards to the root node where the recursion will stop.

1Macro.postwalk({:foo, [], [:bar]}, fn
2  {:foo, [], _} -> {:foo, [], [{:foo, [], [:bar]}]}
3  otherwise -> otherwise
4end)
5
6{:foo, [], [{:foo, [], [:bar]}]}

So, while the choice of prewalk and postwalk might not matter when an operation is not order-sensitive, postwalk is preferred over prewalk to avoid infinite recursion.

traverse combines prewalk and postwalk, performing both together. This is useful when we want to traverse the AST in both orders.

Ecto uses prewalk to count the number of interpolations within a given expression.

In this case, there isn't a specific reason to choose prewalk over postwalk.

1# lib/ecto/query/builder.ex
2def bump_interpolations(expr, params) do
3  len = length(params)
4
5  Macro.prewalk(expr, fn
6    # The following expression matches a pinned variable which is what Ecto relies on for
7    # interpolation
8    {:^, meta, [counter]} when is_integer(counter) -> {:^, meta, [len + counter]}
9    other -> other
10  end)
11end

Ecto also uses postwalk to expand dynamic expressions.

1# lib/ecto/query/builder/dynamic.ex
2defp expand(query, %{fun: fun}, {binding, params, subqueries, count}) do
3  {dynamic_expr, dynamic_params, dynamic_subqueries} = fun.(query)
4
5  Macro.postwalk(dynamic_expr, {binding, params, subqueries, count}, fn
6    {:^, meta, [ix]}, {binding, params, subqueries, count} ->
7      case Enum.fetch!(dynamic_params, ix) do
8        {%Ecto.Query.DynamicExpr{binding: new_binding} = dynamic, _} ->
9          binding = if length(new_binding) > length(binding), do: new_binding, else: binding
10          expand(query, dynamic, {binding, params, subqueries, count})
11
12        param ->
13          {{:^, meta, [count]}, {binding, [param | params], subqueries, count + 1}}
14      end
15
16    {:subquery, i}, {binding, params, subqueries, count} ->
17      subquery = Enum.fetch!(dynamic_subqueries, i)
18      ix = length(subqueries)
19      {{:subquery, ix}, {binding, [{:subquery, ix} | params], [subquery | subqueries], count + 1}}
20
21    expr, acc ->
22      {expr, acc}
23  end)
24end

Another way you can change module behavior using macros is through compile-time hooks — let's take a quick look at those.

Compile-time Hooks with Macros

Compile-time hooks allow the compilation behavior of a module to be modified. Callbacks accompany these hooks.

The two notable hooks to discuss are @before_compile and @after_compile. They are useful when we want to perform computation right before — or right after — module compilation.

For now, let's look at a basic set of examples for each hook.

With @before_compile, as the callback (defmacro __before_compile__(env)) is called right before compilation, the callback must be declared in a separate module from where the hook references it.

If the callback is declared in the same module, the macro will not compile in time.

1defmodule Foo do
2  defmacro __before_compile__(env) do
3    IO.inspect(env)
4    nil
5  end
6end
7
8defmodule Bar do
9  @before_compile Foo
10end

An exception to this behavior is when Bar is an inheritor of Foo:

1defmodule Foo do
2  defmacro __using__(_) do
3    quote do
4      @before_compile unquote(__MODULE__)
5    end
6  end
7
8  defmacro __before_compile__(env) do
9    IO.inspect(env)
10    nil
11  end
12end
13
14defmodule Bar do
15  use Foo
16end

In this example, as @before_compile is injected into Bar, its callback is defined in Foo (a different module). Since use calls require, it ensures that Foo is compiled before Bar. This means Foo.__before_compile__/1 is always available to Bar.

With @after_compile, there isn't a need to declare the callback (defmacro __after_compile__(env, bytecode)) in another module. This is because the module housing the callback is already compiled, so the callback is available.

1defmodule Foo do
2  @after_compile __MODULE__
3
4  def __after_compile__(env, _bytecode) do
5    IO.inspect(env)
6    nil
7  end
8end

Another hook that is worth mentioning briefly is @on_definition, which invokes its callback whenever a function/macro is defined in the current module.

ExUnit uses @before_compile in a test suite to inject a final function — __ex_unit__ — to execute the test suites after they have been collated.

This function must be injected right before compilation when all the test suites are collated.

You may also wish to store a list of data across macro invocation, such as when ExUnit collates test cases and invokes them all at once.

This can be achieved using module attributes. Let's see that in action.

Module Attributes as Temporary Storage

When we set a module attribute to accumulate, any invocation of the module attribute will add the given value to the list, rather than overriding it:

1defmodule Foo do
2  Module.register_attribute(__MODULE__, :names, accumulate: true)
3  @names "John"
4  @names "Peter"
5
6  def print, do: IO.inspect(@names)
7end
8
9iex(1)> Foo.print
10["Peter", "John"]

We may also want to accumulate values through a function call.

This happens when the parent module first compiles, and then a secondary module updates the module attribute via a macro, like so:

1defmodule Foo do
2  defmacro add(name) do
3    quote do
4      @names unquote(name)
5      :ok
6    end
7  end
8end
9
10defmodule Bar do
11  require Foo
12  import Foo
13
14  Module.register_attribute(__MODULE__, :names, accumulate: true)
15
16  add "john"
17  add "henry"
18
19  IO.inspect(@names) # This prints ["henry", "john"] right after the module is done compiling
20end

Foo must compile first. The attribute has to be registered under Bar before it can be used in a given module.

The exception to this rule is use:

1defmodule Foo do
2  defmacro __using__(_) do
3    quote do
4      import Foo
5      Module.register_attribute(__MODULE__, :names, accumulate: true)
6    end
7  end
8
9  defmacro add(name) do
10    quote do
11      @names unquote(name)
12      :ok
13    end
14  end
15end
16
17defmodule Bar do
18  use Foo
19
20  add "john"
21  add "henry"
22
23  IO.inspect(@names) # This prints ["henry", "john"] right after the module is done compiling
24end

This is how ExUnit accumulates test cases and uses @before_compile to inject a "run all test cases in test suite" function right before compilation, similar to something like this:

1defmodule Calculator do
2  def add(a, b), do: a + b
3  def subtract(a, b), do: a - b
4end
5
6defmodule TestCase do
7  defmacro __using__(_) do
8    quote do
9      import TestCase
10      Module.register_attribute(__MODULE__, :tests, accumulate: true)
11      @before_compile unquote(__MODULE__)
12    end
13  end
14
15  defmacro __before_compile__(_env) do
16    # Inject a run function into the test case after all tests have been accumulated
17    quote do
18      def run do
19        Enum.each @tests, fn test_name ->
20          result = apply(__MODULE__, test_name, [])
21          state = if result, do: "pass", else: "fail"
22          IO.puts "#{test_name} => #{state}"
23        end
24      end
25    end
26  end
27
28  defmacro test(description, do: body) do
29    test_name = String.to_atom(description)
30    quote do
31      @tests unquote(test_name)
32      def unquote(test_name)(), do: unquote(body)
33    end
34  end
35end
36
37defmodule CalculatorTest do
38  use TestCase
39  import Calculator
40
41  test "add 1, 2 should return 3" do
42    add(1, 2) == 3
43  end
44
45  test "subtract 5, 2 should not return 4" do
46    subtract(5, 2) == 4
47  end
48end
49
50CalculatorTest.run
51"add 1, 2 should return 3" => pass
52"subtract 5, 2 should not return 4" => fail

Finally, we'll touch on deferring computation using macros.

Deferring Computation with Macros

Macros inject behavior into the callsite as-is and can be used to avoid immediate evaluation of an expression.

For instance:

1defmodule Foo do
2  def if?(condition, do: block, else: else_block) do
3    case condition do
4      true -> block
5      false -> else_block
6    end
7  end
8end
9
10Foo.if? true do
11  IO.puts("Truth")
12else
13  IO.puts("False")
14end
15
16"Truth"
17"False"

Here, we tried implementing the new if using a regular function. However, the result is not what we expect — rather than only evaluating and printing "Truth", both "Truth" and "False" are printed.

This is because of the nature of a regular function: each block is evaluated immediately, so the case will not work.

If we use a macro instead, the macro has to be expanded first, generating an AST of the case first and evaluating the case accordingly. During this time, the condition is evaluated, before matching against the case, and, finally, the appropriate block is evaluated.

Note: This example is borrowed from Metaprogramming Elixir.