//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2010, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::../_part_attributes.asciidoc[]

:leveloffset: -2

[[tools-cif2cif-chapter-lift-events]]
== Lift events

indexterm:[CIF to CIF transformer,lift events]
indexterm:[lift events]
indexterm:[event,lift to specification]
This CIF to CIF transformation lifts event declarations to the top level of the specification.

indexterm:[lift events,supported specifications]

=== Supported specifications

This transformation supports a subset of CIF specifications.
The following restrictions apply:

* Component definitions and component instantiations are not supported.

* Groups are not supported.

indexterm:[lift events,preprocessing]

=== Preprocessing

No preprocessing is currently performed by this CIF to CIF transformation.
To increase the subset of specifications that can be transformed, apply the following <<tools-cif2cif-chapter-index,CIF to CIF transformations>> (in the given order):

* <<tools-cif2cif-chapter-elim-comp-def-inst>>

* <<tools-cif2cif-chapter-groups>>

indexterm:[lift events,implementation]

=== Implementation details

All events declared in the automata, are lifted to the top level of the specification.

In order to be able to track the origin of the events, they are named after their absolute names.
For a group `x`, with a group `y`, with an event `e`, the absolute name of the event is `x.y.e`.
The event is lifted to the top level of the specification, and named `x_y_e`.

For instance, this specification:

[source, cif]
----
event e;

automaton a:
  event e;
  location;
end

group b:
  automaton c:
    event e;
    location;
  end
end
----

is transformed to the following specification:

[source, cif]
----
event e;
event a_e;
event b_c_e;

automaton a:
  location;
end

group b:
  automaton c:
    location;
  end
end
----

indexterm:[lift events,renaming]

=== Renaming

Since events of the automata are merged with the declarations of the specification, renaming may be necessary to ensure uniquely named declarations.
For instance, for a group `x`, with a group `y`, with an event `e`, the absolute name of the event is `x.y.e`.
The event is lifted to the top level of the specification, and renamed to `x_y_e`.
However, if the specification already contains a declaration of a constant, automaton, other event, etc, named `x_y_e`, then the lifted event is renamed to `x_y_e2` instead.
If that name is also already in use, it is renamed to `x_y_e3`, etc.

Whenever renaming takes place, a warning is printed to the console.

indexterm:[lift events,size considerations]

=== Size considerations

Events are lifted, which essentially means they are moved.
The size of the specification does not increase.

=== Optimality

n/a

=== Annotations

This transformation does not process or add any annotations.
If the specification has a <<lang-tut-annotations-controller,controller properties annotation>>, it is removed.
