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:

• adding the annotation metadata (annotateElements)
• parsing the macro arguments and match them with the annotation fields (extractAnnotationArguments)
• checking that the target has a valid type w.r.t. the annotation definition (checkApplicableTo)

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.

• param annotation: the litteral fully qualified class reference to the annotation to use.
• returns a macro that will add the given annotation to a golo element

See annotationWrapper

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.

• param annotation: the litteral fully qualified class reference to the annotation to use.
• param name: the name of the generated macro (as a reference lookup, i.e. a name, not a string).
• returns a macro that will add the given annotation to a golo element

See annotationWrapper

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

&annotationWrapper(
    mypackage.MyAnnotation.class,
    annotation,
    "Apply the `MyAnnotation` annotation")

• param annotation: the litteral fully qualified class reference to the annotation to use.
• param name: the name of the generated macro (as a reference lookup, i.e. a name, not a string).
• param doc: the litteral string of the documentation for the generated macro.
• returns a macro that will add the given annotation to a golo element

See also extractAnnotationArguments and annotateElements

Adds an annotation metadata to an element.

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

See annotateElements for a higher level function.

• param annotationClass: the class of the annotation to add
• param args: a map representing the annotation arguments
• param target: the element to annotate
• returns the element itself

See extractAnnotationArguments.

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:

annotateElements(
    mypackage.MyAnnotation.class,
    map[
      ["prop1", "hello"],
      ["prop2", 42]
    ],
    theFooIR)

• param annotationClass: The class of the annotation.
• param args: a map of the properties of the annotation.
• param elts: the IR elements to annotate.
• returns the annotated element itself if there is only one, or a ToplevelElements if there are several.

See annotationWrapper, extractAnnotationArguments

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

Inspect the annotation's Target annotation.

• param annotationClass: the class of the Java annotation
• param target: the golo IR element to annotate
• throws an exception if the element can't be annotated.

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

• param annotation: the annotation class
• param args: the full array of arguments of the macro
• returns a tuple containing a map of named arguments,

      a map of named arguments not recognized by the annotation,
      and an array of elements to annotate
  

See parseArguments,

[`getLiteralValue`](../macros/Utils.html#getLiteralValue_1)

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.

• param since: the version in which the element became deprecated.
• param comment: a comment to append to the element documentation.
• param elts: the element to mark as deprecated.
• returns the elements, wrapped in a ToplevelElements if required

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