github.com/jhump/annogo (go): 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:
Keywords: annotations|go|golang