Adding types and docstrings to libghdl.

10 files changed, 180 insertions, 51 deletions

diff --git a/pyGHDL/libghdl/__init__.py b/pyGHDL/libghdl/__init__.py
index 2d7791b51..1b400c5c1 100644
--- a/pyGHDL/libghdl/__init__.py
+++ b/pyGHDL/libghdl/__init__.py
@@ -7,12 +7,13 @@
 # |_|    |___/                                     |___/
 # =============================================================================
 # Authors:          Tristan Gingold
+#                   Patrick Lehmann
 #
 # Package package:  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
@@ -32,22 +33,18 @@
 # SPDX-License-Identifier: GPL-2.0-or-later
 # ============================================================================
 #
-import ctypes
+from ctypes import c_char_p, CDLL
 import os
 import sys
 from pathlib import Path
 from shutil import which
-from typing import Tuple
 
 from pydecor import export
 
+from pyGHDL.libghdl._types import Iir
 from pyGHDL.libghdl.version import __version__
 
 
-def _to_char_p(arg: bytes) -> Tuple[ctypes.c_char_p, int]:
-    return ctypes.c_char_p(arg), len(arg)
-
-
 def _get_libghdl_name() -> Path:
     """Get the name of the libghdl library (with version and extension)"""
     ver = __version__.replace("-", "_").replace(".", "_")
@@ -129,22 +126,27 @@ def _get_libghdl_path():
     # Failed.
     raise Exception("Cannot find libghdl {}".format(basename))
 
+def _initialize():
+    # Load the shared library
+    _libghdl_path = _get_libghdl_path()
+    # print("Load {}".format(_libghdl_path))
+    libghdl = CDLL(str(_libghdl_path))
+
+    # Initialize it.
+    # First Ada elaboration (must be the first call)
+    libghdl.libghdl_init()
+    # Then 'normal' initialization (set hooks)
+    libghdl.libghdl__set_hooks_for_analysis()
 
-# Load the shared library
-_libghdl_path = _get_libghdl_path()
-# print("Load {}".format(_libghdl_path))
-libghdl = ctypes.CDLL(str(_libghdl_path))
+    # Set the prefix in order to locate the VHDL libraries.
+    prefix = str(_libghdl_path.parent.parent).encode("utf-8")
+    libghdl.libghdl__set_exec_prefix(c_char_p(prefix), len(prefix))
 
-# Initialize it.
-# First Ada elaboration (must be the first call)
-libghdl.libghdl_init()
-# Then 'normal' initialization (set hooks)
-libghdl.libghdl__set_hooks_for_analysis()
+    return libghdl
+
+# Initialize shared library when package is loaded
+libghdl = _initialize()
 
-# Set the prefix in order to locate the VHDL libraries.
-libghdl.libghdl__set_exec_prefix(
-    *_to_char_p(str(_libghdl_path.parent.parent).encode("utf-8"))
-)
 
 @export
 def finalize() -> None:
@@ -159,9 +161,10 @@ def initialize() -> None:
 
 
 @export
-def set_option(opt: bytes) -> bool:
+def set_option(opt: str) -> bool:
     """Set option :obj:`opt`. Return true, if the option is known and handled."""
-    return libghdl.libghdl__set_option(*_to_char_p(opt)) == 0
+    opt = opt.encode("utf-8")
+    return libghdl.libghdl__set_option(c_char_p(opt), len(opt)) == 0
 
 
 @export
@@ -174,18 +177,21 @@ def analyze_init() -> None:
     """
     libghdl.libghdl__analyze_init()
 
+
 @export
 def analyze_init_status() -> int:
     """Initialize the analyzer. Returns 0 in case of success."""
     return libghdl.libghdl__analyze_init_status()
 
+
 @export
-def analyze_file(fname: bytes):
-    """"Analyze a given filename :obj:`fname`."""
-    return libghdl.libghdl__analyze_file(*_to_char_p(fname))
+def analyze_file(fname: str) -> Iir:
+    """Analyze a given filename :obj:`fname`."""
+    fname = fname.encode("utf-8")
+    return libghdl.libghdl__analyze_file(c_char_p(fname), len(fname))
 
 
 @export
-def disp_config():
-    """"Display the configured prefixes for libghdl."""
-    return libghdl.ghdllocal__disp_config_prefixes()
+def disp_config() -> None:
+    """Display the configured prefixes for libghdl."""
+    libghdl.ghdllocal__disp_config_prefixes()
diff --git a/pyGHDL/libghdl/errorout.py b/pyGHDL/libghdl/errorout.py
index c49251bf4..2d7f29ef5 100644
--- a/pyGHDL/libghdl/errorout.py
+++ b/pyGHDL/libghdl/errorout.py
@@ -1,11 +1,17 @@
 # Auto generated Python source file from Ada sources
 # Call 'make' in 'src/vhdl' to regenerate:
 #
+from pydecor import export
 from pyGHDL.libghdl import libghdl
+from pyGHDL.libghdl._types import MessageIdWarnings
 
-Enable_Warning = libghdl.errorout__enable_warning
 
+@export
+def Enable_Warning(Id: MessageIdWarnings, Enable: bool) -> None:
+    libghdl.errorout__enable_warning(Id, Enable)
 
+
+@export
 class Msgid:
     Msgid_Note = 0
     Warnid_Library = 1
diff --git a/pyGHDL/libghdl/errorout_console.py b/pyGHDL/libghdl/errorout_console.py
index 8862b92ec..a553e70b9 100644
--- a/pyGHDL/libghdl/errorout_console.py
+++ b/pyGHDL/libghdl/errorout_console.py
@@ -1,3 +1,43 @@
+# =============================================================================
+#               ____ _   _ ____  _       _ _ _           _         _ _
+#  _ __  _   _ / ___| | | |  _ \| |     | (_) |__   __ _| |__   __| | |
+# | '_ \| | | | |  _| |_| | | | | |     | | | '_ \ / _` | '_ \ / _` | |
+# | |_) | |_| | |_| |  _  | |_| | |___ _| | | |_) | (_| | | | | (_| | |
+# | .__/ \__, |\____|_| |_|____/|_____(_)_|_|_.__/ \__, |_| |_|\__,_|_|
+# |_|    |___/                                     |___/
+# =============================================================================
+# Authors:          Tristan Gingold
+#                   Patrick Lehmann
+#
+# Package package:  Python binding and low-level API for shared library 'libghdl'.
+#
+# License:
+# ============================================================================
+# 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
+#	Software Foundation; either version 2, or (at your option) any later
+#	version.
+#
+#	GHDL 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 GHDL; see the file COPYING.  If not, write to the Free
+#	Software Foundation, 59 Temple Place - Suite 330, Boston, MA
+#	02111-1307, USA.
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+# ============================================================================
+#
+from pydecor import export
+
 from pyGHDL.libghdl import libghdl
 
-Install_Handler = libghdl.errorout__console__install_handler
+
+@export
+def Install_Handler() -> None:
+    libghdl.errorout__console__install_handler()
diff --git a/pyGHDL/libghdl/errorout_memory.py b/pyGHDL/libghdl/errorout_memory.py
index c7295c113..f9977ec27 100644
--- a/pyGHDL/libghdl/errorout_memory.py
+++ b/pyGHDL/libghdl/errorout_memory.py
@@ -7,12 +7,13 @@
 # |_|    |___/                                     |___/
 # =============================================================================
 # Authors:          Tristan Gingold
+#                   Patrick Lehmann
 #
 # Package package:  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
@@ -37,6 +38,7 @@ from ctypes import c_int8, c_int32, c_char_p, Structure
 from pydecor import export
 
 from pyGHDL.libghdl import libghdl
+from pyGHDL.libghdl._types import ErrorIndex
 
 
 @export
@@ -57,16 +59,35 @@ Msg_Main = 1
 Msg_Related = 2
 Msg_Last = 3
 
-Install_Handler = libghdl.errorout__memory__install_handler
 
-Get_Nbr_Messages = libghdl.errorout__memory__get_nbr_messages
+@export
+def Install_Handler() -> None:
+    libghdl.errorout__memory__install_handler()
+
+
+@export
+def Get_Nbr_Messages() -> ErrorIndex:
+    return libghdl.errorout__memory__get_nbr_messages()
+
 
-Get_Error_Record = libghdl.errorout__memory__get_error_record
-Get_Error_Record.argstypes = [c_int32]
-Get_Error_Record.restype = Error_Message
+@export
+def Get_Error_Record(Idx: ErrorIndex): # FIXME: returns Error_Message
+    func = libghdl.errorout__memory__get_error_record
+    func.argstypes = [c_int32]
+    func.restype = Error_Message
+    return func(Idx)
 
-Get_Error_Message = libghdl.errorout__memory__get_error_message_addr
-Get_Error_Message.argstype = [c_int32]
-Get_Error_Message.restype = c_char_p
 
-Clear_Errors = libghdl.errorout__memory__clear_errors
+@export
+def Get_Error_Message(Idx: ErrorIndex) -> str:   # FIXME: check '*_addr' vs string return value
+    func = libghdl.errorout__memory__get_error_message_addr
+    func.argstype = [c_int32]
+    func.restype = c_char_p
+
+    # FIXME: don't we need to encode to utf-8?
+    return func(Idx)
+
+
+@export
+def Clear_Errors() -> None:
+    libghdl.errorout__memory__clear_errors()
diff --git a/pyGHDL/libghdl/files_map.py b/pyGHDL/libghdl/files_map.py
index 708b20181..195b1d70e 100644
--- a/pyGHDL/libghdl/files_map.py
+++ b/pyGHDL/libghdl/files_map.py
@@ -7,12 +7,13 @@
 # |_|    |___/                                     |___/
 # =============================================================================
 # Authors:          Tristan Gingold
+#                   Patrick Lehmann
 #
 # Package package:  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,7 +35,10 @@
 #
 from ctypes import c_void_p
 
+from pydecor import export
+
 from pyGHDL.libghdl import libghdl
+from pyGHDL.libghdl._types import NameId, SourceFileEntry
 
 
 EOT = b"\x04"
@@ -69,7 +73,9 @@ Get_File_Buffer.restype = c_void_p
 Get_File_Length = libghdl.files_map__get_file_length
 Set_File_Length = libghdl.files_map__set_file_length
 
-Read_Source_File = libghdl.files_map__read_source_file
+@export
+def Read_Source_File(DirectoryId: NameId, NameId: NameId) -> SourceFileEntry:
+    return libghdl.files_map__read_source_file(DirectoryId, NameId)
 
 Reserve_Source_File = libghdl.files_map__reserve_source_file
 
diff --git a/pyGHDL/libghdl/name_table.py b/pyGHDL/libghdl/name_table.py
index e2190f3dd..b82207fb3 100644
--- a/pyGHDL/libghdl/name_table.py
+++ b/pyGHDL/libghdl/name_table.py
@@ -7,12 +7,13 @@
 # |_|    |___/                                     |___/
 # =============================================================================
 # Authors:          Tristan Gingold
+#                   Patrick Lehmann
 #
 # Package package:  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
@@ -37,19 +38,50 @@ from ctypes import c_char_p
 from pydecor import export
 
 from pyGHDL.libghdl import libghdl
+from pyGHDL.libghdl._types import NameId
 
 
-Get_Name_Length = libghdl.name_table__get_name_length
+Null_Identifier = 0
+
 
-Get_Name_Ptr = libghdl.name_table__get_name_ptr
-Get_Name_Ptr.restype = c_char_p
+@export
+def Get_Name_Length(Id: NameId) -> int:
+    """
+    Get the length of an identifier denoted by a ``NameId``.
 
-_Get_Identifier_With_Len = libghdl.name_table__get_identifier_with_len
+    :param Id: NameId for the identifier to query.
+    :return:   Length of the identifier.
+    """
+    return libghdl.name_table__get_name_length(Id)
 
 
 @export
-def Get_Identifier(s):
-    return _Get_Identifier_With_Len(c_char_p(s), len(s))
+def Get_Name_Ptr(Id: NameId) -> bytes:
+    """
+    Get the address of the first character of ID.  The address is valid until
+    the next call to Get_Identifier (which may reallocate the string table).
+    The string is NUL-terminated (this is done by get_identifier).
 
+    :param Id: NameId for the identifier to query.
+    :return:
+    """
+    func = libghdl.name_table__get_name_ptr
+    func.restype = c_char_p
+    # FIXME: don't we need to encode to utf-8?
+    return func(Id)
 
-Null_Identifier = 0
+
+@export
+def Get_Identifier(string: str) -> NameId:
+    """
+    Get or create an entry in the name table.
+
+    Note:
+    * an identifier is represented in all lower case letter,
+    * an extended identifier is represented in backslashes, double internal backslashes are simplified.
+
+    :param string: String to create or lookup.
+    :return:       Id in name table.
+    """
+    string = string.encode("utf-8")
+    return libghdl.name_table__get_identifier_with_len(c_char_p(string), len(string))
diff --git a/pyGHDL/libghdl/std_names.py b/pyGHDL/libghdl/std_names.py
index ebef045ff..201e9cb09 100644
--- a/pyGHDL/libghdl/std_names.py
+++ b/pyGHDL/libghdl/std_names.py
@@ -1,6 +1,10 @@
 # Auto generated Python source file from Ada sources
 # Call 'make' in 'src/vhdl' to regenerate:
 #
+from pydecor import export
+
+
+@export
 class Name:
     First_Character = 1
     Last_Character = 256
diff --git a/pyGHDL/libghdl/vhdl/nodes.py b/pyGHDL/libghdl/vhdl/nodes.py
index fdf3fa437..659813d1e 100644
--- a/pyGHDL/libghdl/vhdl/nodes.py
+++ b/pyGHDL/libghdl/vhdl/nodes.py
@@ -1,6 +1,7 @@
 # Auto generated Python source file from Ada sources
 # Call 'make' in 'src/vhdl' to regenerate:
 #
+from pydecor import export
 from pyGHDL.libghdl import libghdl
 
 Null_Iir = 0
@@ -13,7 +14,7 @@ Iir_Flist_Others = 1
 Iir_Flist_All = 2
 
 
-
+@export
 class Iir_Kind:
     Unused = 0
     Error = 1
@@ -332,6 +333,7 @@ class Iir_Kind:
     Attribute_Name = 314
 
 
+@export
 class Iir_Kinds:
     Library_Unit = [
         Iir_Kind.Entity_Declaration,
@@ -1034,6 +1036,7 @@ class Iir_Kinds:
 
 
 
+@export
 class Iir_Mode:
     Unknown_Mode = 0
     Linkage_Mode = 1
@@ -1043,6 +1046,7 @@ class Iir_Mode:
     In_Mode = 5
 
 
+@export
 class Iir_Staticness:
     Unknown = 0
     PNone = 1
@@ -1050,17 +1054,20 @@ class Iir_Staticness:
     Locally = 3
 
 
+@export
 class Iir_Constraint:
     Unconstrained = 0
     Partially_Constrained = 1
     Fully_Constrained = 2
 
 
+@export
 class Iir_Delay_Mechanism:
     Inertial_Delay = 0
     Transport_Delay = 1
 
 
+@export
 class Date_State:
     Extern = 0
     Disk = 1
@@ -1068,6 +1075,7 @@ class Date_State:
     Analyze = 3
 
 
+@export
 class Iir_Predefined:
     Error = 0
     Boolean_And = 1
diff --git a/pyGHDL/libghdl/vhdl/nodes_meta.py b/pyGHDL/libghdl/vhdl/nodes_meta.py
index 1826bef68..7d41476b2 100644
--- a/pyGHDL/libghdl/vhdl/nodes_meta.py
+++ b/pyGHDL/libghdl/vhdl/nodes_meta.py
@@ -1,6 +1,7 @@
 # Auto generated Python source file from Ada sources
 # Call 'make' in 'src/vhdl' to regenerate:
 #
+from pydecor import export
 from pyGHDL.libghdl import libghdl
 
 
@@ -16,6 +17,7 @@ get_field_type = libghdl.vhdl__nodes_meta__get_field_type
 get_field_attribute = libghdl.vhdl__nodes_meta__get_field_attribute
 
 
+@export
 class types:
     Boolean = 0
     Date_State_Type = 1
@@ -52,6 +54,7 @@ class types:
     Tri_State_Type = 32
 
 
+@export
 class Attr:
     ANone = 0
     Chain = 1
@@ -64,6 +67,7 @@ class Attr:
     Ref = 8
 
 
+@export
 class fields:
     First_Design_Unit = 0
     Last_Design_Unit = 1
diff --git a/pyGHDL/libghdl/vhdl/tokens.py b/pyGHDL/libghdl/vhdl/tokens.py
index d75ef1bde..87cc848b8 100644
--- a/pyGHDL/libghdl/vhdl/tokens.py
+++ b/pyGHDL/libghdl/vhdl/tokens.py
@@ -1,8 +1,10 @@
 # Auto generated Python source file from Ada sources
 # Call 'make' in 'src/vhdl' to regenerate:
 #
+from pydecor import export
 
 
+@export
 class Tok:
     Invalid = 0
     Left_Paren = 1