Issue#1358: Adding user_error_message option. (#1387)

Author: jeremiah-c-leary

docs/configuring.rst

@@ -36,6 +36,7 @@ Configuring
    configuring_type_of_instantiations.rst
    configuring_uppercase_and_lowercase_rules.rst
    configuring_use_clause_indenting.rst
+   configuring_user_error_messages.rst
    configuring_whitespace_rules.rst
    configuring_whitespace_after_comment_rules.rst
    configuring_vhdl_reserved_words.rst

docs/configuring_user_error_messages.rst

@@ -0,0 +1,79 @@
+.. _configuring-user-error-messages:
+
+Configuring User Error Messages
+-------------------------------
+
+There is an option to provide additional information to the user when a violation is found.
+This is accomplished by using the :code:`user_error_message` option.
+Setting this option for a rule will append the message to the normal output.
+
+Example without :code:`user_error_message` defined
+##################################################
+
+Applying a custom regex does not provide additional information to the user.
+
+Given the following configuration file which defines a custom regex:
+
+.. code-block:: yaml
+
+    rule:
+      group:
+          case::name:
+              case: regex
+              regex: (?![a-z||0-9]\u005F)(?!.*\u005F[a-z||0-9]$)([a-z||0-9]+(?:\u005F[a-z||0-9]+)*)
+
+The following error report is generated:
+
+.. code-block:: bash
+
+   $vsg -f original.vhd -c config.yaml
+   ================================================================================
+   File:  original.vhd
+   ================================================================================
+   Phase 6 of 7... Reporting
+   Total Rules Checked: 857
+   Total Violations:    2
+     Error   :     2
+     Warning :     0
+   -------------+------------+------------+--------------------------------------
+     Rule       |  severity  |  line(s)   | Solution
+   -------------+------------+------------+--------------------------------------
+     entity_008 | Error      |          2 | Format FIFO to match defined regex
+     entity_012 | Error      |          3 | Format FIFO to match defined regex
+   -------------+------------+------------+--------------------------------------
+   NOTE: Refer to online documentation at https://vhdl-style-guide.readthedocs.io/en/latest/index.html for more information.
+
+Example with :code:`user_error_message` defined
+###############################################
+
+Adding a custom error message can provide additional information to the user:
+
+.. code-block:: yaml
+
+    rule:
+      group:
+          case::name:
+              case: regex
+              regex: (?![a-z||0-9]\u005F)(?!.*\u005F[a-z||0-9]$)([a-z||0-9]+(?:\u005F[a-z||0-9]+)*)
+              user_error_message: "UPPERCASE and single letter prefix/suffix not allowed"
+
+The following error report is generated:
+
+.. code-block:: bash
+
+   $vsg -f original.vhd -c config.yaml
+   ================================================================================
+   File:  original.vhd
+   ================================================================================
+   Phase 6 of 7... Reporting
+   Total Rules Checked: 857
+   Total Violations:    2
+     Error   :     2
+     Warning :     0
+   -------------+------------+------------+--------------------------------------
+     Rule       |  severity  |  line(s)   | Solution
+   -------------+------------+------------+--------------------------------------
+     entity_008 | Error      |          2 | Format FIFO to match defined regex [user_error_message: UPPERCASE and single letter prefix/suffix not allowed]
+     entity_012 | Error      |          3 | Format FIFO to match defined regex [user_error_message: UPPERCASE and single letter prefix/suffix not allowed]
+   -------------+------------+------------+--------------------------------------
+   NOTE: Refer to online documentation at https://vhdl-style-guide.readthedocs.io/en/latest/index.html for more information.

tests/constant/test_rule_400.py

@@ -22,7 +22,7 @@ def test_rule_400_options(self):
         self.assertTrue(oRule)
         self.assertEqual(oRule.name, "constant")
         self.assertEqual(oRule.identifier, "400")
-        self.assertEqual(len(oRule.configuration), 11)
+        self.assertEqual(len(oRule.configuration), 12)
 
     def test_rule_400_yes_no_no_no_no(self):
         oRule = constant.rule_400()

tests/option/test_option.py

@@ -46,6 +46,7 @@ def test_option_reports_in_rc_command(self):
         dExpected["fixable"] = True
         dExpected["severity"] = "Error"
         dExpected["option_name"] = "yes"
+        dExpected["user_error_message"] = ""
 
         dActual = self.oRule.get_configuration()
 

tests/rule/test_rule.py

@@ -87,6 +87,7 @@ def test_get_configuration(self):
         dExpected["indent_style"] = "spaces"
         dExpected["phase"] = 3
         dExpected["severity"] = "Error"
+        dExpected["user_error_message"] = ""
         dActual = oRule.get_configuration()
         for sKey in dExpected.keys():
             self.assertEqual(dActual[sKey], dExpected[sKey])

tests/user_error_messages/__init__.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+
+import os
+import unittest
+
+from tests import utils
+from vsg import vhdlFile
+from vsg.rules import entity
+
+sTestDir = os.path.dirname(__file__)
+
+lFile, eError = vhdlFile.utils.read_vhdlfile(os.path.join(sTestDir, "user_error_messages_input.vhd"))
+
+
+class test_option(unittest.TestCase):
+    def setUp(self):
+        self.oFile = vhdlFile.vhdlFile(lFile)
+        self.assertIsNone(eError)
+
+    def test_rule_entity_008_without_user_message(self):
+        oRule = entity.rule_008()
+        self.assertTrue(oRule)
+        self.assertEqual(oRule.name, "entity")
+        self.assertEqual(oRule.identifier, "008")
+
+        lExpected = [2]
+
+        oRule.analyze(self.oFile)
+        self.assertEqual(utils.extract_violation_lines_from_violation_object(oRule.violations), lExpected)
+        self.assertEqual(1, len(oRule.violations))
+        self.assertEqual('Change "FIFO" to "fifo"', oRule.violations[0].sSolution)
+
+    def test_rule_entity_008_with_user_message(self):
+        oRule = entity.rule_008()
+        self.assertTrue(oRule)
+        self.assertEqual(oRule.name, "entity")
+        self.assertEqual(oRule.identifier, "008")
+        oRule.user_error_message = "This is a user error message."
+
+        lExpected = [2]
+
+        oRule.analyze(self.oFile)
+        self.assertEqual(utils.extract_violation_lines_from_violation_object(oRule.violations), lExpected)
+        self.assertEqual(1, len(oRule.violations))
+        self.assertEqual('Change "FIFO" to "fifo" [user_error_message: This is a user error message.]', oRule.violations[0].sSolution)

tests/user_error_messages/test_user_error_messages.py

@@ -0,0 +1,2 @@
+
+entity FIFO is end entity;

tests/user_error_messages/user_error_messages_input.vhd

@@ -18,10 +18,11 @@ def __init__(self):
         self.disable = False
         self.fixable = True
         self.severity = severity.error("Error")
+        self.user_error_message = ""
         self.debug = False
         self.dFix = {}
         self.dFix["violations"] = {}
-        self.configuration = ["indent_style", "indent_size", "phase", "disable", "fixable", "severity"]
+        self.configuration = ["indent_style", "indent_size", "phase", "disable", "fixable", "severity", "user_error_message"]
         self.deprecated = False
         self.proposed = False
         self.groups = []
@@ -132,6 +133,8 @@ def add_violation(self, violation):
         Adds a linenumber to a violations list.
         """
         if not violation.has_code_tag(self.unique_id):
+            if self.user_error_message != "":
+                violation.sSolution = violation.sSolution + " [user_error_message: " + self.user_error_message + "]"
             self.violations.append(violation)
 
     def analyze(self, oFile):