# =============================================================================
# ____ _ _ ____ _ _ _ _ _ _ _
# _ __ _ _ / ___| | | | _ \| | | (_) |__ __ _| |__ __| | |
# | '_ \| | | | | _| |_| | | | | | | | | '_ \ / _` | '_ \ / _` | |
# | |_) | |_| | |_| | _ | |_| | |___ _| | | |_) | (_| | | | | (_| | |
# | .__/ \__, |\____|_| |_|____/|_____(_)_|_|_.__/ \__, |_| |_|\__,_|_|
# |_| |___/ |___/
# =============================================================================
# Authors:
# Tristan Gingold
# Patrick Lehmann
#
# Package package: Python binding and low-level API for shared library 'libghdl'.
#
# 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
# ============================================================================
"""
Python binding for the Ada package ``Files_Map`` in *libghdl*.
Maps between a *location* - the compact position *libghdl* stores in a node - and a source file with a line and a
column, and holds the source buffers themselves.
"""
from ctypes import POINTER, c_char, c_void_p, cast
from pyTooling.Decorators import export
from pyGHDL.libghdl._decorator import BindToLibGHDL
from pyGHDL.libghdl._types import NameId, SourceFileEntry, LocationType
__all__ = [
"EOT",
"No_Source_File_Entry",
"No_Location",
]
EOT = b"\x04"
No_Source_File_Entry = 0
No_Location = 0
[docs]
@export
@BindToLibGHDL("files_map__location_to_file")
def Location_To_File(Location: LocationType) -> SourceFileEntry:
"""
Convert ``Location`` to a source file.
:param Location: The location to resolve.
:returns: The source file, or :attr:`~pyGHDL.libghdl.files_map.No_Source_File_Entry` if the location is
incorrect.
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__location_file_to_pos")
def Location_File_To_Pos(Location: LocationType, File: SourceFileEntry) -> int:
"""
Convert ``Location`` and ``File`` to a position (offset) into the source file.
:param Location: The location to resolve.
:param File: Source file
:returns: Offset
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__location_file_to_line")
def Location_File_To_Line(Location: LocationType, File: SourceFileEntry) -> int:
"""
Convert ``Location`` and ``File`` to a line number.
:param Location: The location to resolve.
:param File: Source file
:returns: Line number
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__location_file_line_to_offset")
def Location_File_Line_To_Offset(Location: LocationType, File: SourceFileEntry, Line: int) -> int:
"""
Get the offset in ``Line`` of ``Location``.
:param Location: The location to resolve.
:param File: Source file
:param Line: Line number
:returns: Offset
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__location_file_line_to_col")
def Location_File_Line_To_Col(Location: LocationType, File: SourceFileEntry, Line: int) -> int:
"""
Get logical column (with HT expanded) from ``Location``, ``File`` and
``Line``.
:param Location: The location to resolve.
:param File: Source file
:param Line: Line number
:returns: logical column (horizontal tabs are expanded)
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__file_to_location")
def File_To_Location(File: SourceFileEntry) -> LocationType:
"""Convert a ``File`` into a location.
:param File: The source file to query.
:returns: Location.
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__file_pos_to_location")
def File_Pos_To_Location(File: SourceFileEntry, Pos: int) -> LocationType:
"""
Convert a ``File`` and an offset ``Pos`` in the file into a location.
:param File: The source file to query.
:param Pos: Offset in the file
:returns: Location.
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__file_line_to_position")
def File_Line_To_Position(File: SourceFileEntry, Line: int) -> int:
"""
Convert a ``File`` and ``Line`` into a position.
:param File: The source file to query.
:param Line: Line number
:returns: Return ``Source_Ptr_Bad`` in case of error (``Line`` out of bounds).
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__get_file_name")
def Get_File_Name(File: SourceFileEntry) -> NameId:
"""
Return the name of the file.
:param File: Source file to get the filename from.
:returns: NameId for the filename.
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__get_directory_name")
def Get_Directory_Name(File: SourceFileEntry) -> NameId:
"""
Return the directory of the file.
:param File: Source file to get the directory name from.
:returns: NameId for the directory.
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__get_file_buffer")
def Get_File_Buffer_voidp(File: SourceFileEntry) -> c_void_p:
"""
Raw binding returning the source buffer as an untyped pointer.
Use :func:`Get_File_Buffer` instead, which types it as a character pointer.
:param File: The source file entry to read the buffer of.
:returns: The address of the source buffer.
"""
return 0 # pragma: no cover
def Get_File_Buffer(File: SourceFileEntry) -> POINTER(c_char):
"""
Return a buffer (access to the contents of the file) for a file entry.
:param File: Source file to get the buffer from.
:returns: A pointer to the file's contents.
"""
return cast(Get_File_Buffer_voidp(File), POINTER(c_char))
[docs]
@export
@BindToLibGHDL("files_map__get_file_length")
def Get_File_Length(File: SourceFileEntry) -> int:
"""
Get the position of the first EOT character.
:param File: The source file to query.
:returns: The position of the first EOT character, i.e. the length of the source text.
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__set_file_length")
def Set_File_Length(File: SourceFileEntry, Length: int) -> None:
"""
Set the length of the file (which is less than the size of the file buffer).
Set also append two EOT at the end of the file.
:param File: Source file
:param Length: Length for the file
"""
return 0 # pragma: no cover
@export
@BindToLibGHDL("files_map__get_buffer_length")
def Get_Buffer_Length(File: SourceFileEntry) -> int:
"""
Get the length of the buffer, including the gap and the two EOT.
:param File: The source file to query.
:returns: The length of the buffer.
"""
[docs]
@export
@BindToLibGHDL("files_map__get_buffer_length")
def Get_Buffer_Length(File: SourceFileEntry) -> int:
"""
Get the length of the buffer, including the gap and the two EOT.
:param File: The source file to query.
:returns: The length of the buffer.
"""
[docs]
@export
@BindToLibGHDL("files_map__find_source_file")
def Find_Source_File(Directory: NameId, Name: NameId) -> SourceFileEntry:
"""
Return an existing entry for a filename.
:param Directory: :attr:`~pyGHDL.libghdl.name_table.Null_Identifier` for ``DirectoryId`` means current directory.
:param Name: File name
:returns: Return :attr:`~pyGHDL.libghdl.files_map.No_Source_File_Entry`, if the file is not already open.
"""
return 0
[docs]
@export
@BindToLibGHDL("files_map__read_source_file")
def Read_Source_File(Directory: NameId, Name: NameId) -> SourceFileEntry:
"""
Return an entry for a filename.
Load the filename if necessary.
:param Directory: :attr:`~pyGHDL.libghdl.name_table.Null_Identifier` for ``DirectoryId`` means current directory.
:param Name: File name
:returns: Return :attr:`~pyGHDL.libghdl.files_map.No_Source_File_Entry`, if the file does not exist.
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__reserve_source_file")
def Reserve_Source_File(Directory: NameId, Name: NameId, Length: int) -> SourceFileEntry:
"""
Reserve an entry, but do not read any file.
The length should includes the two terminal EOT.
:param Directory: Directory name
:param Name: File name
:param Length: Length to reserve
:returns: SourceFile
"""
return 0 # pragma: no cover
[docs]
@export
@BindToLibGHDL("files_map__discard_source_file")
def Discard_Source_File(File: SourceFileEntry) -> None:
"""
Mark ``File`` as unavailable: clear the name and directory.
.. hint:: This is needed before creating a new source file with the same name.
:param File: Source file to discard.
"""
[docs]
@export
@BindToLibGHDL("files_map__free_source_file")
def Free_Source_File(File: SourceFileEntry) -> None:
"""
Free resources used by ``File``, but keep the entry.
.. note:: It could be recycled for files that could fit - not implemented.
:param File: Source file to free.
"""
[docs]
@export
@BindToLibGHDL("files_map__get_last_source_file_entry")
def Get_Last_Source_File_Entry() -> SourceFileEntry:
"""
Returns the entry of the last known file.
.. hint:: This allows creating a table of ``SourceFileEntry``.
:returns: Last SourceFileEntry
"""
return 0 # pragma: no cover