From 2a13ab3ff6e86782018fd1691ceb3e6ad92bef96 Mon Sep 17 00:00:00 2001 From: Patrick Lehmann Date: Thu, 7 Jan 2021 16:03:52 +0100 Subject: Enhanced docstrings for Python/Ada interface. --- pyGHDL/libghdl/libraries.py | 96 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 84 insertions(+), 12 deletions(-) (limited to 'pyGHDL/libghdl/libraries.py') diff --git a/pyGHDL/libghdl/libraries.py b/pyGHDL/libghdl/libraries.py index 4fc91f062..895194458 100644 --- a/pyGHDL/libghdl/libraries.py +++ b/pyGHDL/libghdl/libraries.py @@ -7,12 +7,13 @@ # |_| |___/ |___/ # ============================================================================= # Authors: Tristan Gingold +# Patrick Lehmann # -# Package package: Python binding and low-level API for shared library 'libghdl'. +# Package module: Python binding and low-level API for shared library 'libghdl'. # # License: # ============================================================================ -# Copyright (C) 2019-2020 Tristan Gingold +# Copyright (C) 2019-2021 Tristan Gingold # # GHDL 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 @@ -34,23 +35,94 @@ # from ctypes import c_int32 +from pydecor import export + from pyGHDL.libghdl import libghdl +__all__ = [ + 'Library_Location', + 'Work_Library' +] + +from pyGHDL.libghdl._types import NameId + + +Library_Location = c_int32.in_dll(libghdl, "libraries__library_location") #: A location for library declarations (such as library WORK). Type ``Location_Type``. Use ``.value`` to access this variable inside libghdl +Work_Library = c_int32.in_dll(libghdl, "libraries__work_library") #: Library declaration for the work library. Note: the identifier of the work_library is ``work_library_name``, which may be different from 'WORK'. Type: ``Iir_Library_Declaration``. Use ``.value`` to access this variable inside libghdl + + +@export +def Get_Libraries_Chain(): + """ + Get the chain of libraries. Can be used only to read (it mustn't be modified). + + :return: Type ``Iir_Library_Declaration`` + """ + return libghdl.libraries__get_libraries_chain() + + +@export +def Add_Design_Unit_Into_Library(Unit, Keep_Obsolete: bool = False) -> None: + """ + Add or replace an design unit in the work library. DECL must not have a chain + (because it may be modified). + + If the design_file of UNIT is not already in the library, a new one is created. + + Units are always appended to the design_file. Therefore, the order is kept. + + :param Unit: Type: ``Iir_Design_Unit`` + :param Keep_Obsolete: If :obj:`Keep_Obsolete` is True, obsoleted units are + kept in the library. + + This is used when a whole design file has to be added + in the library and then processed (without that feature, + redefined units would disappear). + """ + libghdl.libraries__add_design_unit_into_library(Unit, Keep_Obsolete) + + +@export +def Purge_Design_File(Design_File) -> None: + """ + Remove the same file as DESIGN_FILE from work library and all of its units. + + :param Design_File: Type: ``Iir_Design_File`` + """ + libghdl.libraries__purge_design_file(Design_File) + -Get_Libraries_Chain = libghdl.libraries__get_libraries_chain +@export +def Find_Entity_For_Component(Name: NameId): + """ + Find an entity whose name is :obj:`Name` in any library. |br| + If there is no such entity, return :attr:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`. |br| + If there are several entities, return :attr:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir`; -Add_Design_Unit_Into_Library = libghdl.libraries__add_design_unit_into_library + :param Name: Entity name to search for. + :return: Type: ``Iir_Design_Unit`` + """ + return libghdl.libraries__find_entity_for_component(Name) -# Use .value -Library_Location = c_int32.in_dll(libghdl, "libraries__library_location") -# Use .value -Work_Library = c_int32.in_dll(libghdl, "libraries__work_library") +@export +def Get_Library_No_Create(Ident: NameId): + """ + Get the library named :obj:`Ident`. -Purge_Design_File = libghdl.libraries__purge_design_file + :param Ident: Libryr to look for. + :return: Return :attr:`~pyGHDL.libghdl.vhdl.nodes.Null_Iir` if it doesn't exist. Type ``Iir_Library_Declaration`` + """ + return libghdl.libraries__get_library_no_create(Ident) -Find_Entity_For_Component = libghdl.libraries__find_entity_for_component -Get_Library_No_Create = libghdl.libraries__get_library_no_create +@export +def Find_Primary_Unit(Library, Name: NameId): + """ + Just return the design_unit for :obj:`Name`, or ``NULL`` if not found. -Find_Primary_Unit = libghdl.libraries__find_primary_unit + :param Library: Library to look in. Type: ``Iir_Library_Declaration`` + :param Name: Primary unit to search for. + :return: Type: ``Iir_Design_Unit`` + """ + return libghdl.libraries__find_primary_unit(Library, Name) -- cgit v1.2.3