# loki.program_unit

Classes

`ProgramUnit`([parent]) | Common base class for `Module` and `Subroutine`

class ProgramUnit(parent: dataclasses.InitVar[object] = None)

  Bases: `Scope`

  Common base class for `Module` and `Subroutine`

  Parameters:

    - name (str) – Name of the program unit.

    - docstring (tuple of `Node`, optional) – The docstring in the original source.

    - spec (`Section`, optional) – The spec of the program unit.

    - contains (`Section`, optional) – The internal-subprogram part following a `CONTAINS` statement declaring module or member procedures

    - ast (optional) – Parse tree node from the frontend for this program unit

    - source (`Source`) – Source object representing the raw source string information from the original file.

    - parent (`Scope`, optional) – The enclosing parent scope of the program unit. Declarations from the parent scope remain valid within the program unit’s scope (unless shadowed by local declarations).

    - rescope_symbols (bool, optional) – Ensure that the type information for all `TypedSymbol` in the IR exist in this program unit’s scope or the scope’s parents. Defaults to False.

    - symbol_attrs (`SymbolTable`, optional) – Use the provided `SymbolTable` object instead of creating a new

    - incomplete (bool, optional) – Mark the object as incomplete, i.e. only partially parsed. This is typically the case when it was instantiated using the `Frontend.REGEX` frontend and a full parse using one of the other frontends is pending.

    - parser_classes (`RegexParserClass`, optional) – Provide the list of parser classes used during incomplete regex parsing

  classmethod from_source(source, definitions=None, preprocess=False, includes=None, defines=None, xmods=None, omni_includes=None, frontend=Frontend.FP, parser_classes=None, parent=None)

    Instantiate an object derived from `ProgramUnit` from raw source string

    This calls the frontend-specific factory method implemented in the derived class, such as `Module` or `Subroutine`

    Parameters:

      - source (str) – Fortran source string

      - definitions (list of `Module`, optional) – `Module` object(s) that may supply external type or procedure definitions.

      - preprocess (bool, optional) –

        Flag to trigger CPP preprocessing (by default False).

        Attention

        Please note that, when using the OMNI frontend, C-preprocessing will always be applied, so `includes` and `defines` may have to be defined even when disabling `preprocess`.

      - includes (list of str, optional) – Include paths to pass to the C-preprocessor.

      - defines (list of str, optional) – Symbol definitions to pass to the C-preprocessor.

      - xmods (str, optional) – Path to directory to find and store `.xmod` files when using the OMNI frontend.

      - omni_includes (list of str, optional) – Additional include paths to pass to the preprocessor run as part of the OMNI frontend parse. If set, this replaces (!) `includes`, otherwise `omni_includes` defaults to the value of `includes`.

      - frontend (`Frontend`, optional) – Frontend to use for producing the AST (default `FP`).

      - parent (`Scope`, optional) – The parent scope this module or subroutine is nested into

  abstract classmethod from_omni(ast, raw_source, definitions=None, parent=None, type_map=None)

    Create the `ProgramUnit` object from an `OMNI` parse tree.

    This method must be implemented by the derived class.

    Parameters:

      - ast – The OMNI parse tree

      - raw_source (str) – Fortran source string

      - definitions (list, optional) – List of external `Module` to provide derived-type and procedure declarations

      - parent (`Scope`, optional) – The enclosing parent scope of the module

      - typetable (dict, optional) – A mapping from type hash identifiers to type definitions, as provided in OMNI’s `typeTable` parse tree node

  abstract classmethod from_fparser(ast, raw_source, definitions=None, pp_info=None, parent=None)

    Create the `ProgramUnit` object from an `FP` parse tree.

    This method must be implemented by the derived class.

    Parameters:

      - ast – The FParser parse tree

      - raw_source (str) – Fortran source string

      - definitions (list) – List of external `Module` to provide derived-type and procedure declarations

      - pp_info – Preprocessing info as obtained by `sanitize_input`

      - parent (`Scope`, optional) – The enclosing parent scope of the module.

  abstract classmethod from_regex(raw_source, parser_classes=None, parent=None)

    Create the `ProgramUnit` object from source regex’ing.

    This method must be implemented by the derived class.

    Parameters:

      - raw_source (str) – Fortran source string

      - parent (`Scope`, optional) – The enclosing parent scope of the module.

  abstract register_in_parent_scope()

    Insert the type information for this object in the parent’s symbol table

    If `parent` is None, this does nothing.

    This method must be implemented by the derived class.

  make_complete(**frontend_args)

    Trigger a re-parse of the object if incomplete to produce a full Loki IR

    If the object is marked to be incomplete, i.e. when using the lazy constructor option, this triggers a new parsing of all `ProgramUnit` objects and any `RawSource` nodes in the `ir`.

    Existing `Module` and `Subroutine` objects continue to exist and references to them stay valid, as they will only be updated instead of replaced.

  enrich(definitions, recurse=False)

    Enrich the current scope with inter-procedural annotations

    This updates the `SymbolAttributes` in the scope’s `SymbolTable` with `definitions` for all imported symbols.

    Note that `Subroutine.enrich` expands this to interface-declared calls.

    Parameters:

      - definitions (list of `ProgramUnit`) – A list of all available definitions

      - recurse (bool, optional) – Enrich contained scopes

  clone(**kwargs)

    Create a deep copy of the object with the option to override individual parameters

    Parameters:

      **kwargs – Any parameters from the constructor of the class.

    Returns:

      The cloned object.

    Return type:

      Object of type `self.__class__`

  property typedefs

    Return the `TypeDef` defined in the `spec` of this unit

  property typedef_map

    Map of names and `TypeDef` defined in the `spec` of this unit

  property declarations

    Return the declarations from the `spec` of this unit

  property variables

    Return the variables declared in the `spec` of this unit

  property variable_map

    Map of variable names to `Variable` objects

  property imports

    Return the list of `Import` in this unit

  property import_map

    Map of imported symbol names to `Import` objects

  property imported_symbols

    Return the symbols imported in this unit

  property imported_symbol_map

    Map of imported symbol names to objects

  property all_imports

    Return the list of `Import` in this unit and any parent scopes

  property interfaces

    Return the list of `Interface` declared in this unit

  property interface_symbols

    Return the list of symbols declared via interfaces in this unit

  property interface_map

    Map of declared interface names to `Interface` nodes

  property interface_symbol_map

    Map of declared interface names to symbols

  property enum_symbols

    List of symbols defined via an enum

  property definitions

    The list of IR nodes defined by this program unit.

    Returns an empty tuple by default and can be overwritten by derived nodes.

  property symbols

    Return list of all symbols declared or imported in this module scope

  property symbol_map

    Map of symbol names to symbols

  get_symbol(name)

    Returns the symbol for a given name as defined in its declaration.

    The returned symbol might include dimension symbols if it was declared as an array.

    Parameters:

      name (str) – Base name of the symbol to be retrieved

  Variable(**kwargs)

    Factory method for `TypedSymbol` or `MetaSymbol` classes.

    This invokes the `Variable` with this node as the scope.

    Parameters:

      - name (str) – The name of the variable.

      - type (optional) – The type of that symbol. Defaults to `BasicType.DEFERRED`.

      - parent (`Scalar` or `Array`, optional) – The derived type variable this variable belongs to.

      - dimensions (`ArraySubscript`, optional) – The array subscript expression.

  parse_expr(expr_str, strict=False, evaluate=False, context=None)

    Uses `parse_expr()` to convert expression(s) represented in a string to Loki expression(s)/IR.

    Parameters:

      - expr_str (str) – The expression as a string

      - strict (bool, optional) – Whether to raise exception for unknown variables/symbols when evaluating an expression (default: False)

      - evaluate (bool, optional) – Whether to evaluate the expression or not (default: False)

      - context (dict, optional) – Symbol context, defining variables/symbols/procedures to help/support evaluating an expression

    Returns:

      The expression tree corresponding to the expression

    Return type:

      `Expression`

  property subroutines

    List of `Subroutine` objects that are declared in this unit

  property routines

    List of `Subroutine` objects that are declared in this unit

  property subroutine_map

    Map of subroutine names to `Subroutine` objects in `subroutines`

  property spec_parts

    Return the `spec` subdivided into the parts the Fortran standard describes and requires to appear in a specific order

    The parts are:

    - import statements (such as module imports via `USE`)

    - implicit-part (such as `IMPLICIT NONE`)

    - declaration constructs (such as access statements, variable declarations etc.)

    This can be useful when adding or looking for statements that have to appear in a certain position.

    Note that comments at the interface between parts may be allocated to the previous or next part.

    Returns:

      The parts of the spec, with empty parts represented by empty tuples.

    Return type:

      tuple of tuple of `ir.Node`

  property ir

    All components of the intermediate representation in this unit

  property source

    The `Source` object for this unit

  to_fortran(conservative=False, cuf=False)

    Convert this unit to Fortran source representation

  apply(op, **kwargs)

    Apply a given transformation to this program unit

    Note that the dispatch routine `op.apply(source)` will ensure that all entities of this `ProgramUnit` are correctly traversed.

  resolve_typebound_var(name, variable_map=None)

    A small convenience utility to resolve type-bound variables.

    Parameters:

      - name (str) – The full name of the variable to be resolved, e.g., a%b%c%d.

      - variable_map (dict) – A map of the variables defined in the current scope.