Documentation for gololang.meta.Annotations

Module to deal with java annotations.

To flag a golo element with a Java annotation, one must add some metadata to the IR element. The metadata will be used by the compiler to add the required bytecode.

To add such metadata, the most direct way is to create a macro that modify the IR node.

This module provides functions to ease the creation of such macros by:

Moreover, since the creation of simple macro that only adds the metadata to the element is just boilerplate code, macros to generate such macros are provided ( annotationWrapper, annotationWrapper and annotationWrapper)

Finally, a helper function to mark a element as deprecated is also provided.



Macro to generate a macro to add a Java annotation to a golo element.

The name of the macro is the simple name of the annotation class, its documentation is auto-generated.

See annotationWrapper

annotationWrapper(annotation, name)

Macro to generate a macro to add a Java annotation to a golo element.

The name of the generated macro is given and its documentation is auto-generated.

See annotationWrapper

annotationWrapper(annotation, name, doc)

Macro to generate a macro to add a Java annotation to a golo element.

For instance, to create a macro to apply the mypackage.MyAnnotation Java annotation, one must create a macro such as:

Apply the `MyAnnotation` annotation
macro annotation = |args...| {
  let a, u, e = extractAnnotationArguments(mypackage.MyAnnotation.class, args)
  return annotateElements(mypackage.MyAnnotation.class, a, e)

used as

@annotation(prop1="hello", prop2=42)
function foo = -> null

(given the annotation has the prop1 and prop2 properties.

This macro generate the corresponding macro, thus allowing to simply write

    "Apply the `MyAnnotation` annotation")

See also extractAnnotationArguments and annotateElements


addAnnotationMetadata(annotationClass, args, target)

Adds an annotation metadata to an element.

This is a low-level function, no check is done.

See annotateElements for a higher level function.

See extractAnnotationArguments.

annotateElements(annotationClass, args, elts...)

Adds an annotation to the given elements.

This function correctly deal with several elements by returning a ToplevelElements, and can therefore be used directly by a macro.

The properties of the annotation are given in a map as returned by extractAnnotationArguments. For instance, to have the equivalent of the Java code:

@mypackage.MyAnnotation(prop1="hello", prop2=42)
public static Object foo() {
  return null;

one should annotate the foo function definition IR with:

      ["prop1", "hello"],
      ["prop2", 42]

See annotationWrapper, extractAnnotationArguments

checkApplicableTo(annotationClass, target)

Checks if a Java annotation can be applied to a golo element.

Inspect the annotation's Target annotation.

extractAnnotationArguments(annotation, args)

Parse the macro arguments according to an annotation class.

The named arguments of the macro are matched with the annotation fields. If the annotation has at most one field, positional argument can be used. The named is extracted using reflection on the annotation class. The annotation fields are returned in a map of the name and values

See parseArguments,


makeDeprecated(since, comment, elts...)

Mark the element as deprecated, by setting the deprecated metadata and adding the java.lang.Deprecated annotation. Indeed, the annotation by itself is not sufficient, since a bytecode flag must also be set for the element to be considered deprecated by the Java compiler. The bytecode generator use the deprecated metadata to set this flag.

Moreover, the documentation of the concerned element is also updated to document the deprecation.

Can be applied to function declarations, types, or augmentations. Otherwise, the element is returned unchanged.

This function should not need to be called directly. Use the gololang.macros::deprecated macro instead