github.com/jhump/annogo
Package annogo provides runtime support for Go annotations. This package is referenced from code generated by aptgo, for providing runtime access to annotation values that are intended to be runtime-visible. The various Register* functions should not be called directly, but instead only called from generated code. The other functions can then be used to inspect runtime-visible annotation values (which were registered from said generated code during package initialization). It also provides the foundational meta-annotations, which Go developers use to define their own annotations. Annotations on constructs in Go source code take the form of specially-formatted comments. At the end of normal Go doc, add annotations by writing annotation values, starting with an at sign ("@") in front of each annotation type (similar to annotation syntax in Java). Any comment line that starts with such an at sign is assumed by annotation processors to be the first line of annotations, and all comment lines following it are also assumed to be part of the annotations. So, for packages with annotations (e.g. those on which you might run the aptgo tool or other processing tools), it is important that no Go doc for any element have a line that starts with the at sign ("@") unless that line is the start of the doc'ed element's annotations. Like a statement in the Go language, an annotation should be all on a single line or break lines after characters that do not break expressions (such as open braces, open parentheses, binary operators, commas, etc). Multiple annotations go on multiple lines, though they can all be crammed on a single line if they are separated with semicolons (again, like normal statements in the Go language). As seen in the examples above, a single annotation starts with the at sign ("@") followed by the name of the annotation type, including a package qualifier. With just the annotation name, the annotation's value is its zero value with one important exception: if the annotation type is a struct and it has any field with a @annogo.DefaultValue annotation, that field will have the specified default value (not the field's zero value). If the annotation type is a struct and has any fields with a @annogo.Required annotation, values *must* be indicated in the annotation, so this syntax (annotation type without a value) will not be allowed. Annotations that indicate values can use one of two syntaxes: If the annotation type is a scalar, the value must be in parenthesis, just like a type conversion expression in normal Go code. If the annotation type is a composite type (struct, array, slice, or map), the values are in curly braces, just like the syntax for composite literals in normal Go code. // Scalar value @pkg.IntegerAnnotation(123) // Composite value @pkg.SliceAnnotation{123, 456, 789} There are two exceptions to these rules: These promotions are syntactic sugar to make annotation values more concise. The first case, an annotation type that is a struct with a single field named "Value", is useful when using annotations that only allow annotation fields as the kind of annotated element. If the annotation type were defined as a scalar type, the value of that scalar type could not have this sort of annotation on it (since they would be on a type element, not a field). So you can work around this by instead declaring the annotation as a single-field struct and then apply the annotations to the one field. The syntax of annotation values is the same as the syntax for constant expressions in normal Go code with a few additions: Channel values cannot be expressed with annotation expressions other than via untyped literal nils. Expressions in annotation values do not support pointer operations such as pointer-dereference (*) or address-of (&). However, pointer types are allowed and operations, such as address-of, are handled transparently. Like in constant expressions in normal Go code, function calls are disallowed except for a few special builtin functions for manipulating complex values: imag(c), real(c), and complex(fr, fi). This package contains some meta-annotations, including the one that defines all other annotations: @annogo.Annotation. A meta-annotation is an annotation that is used only on other annotations (or their fields). They are used to define characteristics of other annotations. In addition to to @annogo.Annotation, there are some other meta-annotations in this package worth knowing about: Querying annotation values at runtime (for annotations that are visible at runtime) is done using functions in this package, too. (There are numerous Register* functions, which record the annotation values during package initialization. But these should only be used by the code that is generated by the aptgo tool.) The other functions take three shapes:
Readme
Annotations and annotation processing for Go!
Annotations take the shape of specially-formatted content in Go doc comments. They can appear on types declarations, interface elements (embedded interfaces and methods), struct fields, and other top-level program elements like consts, vars, and funcs (including methods).
Annotation values are strongly-typed and structured using syntax familiar to Go programmers:
Any type that has the @annogo.Annotation "meta-annotation" can be used as an
annotation type.
// @annogo.Annotation
type MyNewAnnotation struct {
Foo int
Bar []string
}
And it can then be referenced in annotations on other program elements:
// @MyNewAnnotation{Foo: 123, Bar: {"a", "b", "c"}}
var AnnotatedThing = 1
This repo includes a program, aptgo, that can be used in a go:generate
directive to perform annotation processing.
Its default behavior is to generate *.annos.go source code that contains
init functions that register all runtime-visible annotation values. This
allows programs to introspect, at runtime, on the annotations present on a
program element.
It also allows for invoking other processors that may perform custom logic to validate annotations and/or perform extra code generation based on the annotations.
To that end, this repo includes the processor sub-package, which provides
APIs used by annotation processors for querying annotations from source.
This is similar to Java's annotation processing functionality, and this
also includes an AnnotationMirror type, which allows processors to inspect
and interact with annotation values that are defined in source, even for
values whose types are not known to the processor.
FAQs
Package annogo provides runtime support for Go annotations. This package is referenced from code generated by aptgo, for providing runtime access to annotation values that are intended to be runtime-visible. The various Register* functions should not be called directly, but instead only called from generated code. The other functions can then be used to inspect runtime-visible annotation values (which were registered from said generated code during package initialization). It also provides the foundational meta-annotations, which Go developers use to define their own annotations. Annotations on constructs in Go source code take the form of specially-formatted comments. At the end of normal Go doc, add annotations by writing annotation values, starting with an at sign ("@") in front of each annotation type (similar to annotation syntax in Java). Any comment line that starts with such an at sign is assumed by annotation processors to be the first line of annotations, and all comment lines following it are also assumed to be part of the annotations. So, for packages with annotations (e.g. those on which you might run the aptgo tool or other processing tools), it is important that no Go doc for any element have a line that starts with the at sign ("@") unless that line is the start of the doc'ed element's annotations. Like a statement in the Go language, an annotation should be all on a single line or break lines after characters that do not break expressions (such as open braces, open parentheses, binary operators, commas, etc). Multiple annotations go on multiple lines, though they can all be crammed on a single line if they are separated with semicolons (again, like normal statements in the Go language). As seen in the examples above, a single annotation starts with the at sign ("@") followed by the name of the annotation type, including a package qualifier. With just the annotation name, the annotation's value is its zero value with one important exception: if the annotation type is a struct and it has any field with a @annogo.DefaultValue annotation, that field will have the specified default value (not the field's zero value). If the annotation type is a struct and has any fields with a @annogo.Required annotation, values *must* be indicated in the annotation, so this syntax (annotation type without a value) will not be allowed. Annotations that indicate values can use one of two syntaxes: If the annotation type is a scalar, the value must be in parenthesis, just like a type conversion expression in normal Go code. If the annotation type is a composite type (struct, array, slice, or map), the values are in curly braces, just like the syntax for composite literals in normal Go code. // Scalar value @pkg.IntegerAnnotation(123) // Composite value @pkg.SliceAnnotation{123, 456, 789} There are two exceptions to these rules: These promotions are syntactic sugar to make annotation values more concise. The first case, an annotation type that is a struct with a single field named "Value", is useful when using annotations that only allow annotation fields as the kind of annotated element. If the annotation type were defined as a scalar type, the value of that scalar type could not have this sort of annotation on it (since they would be on a type element, not a field). So you can work around this by instead declaring the annotation as a single-field struct and then apply the annotations to the one field. The syntax of annotation values is the same as the syntax for constant expressions in normal Go code with a few additions: Channel values cannot be expressed with annotation expressions other than via untyped literal nils. Expressions in annotation values do not support pointer operations such as pointer-dereference (*) or address-of (&). However, pointer types are allowed and operations, such as address-of, are handled transparently. Like in constant expressions in normal Go code, function calls are disallowed except for a few special builtin functions for manipulating complex values: imag(c), real(c), and complex(fr, fi). This package contains some meta-annotations, including the one that defines all other annotations: @annogo.Annotation. A meta-annotation is an annotation that is used only on other annotations (or their fields). They are used to define characteristics of other annotations. In addition to to @annogo.Annotation, there are some other meta-annotations in this package worth knowing about: Querying annotation values at runtime (for annotations that are visible at runtime) is done using functions in this package, too. (There are numerous Register* functions, which record the annotation values during package initialization. But these should only be used by the code that is generated by the aptgo tool.) The other functions take three shapes:
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The June TC39 meeting wrapped up this week with eight proposals moving on to the next stage. Here's a quick roundup of the features that the committee approved to advance.
Security News
Cyber extortion in the US and Canada hit record levels in 2023, with ransomware attacks surging and median ransom demands skyrocketing, though fewer companies are choosing to pay ransoms.
Security News
Ecma TC39 is meeting this week and has moved key ECMAScript proposals forward, advancing Deferred Import Evaluation, Error.isError(), RegExp Escaping, and Promise.try to the next stages.