Annotations

When you write EGL source code, you set annotations. They are values used by some aspect of the EGL system code, including the tooling, if any; the EGL compiler; the EGL generator; or the EGL deployer.

Annotations help ensure that your EGL-created output reflects your intent. You can set them when you define parts; when you declare variables and constants; when you code a subset of EGL statements; and, in some cases, when you declare functions.

For example, when you declare a field in a user-interface form, you might set a YES value in the InputRequired annotation. That setting causes the EGL generator to store a detail in the generated output, and the detail ensures that the user can submit the form only if the specified field has content. InputRequired is an example of a field-level annotation, which is an annotation that applies to data items and to declarations that are based on simple types.

Annotation type

An annotation represents an area of memory and is based on an EGL type. To understand these points, consider the following declaration:

myCarCount NumberOfCars { InputRequired = yes };

That code has effects at two different stages:

It declares the myCarCount variable. The appropriate declaration statement is generated into your output, and the related instance is available at run time. The type of the variable is NumberOfCars, which is an alias of type INT. Here is the alias, or data item:
```
DataItem 
   NumberOfCars INT 
End
```
The example also identifies an instance that is available at transformation time. The type of that instance is InputRequired. Here is the EGL Record part:
```
Record InputRequired type Annotation
   value Boolean;
End
```
The annotation is the typed value. It is not available in your runtime code.

All annotations are based on one or another EGL Record part.

Annotation syntax

The InputRequired declaration in the earlier source code did not set the value field explicitly. The InputRequired = Yes assignment is a shorthand form of the following code:

@InputRequired { value = yes }

The at sign (@) indicates that you are declaring an annotation, and the characters InputRequired indicate that the annotation is based on the InputRequired Record part. The next characters then assign content to the fields in the annotation. A later section explains the use of the braces ({ and }).

A shorthand form such as InputRequired = Yes is available whenever the Record part for the annotation has a single field, regardless of the name of that field.

If an annotation has multiple fields, only the long form of the declaration is valid, as in the following example:

@AnotherAnnotation { field01 = "test", field02 = 5 }

An annotation can be based on a Record part that has no fields. In that case, the mere presence of the annotation is meaningful to the EGL system code, and only the at sign (@) is required. Here is an example declaration:

@ThirdAnnotation

In many cases, you can declare multiple annotations, one separated from the next by a comma. For example, the following code declares the InputRequired and DisplayName annotations:

myCarCount NumberOfCars { InputRequired = yes, DisplayName = "Number of cars:  " };

Annotation overrides

You can declare an annotation when you define a data item or part, and then override the annotation when you declare a variable that is based on the data item or part. Here is a data item with two annotations:

DataItem
   NumberOfCars { InputRequired = no, DisplayName = "Number of cars:  " }
End

The following variable declaration overrides the previous value of the InputRequired annotation:

myCarCount NumberOfCars { InputRequired = yes };

If a data item or part includes several annotations and a few are overridden in a variable declaration, the annotations that were not overridden are still in effect. In the previous example, the myCarCount variable is associated with both the InputRequired and DisplayName annotations.

The ability to set multiple annotations is particularly important for data items. For example, a data item might be defined with annotations that are meaningful for user interface, for accessing a sequential file, and for accessing a relational database. The benefit of being able to specify multiple annotations is that you can retain data items in a library and use those data items for many purposes. When you use a data item to declare a variable for one purpose such as file access, the annotations relevant to other purposes such as user interface have no effect.

Most annotations have a relatively small effect. For example, the InputRequired annotation specifies whether a field in a user-interface form is generated in one way or another. But a stereotype is an annotation that affects a series of decisions; the effect is greater. For details, see “Stereotypes.”