# loki.sourcefile

Contains the declaration of `Sourcefile` that is used to represent and manipulate (Fortran) source code files.

Classes

`Sourcefile`(path[, ir, ast, source, ...]) | Class to handle and manipulate source files, storing `Module` and `Subroutine` objects.

class Sourcefile(path, ir=None, ast=None, source=None, incomplete=False, parser_classes=None)

  Bases: `object`

  Class to handle and manipulate source files, storing `Module` and `Subroutine` objects.

  Reading existing source code from file or string can be done via `from_file()` or `from_source()`.

  Parameters:

    - path (str) – The name of the source file.

    - ir (`Section`, optional) – The IR of the file content (including `Subroutine`, `Module`, `Comment` etc.)

    - ast (optional) – Parser-AST of the original source file.

    - source (`Source`, optional) – Raw source string and line information about the original source file.

    - 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

  clone(**kwargs)

    Replicate the object with the provided overrides.

  classmethod from_file(filename, definitions=None, preprocess=False, includes=None, defines=None, omni_includes=None, xmods=None, frontend=Frontend.FP, parser_classes=None)

    Constructor from raw source files that can apply a C-preprocessor before invoking frontend parsers.

    Parameters:

      - filename (str) – Name of the file to parse into a `Sourcefile` object.

      - 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`).

  classmethod from_omni(raw_source, filepath, definitions=None, includes=None, defines=None, xmods=None, omni_includes=None)

    Parse a given source string using the OMNI frontend

    Parameters:

      - raw_source (str) – Fortran source string

      - filepath (str or `pathlib.Path`) – The filepath of this source file

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

      - 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`.

  classmethod from_fparser(raw_source, filepath, definitions=None)

    Parse a given source string using the fparser frontend

    Parameters:

      - raw_source (str) – Fortran source string

      - filepath (str or `pathlib.Path`) – The filepath of this source file

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

  classmethod from_regex(raw_source, filepath, parser_classes=None)

    Parse a given source string using the REGEX frontend

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

    Constructor from raw source string that invokes specified frontend parser

    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`).

  make_complete(**frontend_args)

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

    If the source file 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 `Sourcefile.ir`.

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

  property source
  to_fortran(conservative=False, cuf=False)
  property modules

    List of `Module` objects that are members of this `Sourcefile`.

  property routines

    List of `Subroutine` objects that are members of this `Sourcefile`.

  property subroutines

    List of `Subroutine` objects that are members of this `Sourcefile`.

  property typedefs

    List of `TypeDef` objects that are declared in the `Module` in this `Sourcefile`.

  property all_subroutines
  property definitions

    List of all definitions made in this sourcefile, i.e. modules and subroutines

  apply(op, **kwargs)

    Apply a given transformation to the source file object.

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

  write(path=None, source=None, conservative=False, cuf=False)

    Write content as Fortran source code to file

    Parameters:

      - path (str, optional) – Filepath of target file; if not provided, `Sourcefile.path` is used

      - source (str, optional) – Write the provided string instead of generating via `Sourcefile.to_fortran`

      - conservative (bool, optional) – Enable conservative output in the backend, aiming to be as much string-identical as possible (default: False)

      - cuf (bool, optional) – To use either Cuda Fortran or Fortran backend

  classmethod to_file(source, path)

    Same as `write()` but can be called from a static context.