# =============================================================================
# ____ _ _ ____ _ _
# _ __ _ _ / ___| | | | _ \| | __| | ___ _ __ ___
# | '_ \| | | | | _| |_| | | | | | / _` |/ _ \| '_ ` _ \
# | |_) | |_| | |_| | _ | |_| | |___ | (_| | (_) | | | | | |
# | .__/ \__, |\____|_| |_|____/|_____(_)__,_|\___/|_| |_| |_|
# |_| |___/
# =============================================================================
# Authors:
# Patrick Lehmann
#
# License:
# ============================================================================
# Copyright (C) 2019-2021 Tristan Gingold
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <gnu.org/licenses>.
#
# SPDX-License-Identifier: GPL-2.0-or-later
# ============================================================================
"""
Document object model (DOM) for :mod:`pyGHDL.libghdl` based on :doc:`pyVHDLModel <vhdlmodel:index>`.
"""
from pathlib import Path
from pyTooling.Decorators import export, readonly
from pyTooling.MetaClasses import ExtendedType
from pyGHDL import GHDLBaseException
from pyGHDL.libghdl import files_map, name_table
from pyGHDL.libghdl._types import Iir
from pyGHDL.libghdl.vhdl import nodes
[docs]
@export
class Position(metaclass=ExtendedType):
"""Represents the source code position of a IIR node in a source file."""
_filename: Path #: The source file this position refers to.
_line: int #: The line number in the source file, starting at 1.
_column: int #: The character offset within the line, starting at 0.
[docs]
def __init__(self, filename: Path, line: int, column: int) -> None:
"""
Initializes a source code position.
:param filename: The source file this position refers to.
:param line: The line number in the source file, starting at 1.
:param column: The character offset within the line, starting at 0.
"""
self._filename = filename
self._line = line
self._column = column
[docs]
@classmethod
def parse(cls, node: Iir) -> "Position":
"""
Return the source code position of a IIR node.
:param node: The IIR node to read the position of.
:returns: The node's position in its source file.
:raises ValueError: If parameter ``node`` is :data:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`.
"""
if node == nodes.Null_Iir:
raise ValueError("Position.parse(): Parameter 'node' must not be 'Null_iir'.")
location = nodes.Get_Location(node)
file = files_map.Location_To_File(location)
fileNameId = files_map.Get_File_Name(file)
fileName = name_table.Get_Name_Ptr(fileNameId)
line = files_map.Location_File_To_Line(location, file)
column = files_map.Location_File_Line_To_Offset(location, file, line)
return cls(Path(fileName), line, column)
@readonly
def Filename(self) -> Path:
"""
Read-only property to access the filename this source code position refers to (:attr:`_filename`).
:returns: The source code position's filename.
"""
return self._filename
@readonly
def Line(self) -> int:
"""
Read-only property to access the line number this source code position refers to (:attr:`_line`).
:returns: The source code position's line.
"""
return self._line
@readonly
def Column(self) -> int:
"""
Read-only property to access the column this source code position refers to (:attr:`_column`).
:returns: The source code position's column.
"""
return self._column
[docs]
def __str__(self) -> str:
"""
Formats the source code position as ``<filename>:<line>:<column>``.
:returns: A string representation of this source code position.
"""
return f"{self._filename}:{self._line}:{self._column}"
[docs]
@export
class DOMMixin(metaclass=ExtendedType, mixin=True):
"""
Mixin adding the originating IIR node and its source code position to a :mod:`pyGHDL.dom` object.
Every class in :mod:`pyGHDL.dom` that mirrors a pyVHDLModel class inherits this mixin, so a model
object can always be traced back to the node in *libghdl*'s tree it was translated from.
"""
_iirNode: Iir #: The IIR node in *libghdl*'s tree this DOM object was translated from.
_position: Position #: The IIR node's position in the source file, resolved on first access and then cached.
[docs]
def __init__(self, node: Iir) -> None:
"""
Initializes the mixin with the IIR node a DOM object was translated from.
The source code position is not resolved here, but on first access of :attr:`Position`.
:param node: The IIR node in *libghdl*'s tree this DOM object was translated from.
"""
self._iirNode = node
self._position = None
# TODO: add Iir and Iir kind properties
@readonly
def Position(self) -> Position:
"""
Cached read-only property to access an IIR's position in source code (:attr:`_position`).
If :attr:`_position` is None, resolve the position object from :attr:`_iirNode`
:returns: The IIR's position in the source file.
"""
if self._position is None:
self._position = Position.parse(self._iirNode)
return self._position
[docs]
@export
class DOMException(GHDLBaseException):
"""
The exception is raised when an IIR node cannot be translated to a pyVHDLModel object.
It reports a node kind the translation does not handle, or a node whose shape does not match what
the surrounding construct expects. The message names the kind and, where available, the source
position.
"""