---

name: crystal-macros description: Use when implementing compile-time metaprogramming in Crystal using macros for code generation, DSLs, compile-time computation, and abstract syntax tree manipulation. allowed-tools: [Bash, Read]

Crystal Macros

You are Claude Code, an expert in Crystal's macro system and compile-time metaprogramming. You specialize in building powerful abstractions, DSLs, and code generation systems using Crystal's compile-time execution capabilities.

Your core responsibilities:

• Write macros for code generation and boilerplate reduction
• Build domain-specific languages (DSLs) using macro methods
• Implement compile-time computations and validations
• Generate methods, classes, and modules dynamically
• Manipulate abstract syntax trees (AST) at compile time
• Create type-safe abstractions through macro expansion
• Build debugging and introspection tools
• Implement compile-time configuration and feature flags
• Generate serialization and deserialization code
• Design annotation-based programming patterns

Macro Basics

Macros run at compile time and receive AST nodes as arguments. They can generate and return code that gets inserted into the program.

Simple Macro Definition

# Basic macro that generates a method
macro define_getter(name)
  def {{name}}
    @{{name}}
  end
end

class Person
  def initialize(@name : String, @age : Int32)
  end

  define_getter name
  define_getter age
end

person = Person.new("Alice", 30)
puts person.name  # Generated method
puts person.age   # Generated method

Macro with Multiple Arguments

macro define_property(name, type)
  @{{name}} : {{type}}?

  def {{name}} : {{type}}?
    @{{name}}
  end

  def {{name}}=(value : {{type}})
    @{{name}} = value
  end
end

class Config
  define_property host, String
  define_property port, Int32
  define_property ssl, Bool

  def initialize
  end
end

config = Config.new
config.host = "localhost"
config.port = 8080
puts config.host

Macro with Block

macro measure_time(name, &block)
  start_time = Time.monotonic
  {{yield}}
  elapsed = Time.monotonic - start_time
  puts "{{name}} took #{elapsed.total_milliseconds}ms"
end

measure_time("database query") do
  sleep 0.5
  # Database operation here
end

String Interpolation in Macros

Macros use {{}} for interpolation and can generate identifiers, literals, and code.

Generating Method Names

macro define_flag_methods(name)
  def {{name}}?
    @{{name}}
  end

  def {{name}}!
    @{{name}} = true
  end

  def clear_{{name}}
    @{{name}} = false
  end
end

class FeatureFlags
  def initialize
    @feature_a = false
    @feature_b = false
  end

  define_flag_methods feature_a
  define_flag_methods feature_b
end

flags = FeatureFlags.new
flags.feature_a!
puts flags.feature_a?  # true
flags.clear_feature_a
puts flags.feature_a?  # false

Generating with String Manipulation

macro define_enum_helpers(enum_type)
  {% for member in enum_type.resolve.constants %}
    def {{member.downcase.id}}?
      self == {{enum_type}}::{{member}}
    end
  {% end %}
end

enum Status
  Pending
  Running
  Completed
  Failed
end

class Job
  def initialize(@status : Status)
  end

  def status
    @status
  end

  # Generate pending?, running?, completed?, failed?
  define_enum_helpers Status
end

job = Job.new(Status::Pending)
puts job.pending?    # true
puts job.running?    # false

Compile-Time Iteration

Macros can iterate over collections at compile time using {% for %}.

Iterating Over Arrays

macro define_constants(*names)
  {% for name, index in names %}
    {{name.upcase.id}} = {{index}}
  {% end %}
end

class ErrorCodes
  define_constants success, not_found, unauthorized, server_error
end

puts ErrorCodes::SUCCESS        # 0
puts ErrorCodes::NOT_FOUND      # 1
puts ErrorCodes::UNAUTHORIZED   # 2
puts ErrorCodes::SERVER_ERROR   # 3

Iterating Over Hash Literals

macro define_validators(**rules)
  {% for name, validator in rules %}
    def validate_{{name.id}}(value)
      {{validator}}
    end
  {% end %}
end

class Validator
  define_validators(
    email: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
    phone: /\A\d{3}-\d{3}-\d{4}\z/,
    zip_code: /\A\d{5}(-\d{4})?\z/
  )
end

validator = Validator.new
puts validator.validate_email("test@example.com")
puts validator.validate_phone("555-123-4567")

Iterating Over Type Methods

macro log_all_methods(type)
  {% for method in type.resolve.methods %}
    puts "Method: {{method.name}}"
  {% end %}
end

class Calculator
  def add(a, b)
    a + b
  end

  def subtract(a, b)
    a - b
  end
end

# At compile time, this generates puts statements
macro list_calculator_methods
  log_all_methods Calculator
end

Conditional Compilation

Use {% if %} for compile-time conditionals based on flags, types, or expressions.

Platform-Specific Code

macro platform_specific_path
  {% if flag?(:windows) %}
    "C:\\Program Files\\MyApp"
  {% elsif flag?(:darwin) %}
    "/Applications/MyApp.app"
  {% elsif flag?(:linux) %}
    "/usr/local/bin/myapp"
  {% else %}
    "/tmp/myapp"
  {% end %}
end

DEFAULT_PATH = {{platform_specific_path}}
puts DEFAULT_PATH

Feature Flags

macro with_feature(flag, &block)
  {% if flag?(flag) %}
    {{yield}}
  {% end %}
end

class Application
  with_feature(:debug) do
    def debug_info
      puts "Debug mode enabled"
    end
  end

  with_feature(:metrics) do
    def record_metric(name, value)
      puts "Recording #{name}: #{value}"
    end
  end
end

# Compile with: crystal build app.cr -Ddebug -Dmetrics

Type-Based Conditionals

macro generate_serializer(type)
  {% if type.resolve < Number %}
    def serialize_{{type.name.downcase.id}}(value : {{type}}) : String
      value.to_s
    end
  {% elsif type.resolve == String %}
    def serialize_{{type.name.downcase.id}}(value : {{type}}) : String
      value.inspect
    end
  {% elsif type.resolve < Array %}
    def serialize_{{type.name.downcase.id}}(value : {{type}}) : String
      "[" + value.map(&.to_s).join(", ") + "]"
    end
  {% end %}
end

class Serializer
  generate_serializer Int32
  generate_serializer String
  generate_serializer Array(Int32)
end

s = Serializer.new
puts s.serialize_int32(42)
puts s.serialize_string("hello")
puts s.serialize_array_int32([1, 2, 3])

AST Node Types

Macros receive different types of AST nodes. Understanding these is crucial.

Inspecting AST Nodes

macro show_ast(expression)
  {{expression.class_name}}
end

# NumberLiteral
puts {{show_ast(42)}}

# StringLiteral
puts {{show_ast("hello")}}

# Call
puts {{show_ast(foo.bar)}}

# ArrayLiteral
puts {{show_ast([1, 2, 3])}}

Working with Identifiers

macro create_accessor(name)
  # name is a SymbolLiteral or StringLiteral
  # Convert to identifier with .id
  def {{name.id}}
    @{{name.id}}
  end

  def {{name.id}}=(value)
    @{{name.id}} = value
  end
end

class User
  def initialize
    @username = ""
  end

  create_accessor :username
end

Manipulating String Literals

macro define_constants_from_string(str)
  {% parts = str.split(",") %}
  {% for part in parts %}
    {{part.strip.upcase.id}} = {{part.strip.id.stringify}}
  {% end %}
end

module Colors
  define_constants_from_string("red, green, blue, yellow")
end

puts Colors::RED     # "red"
puts Colors::GREEN   # "green"
puts Colors::BLUE    # "blue"
puts Colors::YELLOW  # "yellow"

Advanced Macro Patterns

Building a DSL for Routes

macro route(method, path, handler)
  {% ROUTES ||= [] of {String, String, String} %}
  {% ROUTES << {method.stringify, path, handler.stringify} %}
end

macro compile_routes
  ROUTES_MAP = {
    {% for route in ROUTES %}
      {{route[1]}} => {{route[2].id}},
    {% end %}
  }

  def handle_request(method : String, path : String)
    handler_name = ROUTES_MAP[path]?
    return not_found unless handler_name

    case handler_name
    {% for route in ROUTES %}
    when {{route[2]}}
      {{route[2].id}}
    {% end %}
    end
  end
end

class WebApp
  route :get, "/", :index
  route :get, "/about", :about
  route :post, "/users", :create_user

  def index
    "Home Page"
  end

  def about
    "About Page"
  end

  def create_user
    "Create User"
  end

  def not_found
    "404 Not Found"
  end

  compile_routes
end

Automatic JSON Serialization

macro json_serializable(*fields)
  def to_json(builder : JSON::Builder)
    builder.object do
      {% for field in fields %}
        builder.field {{field.stringify}} do
          @{{field.id}}.to_json(builder)
        end
      {% end %}
    end
  end

  def self.from_json(parser : JSON::PullParser)
    instance = allocate
    {% for field in fields %}
      {{field.id}} = nil
    {% end %}

    parser.read_object do |key|
      case key
      {% for field in fields %}
      when {{field.stringify}}
        {{field.id}} = typeof(instance.@{{field.id}}).from_json(parser)
      {% end %}
      end
    end

    {% for field in fields %}
      instance.@{{field.id}} = {{field.id}}.not_nil!
    {% end %}

    instance
  end
end

class User
  def initialize(@name : String, @age : Int32, @email : String)
  end

  json_serializable name, age, email
end

user = User.new("Alice", 30, "alice@example.com")
json = user.to_json
puts json

Compile-Time Configuration

macro configure(&block)
  {% begin %}
    {% config = {} of String => ASTNode %}
    {{yield}}
    {% for key, value in config %}
      {{key.upcase.id}} = {{value}}
    {% end %}
  {% end %}
end

macro set(key, value)
  {% config[key.stringify] = value %}
end

configure do
  set :app_name, "MyApp"
  set :version, "1.0.0"
  set :max_connections, 100
  set :debug, true
end

puts APP_NAME           # "MyApp"
puts VERSION            # "1.0.0"
puts MAX_CONNECTIONS    # 100
puts DEBUG              # true

Macro Methods

Macro methods are called on types and can access compile-time type information.

Generating Methods from Type Info

class Model
  macro inherited
    # Called when a class inherits from Model
    def self.table_name : String
      {{@type.name.underscore.id.stringify}}
    end

    def self.column_names : Array(String)
      [
        {% for ivar in @type.instance_vars %}
          {{ivar.name.stringify}},
        {% end %}
      ]
    end
  end
end

class User < Model
  def initialize(@name : String, @email : String, @age : Int32)
  end
end

puts User.table_name       # "user"
puts User.column_names     # ["name", "email", "age"]

Property Introspection

class Base
  macro generate_initializer
    def initialize(
      {% for ivar in @type.instance_vars %}
        @{{ivar.name}} : {{ivar.type}},
      {% end %}
    )
    end

    def to_s(io : IO)
      io << "{{@type.name}}("
      {% for ivar, index in @type.instance_vars %}
        {% if index > 0 %}
          io << ", "
        {% end %}
        io << "{{ivar.name}}="
        @{{ivar.name}}.inspect(io)
      {% end %}
      io << ")"
    end
  end
end

class Person < Base
  @name : String
  @age : Int32
  @city : String

  generate_initializer
end

person = Person.new("Bob", 25, "NYC")
puts person  # Person(name="Bob", age=25, city="NYC")

Method Delegation

macro delegate(*methods, to target)
  {% for method in methods %}
    def {{method.id}}(*args, **kwargs)
      @{{target.id}}.{{method.id}}(*args, **kwargs)
    end

    def {{method.id}}(*args, **kwargs, &block)
      @{{target.id}}.{{method.id}}(*args, **kwargs) { |*yield_args| yield *yield_args }
    end
  {% end %}
end

class UserRepository
  def find(id : Int32)
    "User #{id}"
  end

  def all
    ["User 1", "User 2"]
  end

  def create(name : String)
    "Created #{name}"
  end
end

class UserService
  def initialize
    @repository = UserRepository.new
  end

  delegate find, all, create, to: repository
end

service = UserService.new
puts service.find(1)
puts service.all

Debugging Macros

Compile-Time Printing

macro debug_print(value)
  {{puts value}}
  {{value}}
end

# This will print at compile time
result = {{debug_print(42 + 8)}}

# Print type information at compile time
macro show_type_info(type)
  {% puts "Type: #{type.resolve}" %}
  {% puts "Instance vars: #{type.resolve.instance_vars.map(&.name)}" %}
  {% puts "Methods: #{type.resolve.methods.map(&.name)}" %}
end

class Example
  @x : Int32 = 0
  @y : String = ""

  def foo
  end

  def bar
  end
end

{{show_type_info(Example)}}

Macro Expansion Inspection

# Use --no-codegen flag to see macro expansion
# crystal build --no-codegen app.cr

macro verbose_property(name, type)
  {{puts "Generating property #{name} of type #{type}"}}

  @{{name}} : {{type}}?

  def {{name}} : {{type}}?
    {{puts "Generating getter for #{name}"}}
    @{{name}}
  end

  def {{name}}=(value : {{type}})
    {{puts "Generating setter for #{name}"}}
    @{{name}} = value
  end
end

class Config
  verbose_property timeout, Int32
  verbose_property host, String
end

When to Use This Skill

Use the crystal-macros skill when you need to:

• Reduce boilerplate code through code generation
• Build domain-specific languages (DSLs) for configuration or business logic
• Generate repetitive methods, classes, or modules
• Implement compile-time validation and type checking
• Create property definitions with custom behavior
• Generate serialization/deserialization code
• Build annotation-based programming patterns
• Implement automatic delegation or proxying
• Create compile-time configuration systems
• Generate database models from schema definitions
• Build testing frameworks with custom assertions
• Implement compile-time dependency injection
• Create type-safe builder patterns
• Generate API clients from specifications
• Implement aspect-oriented programming patterns

Best Practices

1. Keep Macros Simple: Break complex macros into smaller, composable pieces
2. Document Macro Behavior: Explain what code the macro generates and why
3. Use Meaningful Names: Macro names should clearly indicate what they generate
4. Validate Inputs: Check macro arguments at compile time when possible
5. Prefer Macro Methods: Use macro methods over top-level macros for type-specific logic
6. Use {{yield}}: Pass blocks to macros for flexible code generation
7. Debug with {{puts}}: Print AST nodes and values during macro development
8. Test Generated Code: Verify that macro-generated code works as expected
9. Avoid Overuse: Only use macros when the benefit outweighs the complexity
10. Use Type Information: Leverage @type and reflection for powerful abstractions
11. Handle Edge Cases: Consider nil values, empty collections, and type variations
12. Maintain Readability: Generated code should be as readable as hand-written code
13. Version Carefully: Macro changes can break downstream code; version appropriately
14. Use Conditional Compilation: Leverage flags for platform-specific or feature-specific code
15. Document Expansion: Show example of expanded code in macro documentation

Common Pitfalls

1. Forgetting .id Conversion: Literals must be converted to identifiers with .id
2. String vs Symbol Confusion: Know when to use stringify vs literal interpolation
3. Infinite Macro Recursion: Recursive macros must have proper termination conditions
4. Scope Issues: Variables in macro scope vs generated code scope can conflict
5. Type Resolution Timing: Some type information isn't available during early compilation
6. Missing Nil Checks: Generated code may not handle nil properly
7. Hardcoded Assumptions: Macros assuming specific type structures that may change
8. Poor Error Messages: Compilation errors in generated code are hard to debug
9. Overusing Global State: Class variables in macros can cause unexpected behavior
10. Not Handling Empty Collections: Iterating over empty arrays/hashes without checks
11. Syntax Errors in Templates: Invalid Crystal syntax in macro bodies causes confusing errors
12. Type Mismatch: Generated code doesn't match expected types
13. Namespace Pollution: Generating too many methods or constants in global scope
14. Platform Dependencies: Not handling platform differences in macro logic
15. Circular Dependencies: Macros that depend on types that depend on the same macros

Resources

• Crystal Macros Guide
• Crystal API - Macros
• Crystal Metaprogramming
• Crystal Macro Hooks
• Crystal AST Nodes
• Crystal Book - Compile Time Flags
• Effective Crystal - Macro Patterns