diff --git a/docs/configuring.rst b/docs/configuring.rst index c370f908..373af516 100644 --- a/docs/configuring.rst +++ b/docs/configuring.rst @@ -1,7 +1,7 @@ Configuring =========== -VSG can use a configuration file to alter it's behavior or include a list of files to analyze. +VSG can use a configuration file to alter it's behavior and/or include a list of files to analyze. This is accomplished by passing JSON and/or YAML file(s) through the **--configuration** command line argument. This is the basic form of a configuration file in JSON: @@ -10,9 +10,12 @@ This is the basic form of a configuration file in JSON: { "file_list":[ "fifo.vhd", - "source/spi.vhd", "$PATH_TO_FILE/spi_master.vhd", - "$OTHER_PATH/src/*.vhd" + "$OTHER_PATH/src/*.vhd", + "source/spi.vhd": { + "rule": { + "ruleId_ruleNumber":"blah" + } ], "local_rules":"$DIRECTORY_PATH", "rule":{ @@ -32,7 +35,10 @@ This is the basic form of a configuration file in YAML: --- file_list:[ - fifo.vhd - - source/spi.vhd + - source/spi.vhd: + rule: + ruleId_ruleNumber: + attributeName: AttributeValue - $PATH_TO_FILE/spi_master.vhd - $OTHER_PATH/src/*.vhd local_rules: $DIRECTORY_PATH @@ -40,13 +46,12 @@ This is the basic form of a configuration file in YAML: global: attributeName: AttributeValue ruleId_ruleNumber: - attributeName: AttributeValue + attributeName: AttributeValue ... It is not required to have **file_list**, **local_rules**, and **rule** defined in the configuration file. -Any combination can be defined. -The order does not matter either. +Any combination can be defined, and the order does not matter. .. NOTE:: All examples of configurations in this documentation use JSON. However, YAML can be used instead. @@ -59,6 +64,8 @@ File globbing is also supported. The Environment variables will be expanded before globbing occurs. This option can be useful when running VSG over multiple files. +Rule configurations can be specified for each file by following the format of the **rule** configuration. + local_rules ----------- @@ -90,8 +97,6 @@ Here are a list of attributes that can be altered for each rule: | fixable | Boolean | If set to False, the violation will not be fixed | +-------------+---------+--------------------------------------------------+ -.. NOTE:: Some rules have additional attributes. These will be noted in the rule description. - Reporting Single Rule Configuration ----------------------------------- @@ -125,6 +130,48 @@ Every rule configuration can be report and saved to a file using the **-oc** opt The output file will be in JSON format and can be modified and passed back to VSG using the *-c* option. +Rule Configuration Priorities +----------------------------- + +There are three ways to configure a rule. +From least to highest priority are: + +* **[rule][global]** +* **[rule][]** +* **[file_list][][rule][]**. + +If the same rule is defined in all three locations as in the example below, then the final setting will be equal to the highest priority. + +.. code-block:: json + + { + "file_list":[ + "entity.vhd":{ + "rule":{ + "length_001":{ + "disable": true + } + } + }, + "architecture.vhd", + "package.vhd" + ], + "rule":{ + "global":{ + "disable": true + }, + "rule": { + "length_001":{ + "disable": false + } + } + } + + +In this example configuration, all rules are disabled by the **global** configuration. +Then rule **length_001** is enabled for the files **architecture.vhd**, **package.vhd** and **entity.vhd** by the **rule** configuration. +Then rule **length_001** is disabled for the file **entity.vhd**. + Example: Disabling a rule -------------------------- diff --git a/vsg/__main__.py b/vsg/__main__.py index 74b1a04b..e769b417 100644 --- a/vsg/__main__.py +++ b/vsg/__main__.py @@ -68,15 +68,24 @@ def read_configuration_files(commandLineArguments): if commandLineArguments.configuration: dConfiguration = {} for sFileName in commandLineArguments.configuration: - tempConfiguration = open_configuration_file(sFileName, commandLineArguments) for sKey in tempConfiguration.keys(): if sKey == 'file_list': - try: - dConfiguration['file_list'].extend(tempConfiguration['file_list']) - except: - dConfiguration['file_list'] = tempConfiguration['file_list'] + if 'file_list' not in dConfiguration: + dConfiguration['file_list'] = [] + for iIndex, sFilename in enumerate(tempConfiguration['file_list']): + try: + for sGlobbedFilename in glob.glob(expand_filename(sFilename)): + dConfiguration['file_list'].append(sGlobbedFilename) + except TypeError: + sKey = list(sFilename.keys())[0] + for sGlobbedFilename in glob.glob(expand_filename(sKey)): + dTemp = {} + dTemp[sGlobbedFilename] = {} + dTemp[sGlobbedFilename].update(tempConfiguration['file_list'][iIndex][sKey]) + dConfiguration['file_list'].append(dTemp) + elif sKey == 'rule': for sRule in tempConfiguration[sKey]: try: @@ -119,15 +128,19 @@ def write_junit_xml_file(oJunitFile): def update_command_line_arguments(commandLineArguments, configuration): - if configuration: - if 'file_list' in configuration: - for sFilename in configuration['file_list']: - try: - commandLineArguments.filename.extend(glob.glob(expand_filename(sFilename))) - except: - commandLineArguments.filename = glob.glob(expand_filename(sFilename)) - if 'local_rules' in configuration: - commandLineArguments.local_rules = expand_filename(configuration['local_rules']) + if not configuration: + return + + if 'file_list' in configuration: + for sFilename in configuration['file_list']: + if isinstance(sFilename, dict): + sFilename = list(sFilename.keys())[0] + try: + commandLineArguments.filename.extend(glob.glob(expand_filename(sFilename))) + except: + commandLineArguments.filename = glob.glob(expand_filename(sFilename)) + if 'local_rules' in configuration: + commandLineArguments.local_rules = expand_filename(configuration['local_rules']) def expand_filename(sFileName): @@ -243,11 +256,17 @@ def main(): display_rule_configuration(commandLineArguments, configuration) - for sFileName in commandLineArguments.filename: + for iIndex, sFileName in enumerate(commandLineArguments.filename): oVhdlFile = vhdlFile.vhdlFile(read_vhdlfile(sFileName)) oVhdlFile.filename = sFileName oRules = rule_list.rule_list(oVhdlFile, commandLineArguments.local_rules) oRules.configure(configuration) + try: + oRules.configure(configuration['file_list'][iIndex][sFileName]) + except TypeError: + pass + except KeyError: + pass if commandLineArguments.fix: if commandLineArguments.backup: diff --git a/vsg/tests/vsg/read_configuration_files/__init__.py b/vsg/tests/vsg/read_configuration_files/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/vsg/tests/vsg/read_configuration_files/arch.vhd b/vsg/tests/vsg/read_configuration_files/arch.vhd new file mode 100644 index 00000000..e69de29b diff --git a/vsg/tests/vsg/read_configuration_files/arch_2.vhd b/vsg/tests/vsg/read_configuration_files/arch_2.vhd new file mode 100644 index 00000000..e69de29b diff --git a/vsg/tests/vsg/read_configuration_files/config_w_file_globbing.json b/vsg/tests/vsg/read_configuration_files/config_w_file_globbing.json new file mode 100644 index 00000000..429b7acd --- /dev/null +++ b/vsg/tests/vsg/read_configuration_files/config_w_file_globbing.json @@ -0,0 +1,5 @@ +{ + "file_list" : [ + "vsg/tests/vsg/read_configuration_files/*.vhd" + ] +} diff --git a/vsg/tests/vsg/read_configuration_files/config_w_file_list.json b/vsg/tests/vsg/read_configuration_files/config_w_file_list.json new file mode 100644 index 00000000..92564038 --- /dev/null +++ b/vsg/tests/vsg/read_configuration_files/config_w_file_list.json @@ -0,0 +1,7 @@ +{ + "file_list" : [ + "vsg/tests/vsg/read_configuration_files/entity.vhd", + "vsg/tests/vsg/read_configuration_files/arch.vhd", + "vsg/tests/vsg/read_configuration_files/package.vhd" + ] +} diff --git a/vsg/tests/vsg/read_configuration_files/config_w_file_list_globbing_w_individual_rule_config.json b/vsg/tests/vsg/read_configuration_files/config_w_file_list_globbing_w_individual_rule_config.json new file mode 100644 index 00000000..9cbf741b --- /dev/null +++ b/vsg/tests/vsg/read_configuration_files/config_w_file_list_globbing_w_individual_rule_config.json @@ -0,0 +1,19 @@ +{ + "file_list" : [ + "vsg/tests/vsg/read_configuration_files/entity.vhd", + "vsg/tests/vsg/read_configuration_files/arch*.vhd":{ + "rule":{ + "rule_001":{ + "disable": true + } + } + }, + "vsg/tests/vsg/read_configuration_files/package.vhd":{ + "rule":{ + "rule_002":{ + "disable": false + } + } + } + ] +} diff --git a/vsg/tests/vsg/read_configuration_files/config_w_file_list_w_individual_rule_config.json b/vsg/tests/vsg/read_configuration_files/config_w_file_list_w_individual_rule_config.json new file mode 100644 index 00000000..a8964f0f --- /dev/null +++ b/vsg/tests/vsg/read_configuration_files/config_w_file_list_w_individual_rule_config.json @@ -0,0 +1,13 @@ +{ + "file_list" : [ + "vsg/tests/vsg/read_configuration_files/entity.vhd", + "vsg/tests/vsg/read_configuration_files/arch.vhd":{ + "rule":{ + "rule_001":{ + "disable":True + } + } + }, + "vsg/tests/vsg/read_configuration_files/package.vhd" + ] +} diff --git a/vsg/tests/vsg/read_configuration_files/entity.vhd b/vsg/tests/vsg/read_configuration_files/entity.vhd new file mode 100644 index 00000000..e69de29b diff --git a/vsg/tests/vsg/read_configuration_files/entity_2.vhd b/vsg/tests/vsg/read_configuration_files/entity_2.vhd new file mode 100644 index 00000000..e69de29b diff --git a/vsg/tests/vsg/read_configuration_files/package.vhd b/vsg/tests/vsg/read_configuration_files/package.vhd new file mode 100644 index 00000000..e69de29b diff --git a/vsg/tests/vsg/read_configuration_files/package_2.vhd b/vsg/tests/vsg/read_configuration_files/package_2.vhd new file mode 100644 index 00000000..e69de29b diff --git a/vsg/tests/vsg/read_configuration_files/test_read_configuration_files_function.py b/vsg/tests/vsg/read_configuration_files/test_read_configuration_files_function.py new file mode 100644 index 00000000..34908c9c --- /dev/null +++ b/vsg/tests/vsg/read_configuration_files/test_read_configuration_files_function.py @@ -0,0 +1,159 @@ +import unittest +from unittest import mock +import subprocess +import os + +from vsg.tests import utils +from vsg.__main__ import read_configuration_files + +def get_index_of_dictionary_in_list(lList, sKey): + for iIndex, item in enumerate(lList): + if isinstance(item, dict): + sMyKey = list(item.keys())[0] + if sMyKey == sKey: + return iIndex + return None + + +class command_line_args(): + ''' This is used as an input into the read_configuration function.''' + def __init__(self, configuration=False): + self.configuration = configuration + + +class test_read_configuration_function(unittest.TestCase): + + def setUp(self): + if os.path.isfile('deleteme.json'): + os.remove('deleteme.json') + + def tearDown(self): + if os.path.isfile('deleteme.json'): + os.remove('deleteme.json') + + def test_file_list(self): + oCommandLineArgs = command_line_args(['vsg/tests/vsg/read_configuration_files/config_w_file_list.json']) + + dExpected = {} + dExpected['file_list'] = [] + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/arch.vhd') + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/entity.vhd') + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/package.vhd') + + dActual = read_configuration_files(oCommandLineArgs) + + dExpected['file_list'].sort() + dActual['file_list'].sort() + + self.assertDictEqual(dActual, dExpected) + + + def test_globbing_files(self): + oCommandLineArgs = command_line_args(['vsg/tests/vsg/read_configuration_files/config_w_file_globbing.json']) + + dExpected = {} + dExpected['file_list'] = [] + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/package.vhd') + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/entity_2.vhd') + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/arch_2.vhd') + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/arch.vhd') + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/package_2.vhd') + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/entity.vhd') + + dActual = read_configuration_files(oCommandLineArgs) + + dExpected['file_list'].sort() + dActual['file_list'].sort() + + self.assertDictEqual(dActual, dExpected) + + def test_file_list_with_individual_rule_config(self): + self.maxDiff = None + oCommandLineArgs = command_line_args(['vsg/tests/vsg/read_configuration_files/config_w_file_list_w_individual_rule_config.json']) + + dExpected = {} + dExpected['file_list'] = [] + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/entity.vhd') + dFile = {} + dFile['vsg/tests/vsg/read_configuration_files/arch.vhd'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch.vhd']['rule'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch.vhd']['rule']['rule_001'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch.vhd']['rule']['rule_001']['disable'] = True + dExpected['file_list'].append(dFile) + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/package.vhd') + + dActual = read_configuration_files(oCommandLineArgs) + + lExpected = [] + for item in dExpected['file_list']: + if not isinstance(item, dict): + lExpected.append(item) + lExpected.sort() + + lActual = [] + for item in dActual['file_list']: + if not isinstance(item, dict): + lActual.append(item) + lActual.sort() + + self.assertEqual(lActual, lExpected) + + for iIndex, item in enumerate(dExpected['file_list']): + if isinstance(item, dict): + sKey = list(item.keys())[0] + iActualIndex = get_index_of_dictionary_in_list(dActual['file_list'], sKey) + self.assertEqual(dActual['file_list'][iActualIndex], dExpected['file_list'][iIndex]) + + + def test_file_list_globbing_with_individual_rule_config(self): + self.maxDiff = None + oCommandLineArgs = command_line_args(['vsg/tests/vsg/read_configuration_files/config_w_file_list_globbing_w_individual_rule_config.json']) + + dExpected = {} + dExpected['file_list'] = [] + + dFile = {} + dFile['vsg/tests/vsg/read_configuration_files/arch_2.vhd'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch_2.vhd']['rule'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch_2.vhd']['rule']['rule_001'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch_2.vhd']['rule']['rule_001']['disable'] = True + dExpected['file_list'].append(dFile) + + dFile = {} + dFile['vsg/tests/vsg/read_configuration_files/arch.vhd'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch.vhd']['rule'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch.vhd']['rule']['rule_001'] = {} + dFile['vsg/tests/vsg/read_configuration_files/arch.vhd']['rule']['rule_001']['disable'] = True + dExpected['file_list'].append(dFile) + + dFile = {} + dFile['vsg/tests/vsg/read_configuration_files/package.vhd'] = {} + dFile['vsg/tests/vsg/read_configuration_files/package.vhd']['rule'] = {} + dFile['vsg/tests/vsg/read_configuration_files/package.vhd']['rule']['rule_002'] = {} + dFile['vsg/tests/vsg/read_configuration_files/package.vhd']['rule']['rule_002']['disable'] = False + dExpected['file_list'].append(dFile) + + dExpected['file_list'].append('vsg/tests/vsg/read_configuration_files/entity.vhd') + + dActual = read_configuration_files(oCommandLineArgs) + + lExpected = [] + for item in dExpected['file_list']: + if not isinstance(item, dict): + lExpected.append(item) + lExpected.sort() + + lActual = [] + for item in dActual['file_list']: + if not isinstance(item, dict): + lActual.append(item) + lActual.sort() + + self.assertEqual(lActual, lExpected) + + for iIndex, item in enumerate(dExpected['file_list']): + if isinstance(item, dict): + sKey = list(item.keys())[0] + iActualIndex = get_index_of_dictionary_in_list(dActual['file_list'], sKey) + self.assertEqual(dActual['file_list'][iActualIndex], dExpected['file_list'][iIndex]) +