From 2bd7374572542e36740085f3e9328e8169fc2c1e Mon Sep 17 00:00:00 2001 From: Tristan Gingold Date: Mon, 21 Nov 2022 08:04:17 +0100 Subject: testsuite/pyunit: add more tests for comments --- testsuite/pyunit/libghdl/Comment2.vhdl | 132 +++++++++++++++++++++++++ testsuite/pyunit/libghdl/Comments.py | 125 ++++++++++++++++++----- testsuite/pyunit/libghdl/arch_bef.vhdl | 5 + testsuite/pyunit/libghdl/arch_inside.vhdl | 6 ++ testsuite/pyunit/libghdl/arch_inside_fail.vhdl | 5 + testsuite/pyunit/libghdl/conf_bef.vhdl | 6 ++ testsuite/pyunit/libghdl/conf_inside.vhdl | 6 ++ testsuite/pyunit/libghdl/conf_inside_fail.vhdl | 6 ++ testsuite/pyunit/libghdl/ctxt_bef.vhdl | 4 + testsuite/pyunit/libghdl/ctxt_inside.vhdl | 5 + testsuite/pyunit/libghdl/ctxt_inside_fail.vhdl | 5 + testsuite/pyunit/libghdl/ent_bef.vhdl | 4 + testsuite/pyunit/libghdl/ent_inside.vhdl | 15 +++ testsuite/pyunit/libghdl/pkg_bef.vhdl | 4 + testsuite/pyunit/libghdl/pkg_inside.vhdl | 5 + testsuite/pyunit/libghdl/pkg_inside_fail.vhdl | 3 + 16 files changed, 311 insertions(+), 25 deletions(-) create mode 100644 testsuite/pyunit/libghdl/Comment2.vhdl create mode 100644 testsuite/pyunit/libghdl/arch_bef.vhdl create mode 100644 testsuite/pyunit/libghdl/arch_inside.vhdl create mode 100644 testsuite/pyunit/libghdl/arch_inside_fail.vhdl create mode 100644 testsuite/pyunit/libghdl/conf_bef.vhdl create mode 100644 testsuite/pyunit/libghdl/conf_inside.vhdl create mode 100644 testsuite/pyunit/libghdl/conf_inside_fail.vhdl create mode 100644 testsuite/pyunit/libghdl/ctxt_bef.vhdl create mode 100644 testsuite/pyunit/libghdl/ctxt_inside.vhdl create mode 100644 testsuite/pyunit/libghdl/ctxt_inside_fail.vhdl create mode 100644 testsuite/pyunit/libghdl/ent_bef.vhdl create mode 100644 testsuite/pyunit/libghdl/ent_inside.vhdl create mode 100644 testsuite/pyunit/libghdl/pkg_bef.vhdl create mode 100644 testsuite/pyunit/libghdl/pkg_inside.vhdl create mode 100644 testsuite/pyunit/libghdl/pkg_inside_fail.vhdl (limited to 'testsuite/pyunit') diff --git a/testsuite/pyunit/libghdl/Comment2.vhdl b/testsuite/pyunit/libghdl/Comment2.vhdl new file mode 100644 index 000000000..e56815a52 --- /dev/null +++ b/testsuite/pyunit/libghdl/Comment2.vhdl @@ -0,0 +1,132 @@ +-- comments before design units (javadoc / .net documentation style) +-- might be multiline +entity e1 is +end entity; + +-- comments before design units +-- might be multiline +architecture a1 of e1 is +begin +end architecture; + +-- comments before design units +-- might be multiline +package p1 is +end package; + +-- package body should be supported too to keep parity, but I have currently no usecase for it. + +-- comments before design units +-- might be multiline +context ctx1 is +end context; + +-- comments before design units +-- might be multiline +configuration cfg1 of e1 is + for a1 + end for; +end configuration; + + +library ieee; +use ieee.std_logic_1164.all; + +entity e2 is + -- comments in design units (python doc-string style) + -- might be multi line + generic ( + -- comment before a generic + -- might be multiline + constant FREQUENCY : positive; + constant BITS : positive; -- comment after a generic are mostly single line, + -- but could be multi line too + -- in case comment is before and after + constant DEBUG : boolean -- the after has presidence + ); + port ( + signal Clock : in std_logic -- same as for generics + ); +end entity; + +architecture a2 of e2 is + -- comments in design units (python doc-string style) + -- might be multi line +begin + +end architecture; + +-- As packages define public elements like constants, types and sub-programs, we are intrested in such documentation too. +package p2 is + -- comments in design units (python doc-string style) + -- might be multi line + + -- comment before + constant DEBUG : boolean := TRUE; + constant SYNC_STAGES : positive := 3; -- comment after + + -- comment before + type AType1 is array(natural range <>) of bit; + type AType2 is array(natural range <>) of bit; -- comment after + + -- same applies to subtype, alias, attributes, ... + + -- comment before + type RType is record + -- xor comment inside + + -- per element comment before (note the comment "block" is separated by newlines) + elem1 : integer; + elem2 : integer; -- per element comment behind + end record; + + -- as functions are longer in definitions, it might be written before + function log2(param : positive) return natural; + + function log2( + -- otoh, we also want to document parameters too (similar to a record with comments) + + -- comment before + param1 : integer; + param2 : boolean -- comment after + ) return natural; + + -- this applies to procedures as well. + + + +end package; + +context ctx2 is + -- comments in design units (python doc-string style) + -- might be multi line +end context; + +configuration cfg2 of e2 is + -- comments in design units (python doc-string style) + -- might be multi line + for a2 + end for; +end configuration; + + + + + + + +-- This should allow for any kind of documentation style and embedded documentation language. +-- A real implementation might use similar rules are Python+docutils+Sphinx. Here we would e.g. +-- document a function either before (or inside) a function declaration and use the +-- :arg name: description +-- syntax. + + +-- Package `math` provides math extensions not provided by the IEEE packages. +package math is + -- Computes the logarith to base 2. + -- + -- :arg param: Input value + -- :returns: Logarithm + function log2(param : positive) return natural; +end package; diff --git a/testsuite/pyunit/libghdl/Comments.py b/testsuite/pyunit/libghdl/Comments.py index ada8f326e..9a4daf007 100644 --- a/testsuite/pyunit/libghdl/Comments.py +++ b/testsuite/pyunit/libghdl/Comments.py @@ -1,5 +1,5 @@ from pathlib import Path -from unittest import TestCase +from unittest import TestCase, skip, expectedFailure import pyGHDL.libghdl as libghdl from pyGHDL.libghdl import name_table, files_map, errorout_console, flags @@ -13,25 +13,15 @@ if __name__ == "__main__": class Instantiate(TestCase): - _root = Path(__file__).resolve().parent.parent - _filename: Path = _root / "DesignComment.vhdl" + _root = Path(__file__).resolve().parent @staticmethod def getIdentifier(node) -> str: """Return the Python string from node :obj:`node` identifier.""" return name_table.Get_Name_Ptr(nodes.Get_Identifier(node)) - def checkComments(self, node, name) -> None: - f = files_map.Location_To_File(nodes.Get_Location(node)) - idx = file_comments.Find_First_Comment(f, node) - while idx != file_comments.No_Comment_Index: - s = file_comments.Get_Comment(f, idx) - self.assertTrue(s.find(':'+name+':') >= 0, - "no :{}: in '{}'".format(name, s)) - idx = file_comments.Get_Next_Comment(f, idx) - - def test_Comments(self) -> None: - """Initialization: set options and then load libaries.""" + @classmethod + def setUpClass(cls): libghdl.initialize() # Print error messages on the console. @@ -45,11 +35,27 @@ class Instantiate(TestCase): if libghdl.analyze_init_status() != 0: self.fail("libghdl initialization error") + def checkComments(self, node, name) -> None: + f = files_map.Location_To_File(nodes.Get_Location(node)) + idx = file_comments.Find_First_Comment(f, node) + while idx != file_comments.No_Comment_Index: + s = file_comments.Get_Comment(f, idx) + self.assertTrue(s.find(':'+name+':') >= 0, + "no :{}: in '{}'".format(name, s)) + idx = file_comments.Get_Next_Comment(f, idx) + + def checkInterfaces(self, first) -> None: + inter = first + while inter != nodes.Null_Iir: + self.checkComments(inter, self.getIdentifier(inter)) + inter = nodes.Get_Chain(inter) + + def checkFile(self, filename) -> None: # Load the file - file_id = name_table.Get_Identifier(str(self._filename)) + file_id = name_table.Get_Identifier(str(filename)) sfe = files_map.Read_Source_File(name_table.Null_Identifier, file_id) if sfe == files_map.No_Source_File_Entry: - self.fail("Cannot read file '{!s}'".format(self._filename)) + self.fail("Cannot read file '{!s}'".format(filename)) # Parse file = sem_lib.Load_File(sfe) @@ -59,18 +65,87 @@ class Instantiate(TestCase): while designUnit != nodes.Null_Iir: libraryUnit = nodes.Get_Library_Unit(designUnit) - if nodes.Get_Kind(libraryUnit) == nodes.Iir_Kind.Entity_Declaration: - entityName = self.getIdentifier(libraryUnit) - self.checkComments(designUnit, entityName) - port = nodes.Get_Port_Chain(libraryUnit) - while port != nodes.Null_Iir: - self.checkComments(port, self.getIdentifier(port)) - port = nodes.Get_Chain(port) + k = nodes.Get_Kind(libraryUnit) + name = self.getIdentifier(libraryUnit) + + if k == nodes.Iir_Kind.Entity_Declaration: + self.checkComments(designUnit, name) + self.checkComments(libraryUnit, name) + self.checkInterfaces(nodes.Get_Generic_Chain(libraryUnit)) + self.checkInterfaces(nodes.Get_Port_Chain(libraryUnit)) - elif nodes.Get_Kind(libraryUnit) == nodes.Iir_Kind.Architecture_Body: - architectureName = self.getIdentifier(libraryUnit) + elif k == nodes.Iir_Kind.Architecture_Body: + self.checkComments(designUnit, name) + self.checkComments(libraryUnit, name) + + elif k == nodes.Iir_Kind.Package_Declaration: + self.checkComments(designUnit, name) + self.checkComments(libraryUnit, name) + + elif k == nodes.Iir_Kind.Context_Declaration: + self.checkComments(designUnit, name) + self.checkComments(libraryUnit, name) + + elif k == nodes.Iir_Kind.Configuration_Declaration: + self.checkComments(designUnit, name) + self.checkComments(libraryUnit, name) else: self.fail("Unknown unit.") designUnit = nodes.Get_Chain(designUnit) + + def test_Comments(self) -> None: + """Very first test""" + self.checkFile(self._root / "DesignComment.vhdl") + + @skip("not yet handled") + def test_Comment2(self) -> None: + """More exhaustive""" + self.checkFile(self._root / "Comment2.vhdl") + + def test_entity_before(self) -> None: + self.checkFile(self._root / "ent_bef.vhdl") + + def test_arch_before(self) -> None: + self.checkFile(self._root / "arch_bef.vhdl") + + def test_pkg_before(self) -> None: + self.checkFile(self._root / "pkg_bef.vhdl") + + def test_ctxt_before(self) -> None: + self.checkFile(self._root / "ctxt_bef.vhdl") + + def test_conf_before(self) -> None: + self.checkFile(self._root / "conf_bef.vhdl") + + def test_entity_inside(self) -> None: + self.checkFile(self._root / "ent_inside.vhdl") + + @expectedFailure + def test_arch_inside_fail(self) -> None: + self.checkFile(self._root / "arch_inside_fail.vhdl") + + def test_arch_inside(self) -> None: + self.checkFile(self._root / "arch_inside.vhdl") + + @expectedFailure + def test_pkg_inside_fail(self) -> None: + self.checkFile(self._root / "pkg_inside_fail.vhdl") + + def test_pkg_inside(self) -> None: + self.checkFile(self._root / "pkg_inside.vhdl") + + @expectedFailure + def test_ctxt_inside_fail(self) -> None: + self.checkFile(self._root / "ctxt_inside_fail.vhdl") + + def test_ctxt_inside(self) -> None: + self.checkFile(self._root / "ctxt_inside.vhdl") + + @expectedFailure + def test_conf_inside_fail(self) -> None: + self.checkFile(self._root / "conf_inside_fail.vhdl") + + def test_conf_inside(self) -> None: + self.checkFile(self._root / "conf_inside.vhdl") diff --git a/testsuite/pyunit/libghdl/arch_bef.vhdl b/testsuite/pyunit/libghdl/arch_bef.vhdl new file mode 100644 index 000000000..c089b1429 --- /dev/null +++ b/testsuite/pyunit/libghdl/arch_bef.vhdl @@ -0,0 +1,5 @@ +-- comments before design units :a1: +-- might be multiline :a1: +architecture a1 of e1 is +begin +end architecture; diff --git a/testsuite/pyunit/libghdl/arch_inside.vhdl b/testsuite/pyunit/libghdl/arch_inside.vhdl new file mode 100644 index 000000000..9e2184df3 --- /dev/null +++ b/testsuite/pyunit/libghdl/arch_inside.vhdl @@ -0,0 +1,6 @@ +architecture a2 of e2 is + -- comments in design units (python doc-string style) :a2: + --:a2: might be multi line +begin + +end architecture; diff --git a/testsuite/pyunit/libghdl/arch_inside_fail.vhdl b/testsuite/pyunit/libghdl/arch_inside_fail.vhdl new file mode 100644 index 000000000..96002d336 --- /dev/null +++ b/testsuite/pyunit/libghdl/arch_inside_fail.vhdl @@ -0,0 +1,5 @@ +architecture a2 of e2 is + -- comments in design units (python doc-string style) :fail: +begin + +end architecture; diff --git a/testsuite/pyunit/libghdl/conf_bef.vhdl b/testsuite/pyunit/libghdl/conf_bef.vhdl new file mode 100644 index 000000000..0dc3af77e --- /dev/null +++ b/testsuite/pyunit/libghdl/conf_bef.vhdl @@ -0,0 +1,6 @@ +-- comments before design units :cfg1: +-- might be multiline :cfg1: +configuration cfg1 of e1 is + for a1 + end for; +end configuration; diff --git a/testsuite/pyunit/libghdl/conf_inside.vhdl b/testsuite/pyunit/libghdl/conf_inside.vhdl new file mode 100644 index 000000000..6181d572a --- /dev/null +++ b/testsuite/pyunit/libghdl/conf_inside.vhdl @@ -0,0 +1,6 @@ +configuration cfg2 of e2 is + -- comments in design units (python doc-string style) :cfg2: + -- might be multi line :cfg2: + for a2 + end for; +end configuration; diff --git a/testsuite/pyunit/libghdl/conf_inside_fail.vhdl b/testsuite/pyunit/libghdl/conf_inside_fail.vhdl new file mode 100644 index 000000000..6b9b4dce3 --- /dev/null +++ b/testsuite/pyunit/libghdl/conf_inside_fail.vhdl @@ -0,0 +1,6 @@ +configuration cfg2 of e2 is + -- comments in design units (python doc-string style) + -- might be multi line + for a2 + end for; +end configuration; diff --git a/testsuite/pyunit/libghdl/ctxt_bef.vhdl b/testsuite/pyunit/libghdl/ctxt_bef.vhdl new file mode 100644 index 000000000..f7a8fd31c --- /dev/null +++ b/testsuite/pyunit/libghdl/ctxt_bef.vhdl @@ -0,0 +1,4 @@ +-- comments before design units :ctx1: +--:ctx1: might be multiline +context ctx1 is +end context; diff --git a/testsuite/pyunit/libghdl/ctxt_inside.vhdl b/testsuite/pyunit/libghdl/ctxt_inside.vhdl new file mode 100644 index 000000000..af7fdc37b --- /dev/null +++ b/testsuite/pyunit/libghdl/ctxt_inside.vhdl @@ -0,0 +1,5 @@ +context ctx2 is + -- comments in design units (python doc-string style) :ctx2: + -- might be multi line :ctx2: +end context; + diff --git a/testsuite/pyunit/libghdl/ctxt_inside_fail.vhdl b/testsuite/pyunit/libghdl/ctxt_inside_fail.vhdl new file mode 100644 index 000000000..71dce9e40 --- /dev/null +++ b/testsuite/pyunit/libghdl/ctxt_inside_fail.vhdl @@ -0,0 +1,5 @@ +context ctx2 is + -- comments in design units (python doc-string style) + -- might be multi line +end context; + diff --git a/testsuite/pyunit/libghdl/ent_bef.vhdl b/testsuite/pyunit/libghdl/ent_bef.vhdl new file mode 100644 index 000000000..0fbf61d22 --- /dev/null +++ b/testsuite/pyunit/libghdl/ent_bef.vhdl @@ -0,0 +1,4 @@ +-- comments before design units (javadoc / .net documentation style) :e1: +-- might be multiline :e1: +entity e1 is +end entity; diff --git a/testsuite/pyunit/libghdl/ent_inside.vhdl b/testsuite/pyunit/libghdl/ent_inside.vhdl new file mode 100644 index 000000000..834eaa999 --- /dev/null +++ b/testsuite/pyunit/libghdl/ent_inside.vhdl @@ -0,0 +1,15 @@ +library ieee; +use ieee.std_logic_1164.all; + +entity e2 is + -- comments in design units (python doc-string style) :e2: + -- might be multi line :e2: + generic ( + -- comment before a generic :frequency: + -- might be multiline :frequency: + constant FREQUENCY : positive + ); + port ( + signal Clock : in std_logic + ); +end entity; diff --git a/testsuite/pyunit/libghdl/pkg_bef.vhdl b/testsuite/pyunit/libghdl/pkg_bef.vhdl new file mode 100644 index 000000000..1ed150346 --- /dev/null +++ b/testsuite/pyunit/libghdl/pkg_bef.vhdl @@ -0,0 +1,4 @@ +-- comments before design units :p1: +-- :p1: might be multiline +package p1 is +end package; diff --git a/testsuite/pyunit/libghdl/pkg_inside.vhdl b/testsuite/pyunit/libghdl/pkg_inside.vhdl new file mode 100644 index 000000000..c9f6129d4 --- /dev/null +++ b/testsuite/pyunit/libghdl/pkg_inside.vhdl @@ -0,0 +1,5 @@ +-- As packages define public elements like constants, types and sub-programs, we are intrested in such documentation too.:p2: +package p2 is + -- comments in design units (python doc-string style):p2: + -- might be multi line :p2: +end package; diff --git a/testsuite/pyunit/libghdl/pkg_inside_fail.vhdl b/testsuite/pyunit/libghdl/pkg_inside_fail.vhdl new file mode 100644 index 000000000..f5e347488 --- /dev/null +++ b/testsuite/pyunit/libghdl/pkg_inside_fail.vhdl @@ -0,0 +1,3 @@ +package p2 is + -- comments in design units (python doc-string style) :fail: +end package; -- cgit v1.2.3