Macros

Macros are methods that receive AST nodes at compile-time and produce code that is pasted into a program. For example:

  1. macro define_method(name, content)
  2.   def {{name}}
  3.     {{content}}
  4.   end
  5. end
  7. # This generates:
  8. #
  9. #     def foo
  10. #       1
  11. #     end
  12. define_method foo, 1
  14. foo # => 1

A macro’s definition body looks like regular Crystal code with extra syntax to manipulate the AST nodes. The generated code must be valid Crystal code, meaning that you can’t for example generate a def without a matching end, or a single when expression of a case, since both of them are not complete valid expressions. Refer to Pitfalls for more information.

Scope

Macros declared at the top-level are visible anywhere. If a top-level macro is marked as private it is only accessible in that file.

They can also be defined in classes and modules, and are visible in those scopes. Macros are also looked-up in the ancestors chain (superclasses and included modules).

For example, a block which is given an object to use as the default receiver by being invoked with with ... yield can access macros defined within that object’s ancestors chain:

  1. class Foo
  2.   macro emphasize(value)
  3.     "***#{ {{value}} }***"
  4.   end
  6.   def yield_with_self(&)
  7.     with self yield
  8.   end
  9. end
  11. Foo.new.yield_with_self { emphasize(10) } # => "***10***"

Macros defined in classes and modules can be invoked from outside of them too:

  1. class Foo
  2.   macro emphasize(value)
  3.     "***#{ {{value}} }***"
  4.   end
  5. end
  7. Foo.emphasize(10) # => "***10***"

Interpolation

You use {{...}} to paste, or interpolate, an AST node, as in the above example.

Note that the node is pasted as-is. If in the previous example we pass a symbol, the generated code becomes invalid:

  1. # This generates:
  2. #
  3. #     def :foo
  4. #       1
  5. #     end
  6. define_method :foo, 1

Note that :foo was the result of the interpolation, because that’s what was passed to the macro. You can use the method ASTNode#id in these cases, where you just need an identifier.

Macro calls

You can invoke a fixed subset of methods on AST nodes at compile-time. These methods are documented in a fictitious Crystal::Macros module.

For example, invoking ASTNode#id in the above example solves the problem:

  1. macro define_method(name, content)
  2.   def {{name.id}}
  3.     {{content}}
  4.   end
  5. end
  7. # This correctly generates:
  8. #
  9. #     def foo
  10. #       1
  11. #     end
  12. define_method :foo, 1

parse_type

Most AST nodes are obtained via either manually passed arguments, hard coded values, or retrieved from either the type or method information helper variables. Yet there might be cases in which a node is not directly accessible, such as if you use information from different contexts to construct the path to the desired type/constant.

In such cases the parse_type macro method can help by parsing the provided StringLiteral into something that can be resolved into the desired AST node.

  1. MY_CONST = 1234
  3. struct Some::Namespace::Foo; end
  5. {{ parse_type("Some::Namespace::Foo").resolve.struct? }} # => true
  6. {{ parse_type("MY_CONST").resolve }}                     # => 1234
  8. {{ parse_type("MissingType").resolve }} # Error: undefined constant MissingType

See the API docs for more examples.

Modules and classes

Modules, classes and structs can also be generated:

  1. macro define_class(module_name, class_name, method, content)
  2.   module {{module_name}}
  3.     class {{class_name}}
  4.       def initialize(@name : String)
  5.       end
  7.       def {{method}}
  8.         {{content}} + @name
  9.       end
  10.     end
  11.   end
  12. end
  14. # This generates:
  15. #     module Foo
  16. #       class Bar
  17. #         def initialize(@name : String)
  18. #         end
  19. #
  20. #         def say
  21. #           "hi " + @name
  22. #         end
  23. #       end
  24. #     end
  25. define_class Foo, Bar, say, "hi "
  27. p Foo::Bar.new("John").say # => "hi John"

Conditionals

You use {% if condition %} … {% end %} to conditionally generate code:

  1. macro define_method(name, content)
  2.   def {{name}}
  3.     {% if content == 1 %}
  4.       "one"
  5.     {% elsif content == 2 %}
  6.       "two"
  7.     {% else %}
  8.       {{content}}
  9.     {% end %}
  10.   end
  11. end
  13. define_method foo, 1
  14. define_method bar, 2
  15. define_method baz, 3
  17. foo # => one
  18. bar # => two
  19. baz # => 3

Similar to regular code, Nop, NilLiteral and a false BoolLiteral are considered falsey, while everything else is considered truthy.

Macro conditionals can be used outside a macro definition:

  1. {% if env("TEST") %}
  2.   puts "We are in test mode"
  3. {% end %}

Iteration

You can iterate a finite amount of times:

  1. macro define_constants(count)
  2.   {% for i in (1..count) %}
  3.     PI_{{i.id}} = Math::PI * {{i}}
  4.   {% end %}
  5. end
  7. define_constants(3)
  9. PI_1 # => 3.14159...
  10. PI_2 # => 6.28318...
  11. PI_3 # => 9.42477...

To iterate an ArrayLiteral:

  1. macro define_dummy_methods(names)
  2.   {% for name, index in names %}
  3.     def {{name.id}}
  4.       {{index}}
  5.     end
  6.   {% end %}
  7. end
  9. define_dummy_methods [foo, bar, baz]
  11. foo # => 0
  12. bar # => 1
  13. baz # => 2

The index variable in the above example is optional.

To iterate a HashLiteral:

  1. macro define_dummy_methods(hash)
  2.   {% for key, value in hash %}
  3.     def {{key.id}}
  4.       {{value}}
  5.     end
  6.   {% end %}
  7. end
  9. define_dummy_methods({foo: 10, bar: 20})
  10. foo # => 10
  11. bar # => 20

Macro iterations can be used outside a macro definition:

  1. {% for name, index in ["foo", "bar", "baz"] %}
  2.   def {{name.id}}
  3.     {{index}}
  4.   end
  5. {% end %}
  7. foo # => 0
  8. bar # => 1
  9. baz # => 2

Variadic arguments and splatting

A macro can accept variadic arguments:

  1. macro define_dummy_methods(*names)
  2.   {% for name, index in names %}
  3.     def {{name.id}}
  4.       {{index}}
  5.     end
  6.   {% end %}
  7. end
  9. define_dummy_methods foo, bar, baz
  11. foo # => 0
  12. bar # => 1
  13. baz # => 2

The arguments are packed into a TupleLiteral and passed to the macro.

Additionally, using * when interpolating a TupleLiteral interpolates the elements separated by commas:

  1. macro println(*values)
  2.   print {{*values}}, '\n'
  3. end
  5. println 1, 2, 3 # outputs 123\n

Type information

When a macro is invoked you can access the current scope, or type, with a special instance variable: @type. The type of this variable is TypeNode, which gives you access to type information at compile time.

Note that @type is always the instance type, even when the macro is invoked in a class method.

For example:

  1. macro add_describe_methods
  2.   def describe
  3.     "Class is: " + {{ @type.stringify }}
  4.   end
  6.   def self.describe
  7.     "Class is: " + {{ @type.stringify }}
  8.   end
  9. end
  11. class Foo
  12.   add_describe_methods
  13. end
  15. Foo.new.describe # => "Class is Foo"
  16. Foo.describe     # => "Class is Foo"

The top level module

It is possible to access the top-level namespace, as a TypeNode, with a special variable: @top_level. The following example shows its utility:

  1. A_CONSTANT = 0
  3. {% if @top_level.has_constant?("A_CONSTANT") %}
  4.   puts "this is printed"
  5. {% else %}
  6.   puts "this is not printed"
  7. {% end %}

Method information

When a macro is invoked you can access the method, the macro is in with a special instance variable: @def. The type of this variable is Def unless the macro is outside of a method, in this case it’s NilLiteral.

Example:

  1. module Foo
  2.   def Foo.boo(arg1, arg2)
  3.     {% @def.receiver %} # => Foo
  4.     {% @def.name %}     # => boo
  5.     {% @def.args %}     # => [arg1, arg2]
  6.   end
  7. end
  9. Foo.boo(0, 1)

Call Information

When a macro is called, you can access the macro call stack with a special instance variable: @caller. This variable returns an ArrayLiteral of Call nodes with the first element in the array being the most recent. Outside of a macro or if the macro has no caller (e.g. a hook) the value is a NilLiteral.

Note

As of now, the returned array will always only have a single element.

Example:

  1. macro foo
  2.   {{ @caller.first.line_number }}
  3. end
  5. def bar
  6.   {{ @caller }}
  7. end
  9. foo # => 9
  10. bar # => nil

Constants

Macros can access constants. For example:

  1. VALUES = [1, 2, 3]
  3. {% for value in VALUES %}
  4.   puts {{value}}
  5. {% end %}

If the constant denotes a type, you get back a TypeNode.

Nested macros

It is possible to define a macro which generates one or more macro definitions. You must escape macro expressions of the inner macro by preceding them with a backslash character “\“ to prevent them from being evaluated by the outer macro.

  1. macro define_macros(*names)
  2.   {% for name in names %}
  3.     macro greeting_for_{{name.id}}(greeting)
  4.       \{% if greeting == "hola" %}
  5.         "¡hola {{name.id}}!"
  6.       \{% else %}
  7.         "\{{greeting.id}} {{name.id}}"
  8.       \{% end %}
  9.     end
  10.   {% end %}
  11. end
  13. # This generates:
  14. #
  15. #     macro greeting_for_alice(greeting)
  16. #       {% if greeting == "hola" %}
  17. #         "¡hola alice!"
  18. #       {% else %}
  19. #         "{{greeting.id}} alice"
  20. #       {% end %}
  21. #     end
  22. #     macro greeting_for_bob(greeting)
  23. #       {% if greeting == "hola" %}
  24. #         "¡hola bob!"
  25. #       {% else %}
  26. #         "{{greeting.id}} bob"
  27. #       {% end %}
  28. #     end
  29. define_macros alice, bob
  31. greeting_for_alice "hello" # => "hello alice"
  32. greeting_for_bob "hallo"   # => "hallo bob"
  33. greeting_for_alice "hej"   # => "hej alice"
  34. greeting_for_bob "hola"    # => "¡hola bob!"

verbatim

Another way to define a nested macro is by using the special verbatim call. Using this you will not be able to use any variable interpolation but will not need to escape the inner macro characters.

  1. macro define_macros(*names)
  2.   {% for name in names %}
  3.     macro greeting_for_{{name.id}}(greeting)
  5.       # name will not be available within the verbatim block
  6.       \{% name = {{name.stringify}} %}
  8.       {% verbatim do %}
  9.         {% if greeting == "hola" %}
  10.           "¡hola {{name.id}}!"
  11.         {% else %}
  12.           "{{greeting.id}} {{name.id}}"
  13.         {% end %}
  14.       {% end %}
  15.     end
  16.   {% end %}
  17. end
  19. # This generates:
  20. #
  21. #     macro greeting_for_alice(greeting)
  22. #       {% name = "alice" %}
  23. #       {% if greeting == "hola" %}
  24. #         "¡hola {{name.id}}!"
  25. #       {% else %}
  26. #         "{{greeting.id}} {{name.id}}"
  27. #       {% end %}
  28. #     end
  29. #     macro greeting_for_bob(greeting)
  30. #       {% name = "bob" %}
  31. #       {% if greeting == "hola" %}
  32. #         "¡hola {{name.id}}!"
  33. #       {% else %}
  34. #         "{{greeting.id}} {{name.id}}"
  35. #       {% end %}
  36. #     end
  37. define_macros alice, bob
  39. greeting_for_alice "hello" # => "hello alice"
  40. greeting_for_bob "hallo"   # => "hallo bob"
  41. greeting_for_alice "hej"   # => "hej alice"
  42. greeting_for_bob "hola"    # => "¡hola bob!"

Notice the variables in the inner macro are not available within the verbatim block. The contents of the block are transferred “as is”, essentially as a string, until re-examined by the compiler.

Comments

Macro expressions are evaluated both within comments as well as compilable sections of code. This may be used to provide relevant documentation for expansions:

  1. {% for name, index in ["foo", "bar", "baz"] %}
  2.   # Provides a placeholder {{name.id}} method. Always returns {{index}}.
  3.   def {{name.id}}
  4.     {{index}}
  5.   end
  6. {% end %}

This evaluation applies to both interpolation and directives. As a result of this, macros cannot be commented out.

  1. macro a
  2.   # {% if false %}
  3.   puts 42
  4.   # {% end %}
  5. end
  7. a

The expression above will result in no output.

Merging Expansion and Call Comments

The @caller can be combined with the #doc_comment method in order to allow merging documentation comments on a node generated by a macro, and the comments on the macro call itself. For example:

  1. macro gen_method(name)
  2.  # {{ @caller.first.doc_comment }}
  3.  #
  4.  # Comment added via macro expansion.
  5.  def {{name.id}}
  6.  end
  7. end
  9. # Comment on macro call.
  10. gen_method foo

When generated, the docs for the #foo method would be like:

  1. Comment on macro call.
  3. Comment added via macro expansion.

Pitfalls

When writing macros (especially outside of a macro definition) it is important to remember that the generated code from the macro must be valid Crystal code by itself even before it is merged into the main program’s code. This means, for example, a macro cannot generate a one or more when expressions of a case statement unless case was a part of the generated code.

Here is an example of such an invalid macro:

  1. case 42
  2. {% for klass in [Int32, String] %} # Syntax Error: unexpected token: {% (expecting when, else or end)
  3.   when {{klass.id}}
  4.     p "is {{klass}}"
  5. {% end %}
  6. end

Notice that case is not within the macro. The code generated by the macro consists solely of two when expressions which, by themselves, is not valid Crystal code. We must include case within the macro in order to make it valid by using begin and end:

  1. {% begin %}
  2.   case 42
  3.   {% for klass in [Int32, String] %}
  4.     when {{klass.id}}
  5.       p "is {{klass}}"
  6.   {% end %}
  7.   end
  8. {% end %}