Add annotations to CIF (discussion issue)

Introduction

We discussed adding annotations to CIF:

• From !398 (comment 1033233):

  There was some offline discussion elsewhere about not being able to specify in CIF what part of a CIF specification belongs to the safety PLC part and what to the regular PLC part. I wonder whether we also want to indicate what variables are PLC input/output variables, and maybe even to what input/output ports/addresses/etc they link. You propose to either inline or not inline some algebraic variables, maybe even letting users decide this.

  Looking at all these use cases, I wonder if it would be a good idea to introduce annotations to CIF. Then you could tag requirements with for instance @PlcSafety, variables with @PlcInput or @PlcOutput or even @PlcInput(address=5), etc.

  I have other use cases for this as well, unrelated to PLC code generation, in my daily work, where it would be useful to be able to annotate edges, or even events on edges.

  What do you think? Should we create a separate issue to discuss this further?

• From !398 (comment 1033276):

  [...] about input/output variables in plcgen. We solved that by having a CSV file that lists the CIF name, type, and address of input and output variables.

• From !398 (comment 1035806):

  Adding annotations here as improvement to the CSV file, to allow specifying it directly in the CIF specification instead.

Proposal

Textual syntax examples:

@plc:input(address=5) // For PLC code generator, to map variables etc to PLC inputs/outputs.
input bool x;

@plc:safety // For PLC code generator, to indicate what requirements are safety requirements.
requirement e needs Sensor.on;

automaton a:
  @state:origin(grp1.aut1="loc1", grp2.aut5="loc7") // For the event-based tools to add the origin to generated locations.
  location s1:
    initial;
end

Design decisions and constraints:

• Regarding purposes of annotations: Annotations allow us to test out language extensions before actually adding them to the language. They also allow for extensibility, as anyone can add annotations, whether it is general purpose, company-specific, for private use, or even for testing.
• Allow annotations on various objects. Which ones is to be decided. But likely at least all named objects. I have a use case for edge events as well. Likely we start simple, and extend later.
• You may add any number of annotations to the same object. The order is not relevant (it is a set).
• Annotations are named by a CIF identifiers, separated by colons. E.g., name, some:name, some:anno:name. The multiple levels of : allow for nesting, to categorize annotations that belong together, e.g., for the same application/tool, or even for sub-categories for a single tool/use.
• We can think of naming conventions. Ideally annotations are named to not be tool-specific, but rather on a conceptual level. Maybe we want some way to prevent overlap by requiring the first part to be 'owned' by yourself?
• The CIF documentation should at least document the 'official' annotation names in use by the CIF language and toolkit.
• You may not add multiple annotations with the same name to the same object.
• You may add any number of arguments (key/value pairs) to the annotation. The order does not matter (it is a set).
• Annotation arguments are named by a CIF name (allows . in it). E.g., param, grp.aut.
• You may not add multiple arguments with the same name to a single annotation.
• Annotations are defined through an extension point, similar to ToolDef libraries. This defines the name of the annotation. It also defines the parameters. This includes their name (as a regex allowing multiple arguments to be defined at once), whether they are optional or mandatory, and their CIF type. We could extend it later with mutual exclusion requirements, etc, but let's start simple.
• Extension points are identified by a Java-like identifier, used internally by the tools to find 'their' extension. These names don't appear in CIF specifications. Extension points thus define both their unique identifier (e.g. org.eclipse.escet.something.Name) and their syntax form (e.g. something:name).
• All uses of annotations are checked against the registered annotations, based on the annotations registered in the current environment. Any other annotation is not forbidden, but will result in a warning. This allows loading specification of others with non-registered annotations, while still being informed that it is not supported in your environment.
• Annotation arguments must be valid CIF expressions that can be statically evaluated.
• If you refer to objects from the CIF specification in such an expression, the value of that object is used (as usual in CIF expressions). It is not a reference to the object that can be retrieved by tools processing the annotations, as they can only obtain the value that results from evaluating the expression.
• All tools document what annotations they support and produce, and how they handle/use them.
• In the textual syntax, the @name part is mandatory. The parentheses are optional, unless arguments are given. Arguments are separated by commas.
• We can think of short-hand notations later. For instance, if there is only one mandatory parameter, the argument name could be optional.
• This is a language change, and thus we should consider the impact, maintenance, interplay with other language features, effect on syntax, type checker, CIF to CIF transformations, common library, various tools, etc.

Edit:

• 2022-11-28: The example for @Origin had parameter values that were identifiers. These likely don't refer to existing objects. This was meant to be a string. Fixed now.
• 2022-11-28: Annotations are named with a CIF name, rather than a CIF identifier. Explained naming convention.
• 2022-11-28: Explain better that parameter values are CIF expressions, and are parsed and type checked as such.
• 2022-11-28: Added that parameter values must be statically evaluable CIF expressions.
• 2022-11-29: Added foreseen purposes of annotations.
• 2022-11-29: Changed annotation names to use : rather than .. Added explanation of why multiple levels in annotation names is useful.
• 2022-11-29: Added something about naming conventions, and documenting 'official' annotations.
• 2022-11-29: Documented that the order of the annotations and annotation arguments does not matter.
• 2022-11-29: Changed how annotations are defined and checked.
• 2022-11-29: Added that short forms are to be considered later.
• 2022-11-30: Made it clear how object references in annotation argument values are processed.