Merge pull request #357 from jeremiah-c-leary/issue-344

Merging in solution to Issue 344
This commit is contained in:
Jeremiah Leary 2020-03-21 11:08:03 -05:00 committed by GitHub
commit a3c28f1807
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
14 changed files with 293 additions and 24 deletions

View File

@ -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][<identifier>]**
* **[file_list][<filename>][rule][<identifier>]**.
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
--------------------------

View File

@ -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:

View File

@ -0,0 +1,5 @@
{
"file_list" : [
"vsg/tests/vsg/read_configuration_files/*.vhd"
]
}

View File

@ -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"
]
}

View File

@ -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
}
}
}
]
}

View File

@ -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"
]
}

View File

@ -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])