psyclone.parse

This directory contains classes related to parsing Fortran.

Submodules

• psyclone.parse.algorithm
  • Functions
    • parse()
    • get_builtin_defs()
    • get_invoke_label()
    • get_kernel()
    • create_var_name()
  • Classes
    • Parser
      • Parser.check_invoke_label()
      • Parser.create_builtin_kernel_call()
      • Parser.create_coded_kernel_call()
      • Parser.create_invoke_call()
      • Parser.create_kernel_call()
      • Parser.invoke_info()
      • Parser.parse()
      • Parser.update_arg_to_module_map()
    • AlgFileInfo
      • AlgFileInfo.calls
      • AlgFileInfo.name
    • InvokeCall
      • InvokeCall.kcalls
      • InvokeCall.name
    • ParsedCall
      • ParsedCall.args
      • ParsedCall.ktype
      • ParsedCall.module_name
    • KernelCall
      • KernelCall.type
    • BuiltInCall
      • BuiltInCall.func_name
      • BuiltInCall.type
    • Arg
      • Arg.form
      • Arg.is_literal()
      • Arg.text
      • Arg.varname
• psyclone.parse.file_info
• psyclone.parse.kernel
• psyclone.parse.module_info
• psyclone.parse.module_manager
• psyclone.parse.utils

Classes

• FileInfo: This class stores mostly cached information about source code:

• ModuleInfo: This class stores mostly memory-cached information about a Fortran

• ModuleManager: This class implements a singleton that manages module

class psyclone.parse.FileInfo(filepath, use_caching=False)

This class stores mostly cached information about source code: - it stores the original filename - it will read the source of the file and cache it - it will parse it with fparser and cache it - it will construct the PSyIR (depends on TODO #2786 “and cache it”)

Parameters:

• filepath (str) – Path to the file that this object holds information on. Can also be set to ‘None’ in case of providing fparser / PSyIR node in a different way.

• use_caching (bool) – Use caching of intermediate representations

Inheritance

property basename

Returns:

the base name (i.e. without path or suffix) of the filename that this FileInfo object represents.

Return type:

str

property filename

Returns:

the full filename that this FileInfo object represents.

Return type:

str

get_fparser_tree(verbose=False, save_to_cache_if_cache_active=True)

Returns the fparser Fortran2003.Program representation of the source code (including Fortran2008).

Parameters:

• save_to_cache_if_cache_active (bool) – Cache is updated if fparser was not loaded from cache.

• verbose (bool) – Produce some verbose output

Return type:

Program

Returns:

fparser representation.

Raises:

FileInfoFParserError – if fparser had issues

get_psyir(verbose=False)

Returns the PSyIR FileContainer of the file.

Parameters:

verbose (bool) – Produce some verbose output

Return type:

FileContainer

Returns:

PSyIR file container node.

get_source_code(verbose=False)

Returns the source code of the file. The first time, it will be read from the file, but the data is then cached.

If any decoding errors are encountered then the associated character(s) are simply skipped. This is because this class is intended for reading Fortran source and the only way such characters can appear is if they are in comments.

Parameters:

verbose (bool) – If True, produce some verbose output

Return type:

str

Returns:

the contents of the file (utf-8 encoding).

class psyclone.parse.ModuleInfo(module_name, file_info)

This class stores mostly memory-cached information about a Fortran module. It stores a FileInfo object holding details on the original source file, the fparser2 parse tree and the PSyIR. Memory-caching is always used in FileInfo with an opt-in feature of caching the fparser parse tree to the file system.

Parameters:

• module_name (str) – Name of the module

• file_info (FileInfo) – FileInfo object. The fparser tree, PSyIR and module information will be loaded from this file if it’s not yet available.

Inheritance

property filename: str

Returns:

the filepath that contains the source code for this module.

get_fparser_tree()

Returns the fparser AST for this module.

Return type:

Optional[Program]

Returns:

The fparser AST for this module.

Raises:

ModuleInfoError – When errors have been triggered while creating the fparser tree.

get_psyir()

Returns the PSyIR representation of this module. This is based on the fparser tree (see get_parse_tree), and the information is cached. If the PSyIR must be modified, it needs to be copied, otherwise the modified tree will be returned from the cache in the future.

If the conversion to PSyIR fails then None is returned.

Returns:

PSyIR representing this module.

Return type:

psyclone.psyir.nodes.Container | NoneType

Raises:

InternalError – if the named Container (module) does not exist in the PSyIR.

get_source_code()

Returns the source code for the module using the associated FileInfo instance (which caches it).

Returns:

the source code.

Return type:

str

Raises:

ModuleInfoError – when the file cannot be read.

get_symbol(name)

Gets the PSyIR Symbol with the supplied name from the Container representing this Fortran module (if available).

This utility mainly exists to insulate the user from having to check that a Container has been successfully created for this module (it might not have been if the source of the module cannot be found or cannot be parsed) and that it contains the specified Symbol.

Parameters:

name (str) – the name of the symbol to get from this module.

Return type:

Optional[Symbol]

Returns:

the Symbol with the supplied name if the Container has been successfully created and contains such a symbol and None otherwise.

get_used_modules()

This function returns a set of all modules used in this module. Fortran intrinsic modules will be ignored. The information is based on the fparser parse tree of the module (since fparser can handle more files than PSyir, like LFRic’s constants_mod which has pre-processor directives).

Returns:

a set with all imported module names.

Return type:

set[str]

get_used_symbols_from_modules()

This function returns information about which modules are used by this module, and also which symbols are imported. The return value is a dictionary with the used module name as key, and a set of all imported symbol names as value.

Returns:

a dictionary that gives for each module name the set of symbols imported from it.

Return type:

dict[str, set[str]]

property name: str

Returns:

the name of this module.

view_tree(indent='')

Show the module information with markdown style in a tree-like structure supporting indentation.

Parameters:

indent (str) – the string to use for indentation.

class psyclone.parse.ModuleManager(use_caching=None)

This class implements a singleton that manages module dependencies.

Parameters:

use_caching (bool) – Whether to use (True) or disable (False) caching

Inheritance

add_ignore_module(module_name)

Adds the specified module name to the modules to be ignored.

Parameters:

module_name (str) – name of the module to ignore.

add_search_path(directories, recursive=True)

If the directory is not already contained in the search path, add it. Directory can either be a string, in which case it is a single directory, or a list of directories, each one a string.

Parameters:

• directories (str | list[str]) – the directory/directories to add.

• recursive (bool) – whether recursively all subdirectories should be added to the search path.

static get(use_caching=None)

Static function that if necessary creates and returns the singleton ModuleManager instance.

Parameters:

use_caching (bool) – If True, a file-based caching of the fparser tree will be used. This can significantly accelerate obtaining a PSyIR from a source file. For parallel builds, parallel race conditions to the cache file can happen, but this shouldn’t lead to wrong results. However, that’s untested so far.

get_all_dependencies_recursively(all_mods)

This function collects recursively all module dependencies for any of the modules in the all_mods set. I.e. it will add all modules used by any module listed in all_mods, and any modules used by the just added modules etc. In the end, it will return a dictionary that for each module lists which modules it depends on. This dictionary will be complete, i.e. all modules that are required for the original set of modules (and that could be found) will be a key in the dictionary. It will include the original set of modules as well.

If a module cannot be found (e.g. its path was not given to the ModuleManager, or it might be a system module for which the sources are not available, a message will be printed, and this module will be ignored (i.e. not listed in any dependencies). # TODO 2120: allow a choice to abort or ignore.

Parameters:

all_mods (set[str]) – the set of all modules for which to collect module dependencies.

Returns:

a dictionary with all modules that are required (directly or indirectly) for the modules in all_mods.

Return type:

dict[str, set[str]]

get_module_info(module_name)

This function returns the ModuleInformation for the specified module.

Parameters:

module_name (str) – name of the module.

Returns:

object describing the requested module or None if the manager has been configured to ignore this module.

Return type:

psyclone.parse.ModuleInfo | None

Raises:

FileNotFoundError – if the module_name is not found in either the cached data nor in the search path.

get_modules_in_file(finfo)

Uses a regex search to find all modules defined in the file with the supplied name.

Parameters:

finfo (psyclone.parse.FileInfo) – object holding information on the file to examine.

Returns:

the names of any modules present in the supplied file.

Return type:

list[str]

ignores()

Returns:

the set of modules to ignore.

Return type:

set[str]

sort_modules(module_dependencies)

This function sorts the given dependencies so that all dependencies of a module are before any module that needs it. Input is a dictionary that contains all modules to be sorted as keys, and the value for each module is the set of dependencies that the module depends on.

Parameters:

module_dependencies (dict[str, set[str]]) – the list of modules required as keys, with all their dependencies as value.

Returns:

the sorted list of modules.

Return type:

list[str]

Exceptions

• FileInfoFParserError: Triggered when generation of FParser tree failed

• ModuleInfoError: PSyclone-specific exception for use when an error with the module manager

exception psyclone.parse.FileInfoFParserError(value)

Triggered when generation of FParser tree failed

Inheritance

exception psyclone.parse.ModuleInfoError(value)

PSyclone-specific exception for use when an error with the module manager happens - typically indicating that some module information cannot be found.

Parameters:

value (str) – the message associated with the error.

Inheritance