# loki.batch.transformation module

Base class definition for Transformation pipelines.

class Transformation

  Bases: `object`

  Base class for source code transformations that manipulate source items like `Subroutine` or `Module` in place via the `item.apply(transform)` method.

  The source transformations to be applied should be defined in the following class-specific methods:

  - `transform_subroutine()`

  - `transform_module()`

  - `transform_file()`

  The generic dispatch mechanism behind the `apply()` method will ensure that all hierarchies of the data model are traversed and the specific method for each level is applied, if the relevant recursion mode is enabled in the transformation’s manifest (`recurse_to_modules` and/or `recurse_to_procedures`). Note that in `Sourcefile` objects, `Module` members will be traversed before standalone `Subroutine` objects.

  Classes inheriting from `Transformation` may configure the invocation and behaviour during batch processing via a predefined set of class attributes. These flags determine the underlying graph traversal when processing complex call trees and determine how the transformations are invoked for a given type of `Item` in the `Scheduler`.

  reverse_traversal

    Forces scheduler traversal in reverse order from the leaf nodes upwards (default: `False`).

    Type:

      bool

  traverse_file_graph

    Apply `Transformation` to the `Sourcefile` object corresponding to the `Item` being processed, instead of the program unit in question (default: `False`).

    Type:

      bool

  item_filter

    Filter by graph node types to prune the graph and change connectivity. By default, only calls to `Subroutine` items are used to construct the graph.

    Type:

      bool

  recurse_to_modules

    Apply transformation to all `Module` objects when processing a `Sourcefile` (default `False`)

    Type:

      bool

  recurse_to_procedures

    Apply transformation to all `Subroutine` objects when processing `Sourcefile` or `Module` objects (default `False`)

    Type:

      bool

  recurse_to_internal_procedures

    Apply transformation to all internal `Subroutine` objects when processing `Subroutine` objects (default `False`)

    Type:

      bool

  process_ignored_items

    Apply transformation to “ignored” `Item` objects for analysis. This might be needed if IPO-information needs to be passed across library boundaries.

    Type:

      bool

  renames_items

    Indicates to the `Scheduler` that a transformation may change the name of the IR node corresponding to the processed `Item` (e.g., by renaming a module or subroutine). The transformation has to take care of renaming processed the `Item` itself but the `Scheduler` will update its internal cache after the transformation has been applied (default `False`).

    Type:

      bool

  creates_items

    Indicates to the `Scheduler` that a transformation may create new scopes or other dependency nodes (e.g., by adding new routines to a module). The scheduler will run a discovery step after the transformation has been applied to include these new items in the dependency graph (default `False`).

    Type:

      bool

  reverse_traversal = False
  traverse_file_graph = False
  item_filter

    alias of `ProcedureItem`

  recurse_to_modules = False
  recurse_to_procedures = False
  recurse_to_internal_procedures = False
  process_ignored_items = False
  renames_items = False
  creates_items = False
  transform_subroutine(routine, **kwargs)

    Defines the transformation to apply to `Subroutine` items.

    For transformations that modify `Subroutine` objects, this method should be implemented. It gets called via the dispatch method `apply()`.

    Parameters:

      - routine (`Subroutine`) – The subroutine to be transformed.

      - **kwargs (optional) – Keyword arguments for the transformation.

  plan_subroutine(routine, **kwargs)

    Define the planning steps to apply for `Subroutine` items.

    For transformations that modify the dependencies of `routine` (e.g., adding new procedure calls, inlining calls, renaming the interface) this should be implemented. It gets called via the dispatch method `apply()` if the optional `plan_mode` argument is set to True.

    Parameters:

      - routine (`Subroutine`) – The subroutine to be transformed.

      - **kwargs (optional) – Keyword arguments for the transformation.

  transform_module(module, **kwargs)

    Defines the transformation to apply to `Module` items.

    For transformations that modify `Module` objects, this method should be implemented. It gets called via the dispatch method `apply()`.

    Parameters:

      - module (`Module`) – The module to be transformed.

      - **kwargs (optional) – Keyword arguments for the transformation.

  plan_module(module, **kwargs)

    Define the planning steps to apply for `Module` items.

    For transformations that modify the dependencies or definitions of `module` (e.g., renaming the module, adding new subroutines, adding or removing imports) this should be implemented. It gets called via the dispatch method `apply()` if the optional `plan_mode` argument is set to True.

    Parameters:

      - module (`Module`) – The module to be transformed.

      - **kwargs (optional) – Keyword arguments for the transformation.

  transform_file(sourcefile, **kwargs)

    Defines the transformation to apply to `Sourcefile` items.

    For transformations that modify `Sourcefile` objects, this method should be implemented. It gets called via the dispatch method `apply()`.

    Parameters:

      - sourcefile (`Sourcefile`) – The sourcefile to be transformed.

      - **kwargs (optional) – Keyword arguments for the transformation.

  plan_file(sourcefile, **kwargs)

    Define the planning steps to apply for `Sourcefile` items.

    For transformations that modify the definitions or dependencies of `sourcefile` this should be implemented. It gets called via the dispatch method `apply()` if the optional `plan_mode` argument is set to True.

    Parameters:

      - sourcefile (`Sourcefile`) – The sourcefile to be transformed.

      - **kwargs (optional) – Keyword arguments for the transformation.

  apply(source, post_apply_rescope_symbols=False, plan_mode=False, **kwargs)

    Dispatch method to apply transformation to `source`.

    It dispatches to one of the type-specific dispatch methods `apply_file()`, `apply_module()`, or `apply_subroutine()`.

    Parameters:

      - source (`Sourcefile` or `Module` or `Subroutine`) – The source item to transform.

      - post_apply_rescope_symbols (bool, optional) – Call `rescope_symbols` on `source` after applying the transformation to clean up any scoping issues.

      - **kwargs (optional) – Keyword arguments that are passed on to the methods defining the actual transformation.

  apply_file(sourcefile, plan_mode=False, **kwargs)

    Apply transformation to all items in `sourcefile`.

    This calls `transform_file()` or, if `plan_mode` is enabled, calls `plan_file()`.

    If the `recurse_to_modules` class property is set, it will also invoke `apply()` on all `Module` objects in this `Sourcefile`. Likewise, if `recurse_to_procedures` is set, it will invoke `apply()` on all free `Subroutine` objects in this `Sourcefile`.

    Parameters:

      - sourcefile (`Sourcefile`) – The file to transform.

      - plan_mode (bool, optional) – If enabled, apply planning mode.

      - **kwargs (optional) – Keyword arguments that are passed on to transformation methods.

  apply_subroutine(subroutine, plan_mode=False, **kwargs)

    Apply transformation to a given `Subroutine` object and its members.

    This calls `transform_subroutine()` or, if `plan_mode` is enabled, calls `plan_subroutine()`.

    If the `recurse_to_member_procedures` class property is set, it will also invoke `apply()` on all `Subroutine` objects in the `contains` clause of this `Subroutine`.

    Parameters:

      - subroutine (`Subroutine`) – The subroutine to transform.

      - plan_mode (bool, optional) – If enabled, apply planning mode.

      - **kwargs (optional) – Keyword arguments that are passed on to transformation methods.

  apply_module(module, plan_mode=False, **kwargs)

    Apply transformation to a given `Module` object and its members.

    This calls `transform_module()` or, if `plan_mode` is enabled, calls `plan_module()`.

    If the `recurse_to_procedures` class property is set, it will also invoke `apply()` on all `Subroutine` objects in the `contains` clause of this `Module`.

    Parameters:

      - module (`Module`) – The module to transform.

      - plan_mode (bool, optional) – If enabled, apply planning mode.

      - **kwargs (optional) – Keyword arguments that are passed on to transformation methods.

  post_apply(source, rescope_symbols=False)

    Dispatch method for actions to be carried out after applying a transformation to `source`.

    It dispatches to one of the type-specific dispatch methods `post_apply_file()`, `post_apply_module()`, or `post_apply_subroutine()`.

    Parameters:

      - source (`Sourcefile` or `Module` or `Subroutine`) – The source item to transform.

      - rescope_symbols (bool, optional) – Call `rescope_symbols` on `source`

  post_apply_file(sourcefile, rescope_symbols)

    Apply actions after applying a transformation to `sourcefile`.

    Parameters:

      - sourcefile (`Sourcefile`) – The file to transform.

      - rescope_symbols (bool) – Call `rescope_symbols` on modules and subroutines in `sourcefile`

  post_apply_subroutine(subroutine, rescope_symbols)

    Apply actions after applying a transformation to `subroutine`.

    Parameters:

      - subroutine (`Subroutine`) – The file to transform.

      - rescope_symbols (bool) – Call `rescope_symbols` on `subroutine`

  post_apply_module(module, rescope_symbols)

    Apply actions after applying a transformation to `module`.

    Parameters:

      - module (`Module`) – The file to transform.

      - rescope_symbols (bool) – Call `rescope_symbols` on `module`

exception TransformationError(message, transformation, source)

  Bases: `Exception`

  Exception raised when a `Transformation` encounters an error while processing an IR node

  Parameters:

    - message (str) – Description of the error

    - transformation (subclass of `Transformation`) – The class of the transformation in which the error occured

    - source (`Sourcefile` or `ProgramUnit`) – The object that was processed when the error occured