Package io.github.douira.glsl_transformer.transform

Class Transformation<T>

java.lang.Object
io.github.douira.glsl_transformer.transform.Transformation<T>
Direct Known Subclasses:
WrapIdentifier, WrapIdentifierDynamic
public class Transformation<T> extends Object
The transformation is the vehicle through which transformation phases, which do all the actual transforming work, are added to the phase collector. It also holds any inter-phase state that may be necessary for a transformation. Since a transformation is independent of a phase collector since it only contains a list of phases and their indexes, it could be added to multiple phase collectors. However, they can't execute a single transformation in separate threads as that would mess up the transformation's state. Phases can, however, be added multiple times or to multiple phases. Beware of sharing state between transformations as that could cause issues. A stateless (no inter-phase state) transformation can be created by simply making an instance of this class and adding transformations to it. If state between phases is needed, make a subclass and add any state as instance fields. Then phases are created and added within the subclass' constructor. There cannot be any state stored as local variables either in the scope that created the Transformation instance or in a subclass' constructor as it will not be reset if a transformation is run multiple times. In the same vein, state should only be initialized in the resetState() method. TODO: unclear if sharing phases between transformation managers is problematic since then the compiled paths/patterns in phases have a different parser than the one being used for the transformation. Probably it doesn't matter and the parser is just used to figure out how the rules of the tree are.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    Transformation.PhaseEntry<T>
    The record used to store added transformation phases with their ordering index and group index.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_GROUP
    The default group index.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Transformation()
    Creates a stateless transformation with no transformation phases, which can be added later.
    Transformation(TransformationPhase<T> phase)
    Creates a stateless transformatio n and adds a single phase to it.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addConcurrentPhase(TransformationPhase<T> phase)
    Adds a transformation phase to this transformation at the previous phase counter position without incrementing the current phase counter.
    void
    addPhase(int index, int group, TransformationPhase<T> phase)
    Adds a transformation phase to this transformation in a given group and at a given position within that group.
    void
    addPhase(int index, TransformationPhase<T> phase)
    Adds a transformation phase to this transformation at a specific order but in the default group.
    void
    addPhase(Transformation.PhaseEntry<T> entry)
    Adds a transformation phase entry to this transformation.
    void
    addPhase(TransformationPhase<T> phase)
    Adds a transformation phase to this transformation.
    void
    addPhases(Collection<Transformation.PhaseEntry<T>> entries)
    Adds a whole collection of phases to this transformation.
    void
    append(Transformation<T> other)
    Appends all phases from another transformation to this one.
    protected int
    getDefaultGroup()
    Returns the default group for this transformation that is used for adding phases if not specified otherwise.
    void
    merge(Transformation<T> other)
    Adds all phases from another transformation into this one.
    protected void
    resetState()
    This method is called by the phase collector each time a tree is transformed in order to reset or initialize the state of the transformation if it has any.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_GROUP

      public static final int DEFAULT_GROUP
      The default group index. If no group index is specified, this group index is used. All phases without an explicit group index are added in this group. If all phases are added without a group index, they are effectively only ordered by their ordering index.
      See Also:

  • Constructor Details

    • Transformation

      public Transformation(TransformationPhase<T> phase)
      Creates a stateless transformatio n and adds a single phase to it. If you want to add multiple phases to a transformation, create an instance and call addPhase(TransformationPhase) multiple times.
      Parameters:
      phase - The only transformation phase to add to a new stateless transformation

    • Transformation

      public Transformation()
      Creates a stateless transformation with no transformation phases, which can be added later.

  • Method Details

    • addPhase

      public void addPhase(TransformationPhase<T> phase)
      Adds a transformation phase to this transformation. There is purposefully no method that adds a whole array of phases as that would make the code harder to read.
      Parameters:
      phase - The transformation phase to append

    • addPhase

      public void addPhase(int index, TransformationPhase<T> phase)
      Adds a transformation phase to this transformation at a specific order but in the default group.
      Parameters:
      index - The ordering index at which the phase should be executed
      phase - The transformation phase to insert

    • addPhase

      public void addPhase(int index, int group, TransformationPhase<T> phase)
      Adds a transformation phase to this transformation in a given group and at a given position within that group. The index determines in which order the phases will be executed in relation to other phases within this transformation and within the phase collector. The group is like another index that can be used to further separate transformations from eachother. Choose an ascending index for phases to be executed in order. To separate all phases of this transformation from those of other transformations, a different group index should be used.
      Parameters:
      index - The index at which the phase should be executed
      group - The index of the group in which this phase is executed at the given ordering index
      phase - The transformation phase to insert. For better formatting this parameter is at the end.

    • addPhase

      public void addPhase(Transformation.PhaseEntry<T> entry)
      Adds a transformation phase entry to this transformation. The entry contains a phase and information about when it should be executed by the phase collector in relation to other phases in this and other transformations. If the contained phase is null, the entry is ignored. This can be useful when a phase is expected but it be a no-op.
      Parameters:
      entry - The phase entry to add to the registry

    • addConcurrentPhase

      public void addConcurrentPhase(TransformationPhase<T> phase)
      Adds a transformation phase to this transformation at the previous phase counter position without incrementing the current phase counter. This means the phase will run at the same time as the previous phase in the case of walk phases. If no phase has been added yet, this will add the phase normally but still not increment the phase counter.
      Parameters:
      phase - The phase to add at the same position as the previous one

    • addPhases

      public void addPhases(Collection<Transformation.PhaseEntry<T>> entries)
      Adds a whole collection of phases to this transformation. This is meant for programmatic use and not for adding phases individually.
      Parameters:
      entries - The collection of phases to add

    • getDefaultGroup

      protected int getDefaultGroup()
      Returns the default group for this transformation that is used for adding phases if not specified otherwise. This method is meant to be overwritten by transformation subclasses that want to use a different group for all their phases.
      Returns:
      The default group index to use for adding phases

    • resetState

      protected void resetState()
      This method is called by the phase collector each time a tree is transformed in order to reset or initialize the state of the transformation if it has any.

    • merge

      public void merge(Transformation<T> other)
      Adds all phases from another transformation into this one. Note that this doesn't execute them after this transformation's phases but interleaved according to the phase entry's index and group numbers.
      Parameters:
      other - The other transformation to merge into this one

    • append

      public void append(Transformation<T> other)
      Appends all phases from another transformation to this one. This will adjust the phase entry's indexes to be offset by the current next index as it would be generated by addPhase(TransformationPhase). The next phase added after this will be executed after the last phase of the appended transformation. Note that group numbers are not modified. It also assumes that the phases of the appended transformation start with index 1.
      Parameters:
      other - The other transformation from which to append all phases onto this one