# loki.frontend.source

Implementation of `Source` and adjacent utilities

Functions

`join_source_list`(source_list) | Combine a list of `Source` objects into a single object containing the joined source string.
`source_to_lines`(source) | Create line-wise `Source` objects, resolving Fortran line-continuation.

Classes

`FortranReader`(raw_source) | Reader for Fortran source strings that provides a sanitized version of the source code
`Source`(lines[, string, file, status]) | Store information about the original source for an IR node.
`SourceStatus`(*values) | The node and its children are unchanged - `Source` is valid!

class Source(lines, string=None, file=None, status=None)

  Bases: `object`

  Store information about the original source for an IR node.

  Parameters:

    - line (tuple) – Start and (optional) end line number in original source file

    - string (str (optional)) – The original raw source string

    - file (str (optional)) – The file name

    - status (`SourceStatus`) – Flag indicating if the associated node has been altered

  clone(**kwargs)

    Replicate the object with the provided overrides.

  find(string, ignore_case=True, ignore_space=True)

    Find the given string in the source and return start and end index or None if not found.

  clone_with_string(string, ignore_case=True, ignore_space=True)

    Clone the source object and extract the given string from the original source string or use the provided string.

  clone_with_span(span)

    Clone the source object and extract the given line span from the original source string (relative to the string length).

  clone_lines(span=None)

    Create source object clones for each line.

  invalidate(children=False)

    Set the status of this source to `SourceStatus.INVALID_NODE` or `SourceStatus.INVALID_CHILDREN`.

    Calling `source.invalidate()` marks the entire source object as invalid, while `source.invalidate(children=True)` denotes that interior properties the associated node have not been changed, but its children have been invalidated.

  is_valid()

    Returns `True` if the `Source` object is still valid.

class SourceStatus(*values)

  Bases: `Enum`

  The node and its children are unchanged - `Source` is valid!

  VALID = 1

    Interior node properties (expressions) have changed - `Source` is invalid!

  INVALID_NODE = 2

    Interior node properties have not changed, but child nodes have been altered - `Source` is invalid!

  INVALID_CHILDREN = 3

class FortranReader(raw_source)

  Bases: `object`

  Reader for Fortran source strings that provides a sanitized version of the source code

  It performs the following sanitizer steps:

  - Remove all comments and preprocessor directives

  - Remove empty lines

  - Remove all whitespace at the beginning and end of lines

  - Resolve all line continuations

  This enables easier pattern matching in the source code. The original source code can be recovered (with some restrictions) for each position in the sanitized source string.

  Parameters:

    raw_source (str) – The Fortran source code

  source_lines

    The lines of the original source code

    Type:

      list

  sanitized_lines

    Lines in the sanitized source code

    Type:

      list of `fparser.common.Line`

  sanitized_string

    The sanitized source code

    Type:

      str

  sanitized_spans

    Start index of each line in the sanitized string

    Type:

      list of int

  get_line_index(line_number)

    Yield the index in `source_lines` for the given `line_number`

  get_line_indices_from_span(span, include_padding=False)

    Yield the line indices in `source_lines` and `sanitized_lines` for the given `span` in the `sanitized_string`

    Parameters:

      - span (tuple) – Start and end in the `sanitized_string`. The end can optionally be None, which includes everything up to the end

      - include_padding (bool (optional)) – Includes lines from the original source that are missing in the sanitized string (i.e. comments etc.) and that are located immediately before/after the specified span.

    Returns:

      Start and end indices corresponding to `sanitized_lines` and `source_lines`, respectively. Indices for start are inclusive and for end exclusive (i.e. `[start, end)`).

    Return type:

      sanitized_start, sanitized_end, source_start, source_end

  to_source(include_padding=False)

    Create a `Source` object with the content of the reader

  source_from_head()

    Create a `Source` object that contains raw source lines present in the original source string before the sanitized source string

    This means typically comments or preprocessor directives. Returns None if there is nothing.

  source_from_tail()

    Create a `Source` object that contains raw source lines present in the original source string after the sanitized source string

    This means typically comments or preprocessor directives. Returns None if there is nothing.

  source_from_sanitized_span(span, include_padding=False)

    Create a `Source` object containing the original source string corresponding to the given span in the sanitized string

  reader_from_sanitized_span(span, include_padding=False)

    Create a new `FortranReader` object covering only the source code section corresponding to the given span in the sanitized string

  property current_line

    Return the current line of the iterator or None if outside of iteration range

  source_from_current_line()

    Return a `Source` object for the current line

source_to_lines(source)

  Create line-wise `Source` objects, resolving Fortran line-continuation.

join_source_list(source_list)

  Combine a list of `Source` objects into a single object containing the joined source string.

  This will annotate the joined source object with the maximum range of line numbers provided in `source_list` objects and insert empty lines for any missing line numbers inbetween the provided source objects.