Annotations

Annotations can be used to add metadata to certain features in the source code. Types, methods, instance variables, and method/macro parameters may be annotated. User-defined annotations, such as the standard library’s JSON::Field, are defined using the annotation keyword. A number of built-in annotations are provided by the compiler.

Users can define their own annotations using the annotation keyword, which works similarly to defining a class or struct.

  1. annotation MyAnnotation
  2. end

The annotation can then be applied to various items, including:

  • Instance and class methods
  • Instance variables
  • Classes, structs, enums, and modules
  • Method and macro parameters (though the latter are currently unaccessable)
  1. annotation MyAnnotation
  2. end
  4. @[MyAnnotation]
  5. def foo
  6.   "foo"
  7. end
  9. @[MyAnnotation]
  10. class Klass
  11. end
  13. @[MyAnnotation]
  14. module MyModule
  15. end
  17. def method1(@[MyAnnotation] foo)
  18. end
  20. def method2(
  21.   @[MyAnnotation]
  22.   bar
  23. )
  24. end
  26. def method3(@[MyAnnotation] & : String ->)
  27. end

Applications

Annotations are best used to store metadata about a given instance variable, type, or method so that it can be read at compile time using macros. One of the main benefits of annotations is that they are applied directly to instance variables/methods, which causes classes to look more natural since a standard macro is not needed to create these properties/methods.

A few applications for annotations:

Object Serialization

Have an annotation that when applied to an instance variable determines if that instance variable should be serialized, or with what key. Crystal’s JSON::Serializable and YAML::Serializable are examples of this.

ORMs

An annotation could be used to designate a property as an ORM column. The name and type of the instance variable can be read off the TypeNode in addition to the annotation; removing the need for any ORM specific macro. The annotation itself could also be used to store metadata about the column, such as if it is nullable, the name of the column, or if it is the primary key.

Fields

Data can be stored within an annotation.

  1. annotation MyAnnotaion
  2. end
  4. # The fields can either be a key/value pair
  5. @[MyAnnotation(key: "value", value: 123)]
  7. # Or positional
  8. @[MyAnnotation("foo", 123, false)]

Key/value

The values of annotation key/value pairs can be accessed at compile time via the [] method.

  1. annotation MyAnnotation
  2. end
  4. @[MyAnnotation(value: 2)]
  5. def annotation_value
  6.   # The name can be a `String`, `Symbol`, or `MacroId`
  7.   {{ @def.annotation(MyAnnotation)[:value] }}
  8. end
  10. annotation_value # => 2

The named_args method can be used to read all key/value pairs on an annotation as a NamedTupleLiteral. This method is defined on all annotations by default, and is unique to each applied annotation.

  1. annotation MyAnnotation
  2. end
  4. @[MyAnnotation(value: 2, name: "Jim")]
  5. def annotation_named_args
  6.   {{ @def.annotation(MyAnnotation).named_args }}
  7. end
  9. annotation_named_args # => {value: 2, name: "Jim"}

Since this method returns a NamedTupleLiteral, all of the methods on that type are available for use. Especially #double_splat which makes it easy to pass annotation arguments to methods.

  1. annotation MyAnnotation
  2. end
  4. class SomeClass
  5.   def initialize(@value : Int32, @name : String); end
  6. end
  8. @[MyAnnotation(value: 2, name: "Jim")]
  9. def new_test
  10.   {% begin %}
  11.     SomeClass.new {{ @def.annotation(MyAnnotation).named_args.double_splat }}
  12.   {% end %}
  13. end
  15. new_test # => #<SomeClass:0x5621a19ddf00 @name="Jim", @value=2>

Positional

Positional values can be accessed at compile time via the [] method; however, only one index can be accessed at a time.

  1. annotation MyAnnotation
  2. end
  4. @[MyAnnotation(1, 2, 3, 4)]
  5. def annotation_read
  6.   {% for idx in [0, 1, 2, 3, 4] %}
  7.     {% value = @def.annotation(MyAnnotation)[idx] %}
  8.     pp "{{ idx }} = {{ value }}"
  9.   {% end %}
  10. end
  12. annotation_read
  14. # Which would print
  15. "0 = 1"
  16. "1 = 2"
  17. "2 = 3"
  18. "3 = 4"
  19. "4 = nil"

The args method can be used to read all positional arguments on an annotation as a TupleLiteral. This method is defined on all annotations by default, and is unique to each applied annotation.

  1. annotation MyAnnotation
  2. end
  4. @[MyAnnotation(1, 2, 3, 4)]
  5. def annotation_args
  6.   {{ @def.annotation(MyAnnotation).args }}
  7. end
  9. annotation_args # => {1, 2, 3, 4}

Since the return type of TupleLiteral is iterable, we can rewrite the previous example in a better way. By extension, all of the methods on TupleLiteral are available for use as well.

  1. annotation MyAnnotation
  2. end
  4. @[MyAnnotation(1, "foo", true, 17.0)]
  5. def annotation_read
  6.   {% for value, idx in @def.annotation(MyAnnotation).args %}
  7.     pp "{{ idx }} = #{{{ value }}}"
  8.   {% end %}
  9. end
  11. annotation_read
  13. # Which would print
  14. "0 = 1"
  15. "1 = foo"
  16. "2 = true"
  17. "3 = 17.0"

Reading

Annotations can be read off of a TypeNode, Def, MetaVar, or Arg using the .annotation(type : TypeNode) method. This method return an Annotation object representing the applied annotation of the supplied type.

Note

If multiple annotations of the same type are applied, the .annotation method will return the last one.

The @type and @def variables can be used to get a TypeNode or Def object to use the .annotation method on. However, it is also possible to get TypeNode/Def types using other methods on TypeNode. For example TypeNode.all_subclasses or TypeNode.methods, respectively.

Tip

Checkout the parse_type method for a more advanced way to obtain a TypeNode.

The TypeNode.instance_vars can be used to get an array of instance variable MetaVar objects that would allow reading annotations defined on those instance variables.

Note

TypeNode.instance_vars currently only works in the context of an instance/class method.

  1. annotation MyClass
  2. end
  4. annotation MyMethod
  5. end
  7. annotation MyIvar
  8. end
  10. annotation MyParameter
  11. end
  13. @[MyClass]
  14. class Foo
  15.   pp {{ @type.annotation(MyClass).stringify }}
  17.   @[MyIvar]
  18.   @num : Int32 = 1
  20.   @[MyIvar]
  21.   property name : String = "jim"
  23.   def properties
  24.     {% for ivar in @type.instance_vars %}
  25.       pp {{ ivar.annotation(MyIvar).stringify }}
  26.     {% end %}
  27.   end
  28. end
  30. @[MyMethod]
  31. def my_method
  32.   pp {{ @def.annotation(MyMethod).stringify }}
  33. end
  35. def method_params(
  36.   @[MyParameter(index: 0)]
  37.   value : Int32,
  38.   @[MyParameter(index: 1)] metadata,
  39.   @[MyParameter(index: 2)] & : -> String
  40. )
  41.   pp {{ @def.args[0].annotation(MyParameter).stringify }}
  42.   pp {{ @def.args[1].annotation(MyParameter).stringify }}
  43.   pp {{ @def.block_arg.annotation(MyParameter).stringify }}
  44. end
  46. Foo.new.properties
  47. my_method
  48. method_params 10, false do
  49.   "foo"
  50. end
  51. pp {{ Foo.annotation(MyClass).stringify }}
  53. # Which would print
  54. "@[MyClass]"
  55. "@[MyIvar]"
  56. "@[MyIvar]"
  57. "@[MyMethod]"
  58. "@[MyParameter(index: 0)]"
  59. "@[MyParameter(index: 1)]"
  60. "@[MyParameter(index: 2)]"
  61. "@[MyClass]"

Warning

Annotations can only be read off of typed block parameters. See https://github.com/crystal-lang/crystal/issues/5334.

Reading Multiple Annotations

If there are multiple annotations of the same type applied to the same instance variable/method/type, the .annotations(type : TypeNode) method can be used. This will work on anything that .annotation(type : TypeNode) would, but instead returns an ArrayLiteral(Annotation).

  1. annotation MyAnnotation
  2. end
  4. @[MyAnnotation("foo")]
  5. @[MyAnnotation(123)]
  6. @[MyAnnotation(123)]
  7. def annotation_read
  8.   {% for ann, idx in @def.annotations(MyAnnotation) %}
  9.     pp "Annotation {{ idx }} = {{ ann[0].id }}"
  10.   {% end %}
  11. end
  13. annotation_read
  15. # Which would print
  16. "Annotation 0 = foo"
  17. "Annotation 1 = 123"
  18. "Annotation 2 = 123"