loki.program_unit

Classes

ProgramUnit([parent])

Common base class for Module and Subroutine

class ProgramUnit(parent: dataclasses.InitVar[object] | None = 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_ofp(ast, raw_source, definitions=None, pp_info=None, parent=None)

Create the ProgramUnit object from an OFP parse tree.

This method must be implemented by the derived class.

Parameters:

• ast – The OFP 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_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

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.