529 lines
18 KiB
ReStructuredText
529 lines
18 KiB
ReStructuredText
Localizing
|
|
==========
|
|
.. WARNING:: This information is out of date with the release of 3.0.0
|
|
.. WARNING:: This information is out of date with the release of 3.0.0
|
|
.. NOTE:: If you have local rules defined in a version prior to 3.0.0, create an issue and I can work with you to convert it to 3.0.0 format.
|
|
|
|
VSG supports customization to your coding style standards by allowing localized rules.
|
|
These rules are stored in a directory with an __init__.py file and one or more python files.
|
|
The files should follow the same structure and naming convention as the rules found in the vsg/rules directory.
|
|
|
|
The localized rules will be used when the **--local_rules** command line argument is given or using the **local_rules** option in a configuration file.
|
|
|
|
Example: Create rule to check for entity and architectures in the same file.
|
|
----------------------------------------------------------------------------
|
|
|
|
Let's suppose in our organization the entity and architecture should be split into separate files.
|
|
This rule is not in the base rule set, but we can add it through localization.
|
|
For this example, we will be setting up the localized rules in your home directory.
|
|
|
|
Prepare local rules directory
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Create an empty directory with an empty __init__.py file
|
|
|
|
.. code-block:: bash
|
|
|
|
$ mkdir ~/local_rules
|
|
$ touch ~/local_rules/__init__.py
|
|
|
|
Create new rule file
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
We will create a new rule by extending the base rule class.
|
|
|
|
.. NOTE::
|
|
The file name and class name must start with **rule_**.
|
|
Otherwise VSG will not recognize it as a rule.
|
|
|
|
The rule will be in the **localized** group.
|
|
Since this is the first rule, we will number it **001**.
|
|
|
|
.. code-block:: python
|
|
|
|
from vsg import rule
|
|
|
|
|
|
class rule_001(rule.rule):
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'localized'
|
|
|
|
Referencing the :doc:`phases`, we decide it should be in phase 1: structural.
|
|
|
|
.. code-block:: python
|
|
|
|
from vsg import rule
|
|
|
|
|
|
class rule_001(rule.rule):
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'localized'
|
|
self.phase = 1
|
|
|
|
Now we need to add the **analyze** method to perform the check.
|
|
|
|
.. code-block:: python
|
|
|
|
from vsg import rule
|
|
|
|
|
|
class rule_001(rule.rule):
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'localized'
|
|
self.phase = 1
|
|
|
|
def analyze(self, oFile):
|
|
|
|
The built in variables in the vsg.line class can be used to build rules.
|
|
In this case, the vsg.vhdlFile class has two attributes (**hasEntity** and **hasArchitecture**) that are exactly what we need.
|
|
We are ready to write the body of the **analyze** method:
|
|
|
|
.. code-block:: python
|
|
|
|
from vsg import rule
|
|
|
|
|
|
class rule_001(rule.rule):
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'localized'
|
|
self.phase = 1
|
|
|
|
def analyze(self, oFile):
|
|
if oFile.hasEntity and oFile.hasArchitecture:
|
|
self.add_violation(utils.create_violation_dict(1))
|
|
|
|
The base rule class has an **add_violation** method which takes a dictionary as an argument.
|
|
The *create_violation_dict* function will create the dictionary.
|
|
This dictionary can be modified to include other information about the violation.
|
|
This method appends the dictionary to a violation list, which is processed later for reporting and fixing purposes.
|
|
In this case, any line number will do so we picked 1.
|
|
|
|
We must decide if we want to give VSG the ability to fix this rule on its own.
|
|
If so, then we will need to write the **_fix_violations** method.
|
|
However, for this violation we want the user to split the file.
|
|
We will tell VSG the rule is not fixable.
|
|
|
|
.. code-block:: python
|
|
|
|
from vsg import rule
|
|
|
|
|
|
class rule_001(rule.rule):
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'localized'
|
|
self.phase = 1
|
|
self.fixable = False # User must split the file
|
|
|
|
def analyze(self, oFile):
|
|
if oFile.hasEntity and oFile.hasArchitecture:
|
|
self.add_violation(utils.create_violation_dict(1))
|
|
|
|
We also need to provide a solution to the user so they will know how to fix the violation:
|
|
|
|
.. code-block:: python
|
|
|
|
from vsg import rule
|
|
|
|
|
|
class rule_001(rule.rule):
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'localized'
|
|
self.phase = 1
|
|
|
|
|
|
self.fixable = False # User must split the file
|
|
self.solution = 'Split entity and architecture into separate files.'
|
|
|
|
def analyze(self, oFile):
|
|
if oFile.hasEntity and oFile.hasArchitecture:
|
|
self.add_violation(utils.create_violation_dict(1))
|
|
|
|
Finally, we need to add a code tag check so the rule can be disabled via comments in the code:
|
|
|
|
.. code-block:: python
|
|
|
|
from vsg import rule
|
|
|
|
|
|
class rule_001(rule.rule):
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'localized'
|
|
self.phase = 1
|
|
self.fixable = False # User must split the file
|
|
self.solution = 'Split entity and architecture into separate files.'
|
|
|
|
def analyze(self, oFile):
|
|
if not self.is_vsg_off(oLine):
|
|
if oFile.hasEntity and oFile.hasArchitecture:
|
|
self.add_violation(utils.create_violation_dict(1))
|
|
|
|
The rule is complete, so we save it as rule_localized_001.py.
|
|
Performing an **ls** on our local_rules directory:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ ls ~/local_rules
|
|
__init__.py rule_localized_001.py
|
|
|
|
Use new rule to analyze
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When we want to run with localized rules, use the **--local_rules** option.
|
|
|
|
.. code-block:: bash
|
|
|
|
$ vsg -f RAM.vhd --local_rules ~/local_rules
|
|
File: RAM.vhd
|
|
==============
|
|
Phase 1... Reporting
|
|
localized_001 | 1 | Split entity and architecture into separate files.
|
|
Phase 2... Not executed
|
|
Phase 3... Not executed
|
|
Phase 4... Not executed
|
|
Phase 5... Not executed
|
|
Phase 6... Not executed
|
|
Phase 7... Not executed
|
|
==============
|
|
Total Rules Checked: 50
|
|
Total Failures: 1
|
|
|
|
Our new rule will now flag files which have both an entity and an architecture in the same file.
|
|
That was a fairly simple rule.
|
|
To write more complex rules, it is important to understand how the rule class works.
|
|
|
|
Understanding the Rule class
|
|
----------------------------
|
|
|
|
Every rule uses the base rule class.
|
|
There are a few methods to the base rule class, but we are interested in only the following:
|
|
|
|
+-----------------+-------------------------------------------+
|
|
| Method | Description |
|
|
+-----------------+-------------------------------------------+
|
|
| add_violations | Adds violations to a list. |
|
|
+-----------------+-------------------------------------------+
|
|
| analyze | Calls _pre_analyze and then _analyze. |
|
|
+-----------------+-------------------------------------------+
|
|
| _analyze | Code that performs the analysis. |
|
|
+-----------------+-------------------------------------------+
|
|
| fix | calls analyze and then _fix_violations. |
|
|
+-----------------+-------------------------------------------+
|
|
| _fix_violations | Code that fixes the violations. |
|
|
+-----------------+-------------------------------------------+
|
|
| _get_solution | Prints out the solution to stdout. |
|
|
+-----------------+-------------------------------------------+
|
|
| _pre_analyze | Code that sets up variables for _analyze. |
|
|
+-----------------+-------------------------------------------+
|
|
|
|
We will look at the rule **constant_014** to illustrate how VSG uses the methods above:
|
|
|
|
.. code-block:: python
|
|
|
|
class rule_014(rule.rule):
|
|
'''
|
|
Constant rule 014 checks the indent of multiline constants that are not arrays.
|
|
'''
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'constant'
|
|
self.identifier = '014'
|
|
self.solution = 'Align with := keyword on constant declaration line.'
|
|
self.phase = 5
|
|
|
|
def _pre_analyze(self):
|
|
self.alignmentColumn = 0
|
|
self.fKeywordFound = False
|
|
|
|
def _analyze(self, oFile, oLine, iLineNumber):
|
|
if not oLine.isConstantArray and oLine.insideConstant:
|
|
if oLine.isConstant and ':=' in oLine.line:
|
|
self.alignmentColumn = oLine.line.index(':=') + len(':= ')
|
|
self.fKeywordFound = True
|
|
elif not oLine.isConstant and self.fKeywordFound:
|
|
sMatch = ' ' * self.alignmentColumn
|
|
if not re.match('^' + sMatch + '\w', oLine.line):
|
|
self.add_violation(utils.create_violation_dict(LineNumber))
|
|
self.dFix['violations'][iLineNumber] = self.alignmentColumn
|
|
if oLine.isConstantEnd:
|
|
self.fKeywordFound = False
|
|
|
|
def _fix_violations(self, oFile):
|
|
for iLineNumber in self.violations:
|
|
sLine = oFile.lines[iLineNumber].line
|
|
sNewLine = ' ' * self.dFix['violations'][iLineNumber] + sLine.strip()
|
|
oFile.lines[iLineNumber].update_line(sNewLine)
|
|
|
|
Creating Class
|
|
~~~~~~~~~~~~~~
|
|
|
|
First we create the rule by inheriting from the base rule class.
|
|
We also add a comment to describe what the rule is doing.
|
|
|
|
.. code-block:: python
|
|
|
|
class rule_014(rule.rule):
|
|
'''
|
|
Constant rule 014 checks the indent of multiline constants that are not arrays.
|
|
'''
|
|
|
|
Adding __init__
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Then we add the **__init__** method.
|
|
It calls the init of the base rule class, then we modify attributes for this specific rule:
|
|
|
|
.. code-block:: python
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.name = 'constant'
|
|
self.identifier = '014'
|
|
self.solution = 'Align with := keyword on constant declaration line.'
|
|
self.phase = 5
|
|
|
|
For this rule we set its *name*, *identifier*, *solution*, and *phase*.
|
|
|
|
Analyzing Considerations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The **analyze** method of the base rule class will first call **_pre_anaylze** before **_analyze**.
|
|
The **_analyze** method is wrapped in a loop that increments through each line of the file.
|
|
The **analyze** method also checks if the rule has been turned off for a line, via code tags.
|
|
If the code tag indicates to ignore the line, then it will be skipped.
|
|
If you decide to override the **analyze** method, then you should add the code tag check.
|
|
|
|
Adding _pre_analyze method
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
In this rule, we use the **_pre_analyze** method to initialize some variables.
|
|
These variables must be set outside the loop that is present in the **analyze** method.
|
|
|
|
.. code-block:: python
|
|
|
|
def _pre_analyze(self):
|
|
self.alignmentColumn = 0
|
|
self.fKeywordFound = False
|
|
|
|
Adding _analyze method
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The **_analyze** method is called on every line of the VHDL file.
|
|
Any memory needed between lines must be declared in the **_pre_analyze** method.
|
|
In the following code, notice *self.alignmentColumn* and *self.fKeywordFound*.
|
|
|
|
.. code-block:: python
|
|
|
|
def _analyze(self, oFile, oLine, iLineNumber):
|
|
if not oLine.isConstantArray and oLine.insideConstant:
|
|
if oLine.isConstant and ':=' in oLine.line:
|
|
self.alignmentColumn = oLine.line.index(':=') + len(':= ')
|
|
self.fKeywordFound = True
|
|
elif not oLine.isConstant and self.fKeywordFound:
|
|
sMatch = ' ' * self.alignmentColumn
|
|
if not re.match('^' + sMatch + '\w', oLine.line):
|
|
self.add_violation(utils.create_violation_dict(LineNumber))
|
|
self.dFix['violations'][iLineNumber] = self.alignmentColumn
|
|
if oLine.isConstantEnd:
|
|
self.fKeywordFound = False
|
|
|
|
This code is searching for the characteristics of a non-array constant.
|
|
|
|
.. code-block:: python
|
|
|
|
def _analyze(self, oFile, oLine, iLineNumber):
|
|
if not oLine.isConstantArray and oLine.insideConstant:
|
|
|
|
Once the non-array constant is found, it notes the column of the *:=* keyword.
|
|
|
|
.. code-block:: python
|
|
|
|
if oLine.isConstant and ':=' in oLine.line:
|
|
self.alignmentColumn = oLine.line.index(':=') + len(':= ')
|
|
self.fKeywordFound = True
|
|
|
|
On successive lines of the constant declaration, it checks to see if there are enough spaces from the beginning of the line to match the column number the *:=* is located at.
|
|
|
|
.. code-block:: python
|
|
|
|
elif not oLine.isConstant and self.fKeywordFound:
|
|
|
|
If there are not enough spaces, then a violation is added.
|
|
We also store off the required column into a predefined dictionary named *dFix*.
|
|
This will be used later when the **fix** method is called.
|
|
|
|
.. code-block:: python
|
|
|
|
sMatch = ' ' * self.alignmentColumn
|
|
if not re.match('^' + sMatch + '\w', oLine.line):
|
|
self.add_violation(utils.create_violation_dict(LineNumber))
|
|
self.dFix['violations'][iLineNumber] = self.alignmentColumn
|
|
|
|
When we detect the end of the constant declaration, we clear a flag and prepare for the next constant declaration.
|
|
|
|
.. code-block:: python
|
|
|
|
if oLine.isConstantEnd:
|
|
self.fKeywordFound = False
|
|
|
|
Fixing considerations
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The **fix** method will first call the **analyze** method and then the **_fix_violations** method.
|
|
Unlike the **analyze** method, it does not wrap the **_fix_violations** in a loop.
|
|
This is due to some fixes needing to execute either top down or bottom up.
|
|
Rules that add or delete lines need to work from the bottom up.
|
|
Otherwise, the violations detected by the **analyze** method will have moved.
|
|
|
|
Adding the _fix_violations method
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
In this rule, we are going to iterate on all the violations in the *self.violations* attribute.
|
|
|
|
.. code-block:: python
|
|
|
|
def _fix_violations(self, oFile):
|
|
for iLineNumber in self.violations:
|
|
|
|
We store the current line off to make it easier to read.
|
|
Then we strip the line of all leading and trailing spaces and prepend the number of spaces required to align with the *:=* keyword.
|
|
|
|
.. code-block:: python
|
|
|
|
sLine = oFile.lines[iLineNumber].line
|
|
sNewLine = ' ' * self.dFix['violations'][iLineNumber] + sLine.strip()
|
|
|
|
Finally, we update the line with our modified line using the **update_line** method.
|
|
|
|
.. code-block:: python
|
|
|
|
oFile.lines[iLineNumber].update_line(sNewLine)
|
|
|
|
Violation dictionary
|
|
--------------------
|
|
|
|
Violations are stored as a list of dictionaries in the **rule.violations** attribute.
|
|
This is the generic format of the dictionary represented by json:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"lines" : [
|
|
{
|
|
"number" : "<integer>",
|
|
"<line_attribute>" : "<line_value>",
|
|
"<line_attribute>" : "<line_value>"
|
|
}
|
|
],
|
|
"<violation_attribute>" : "<violation_value>",
|
|
"<violation_attribute>" : "<violation_value>"
|
|
}
|
|
|
|
This format gives us the greatest flexibility in describing violations.
|
|
The lines[0]['number'] is the only required element in a violation dictionary.
|
|
The "<line_attribute>" and "<violation_attribute>" elements are optional.
|
|
They are used by more complex rules to maintain information used to fix violations.
|
|
|
|
Single line violations
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Most violations are against a single line and no other information is required to fix it.
|
|
These dictionaries use the minimal form.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"lines" : [
|
|
{
|
|
"number" : 40
|
|
}
|
|
]
|
|
}
|
|
|
|
Single line violations with additional information
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If additional information for single line violations is required, it will be stored at the **violation** level.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"lines" : [
|
|
{
|
|
"number" : 40
|
|
}
|
|
],
|
|
"label" : "FIFO"
|
|
}
|
|
|
|
This violation is indicating there is an issue at line 40 with the label "FIFO".
|
|
The "label" element will be used to fix the violation.
|
|
|
|
Multiple line violations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
If a rule covers multiple lines, then information about individual lines can be stored:
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"lines" : [
|
|
{
|
|
"number" : 40,
|
|
"column" : 20
|
|
},
|
|
{
|
|
"number" : 41,
|
|
"column" : 35
|
|
}
|
|
],
|
|
"desired_column" : 15
|
|
}
|
|
|
|
In the above case, we are trying to align a keyword over multiple lines.
|
|
Each line which is not aligned is reported in the **lines** list.
|
|
The **column** attribute indicates which column the keyword was found.
|
|
The **desired_column**, which applies to all lines in the **lines** list, indicates which column the keyword should be located.
|
|
|
|
This violation would cover a group of multiple lines.
|
|
If there were violations in multiple groups, then each group with get its own violation dictionary.
|
|
|
|
utils functions
|
|
~~~~~~~~~~~~~~~
|
|
|
|
There are three functions in the utils module to help with managing the violation dictionary: **create_violation_dict**, **get_violation_line_number** and **get_violating_line**.
|
|
The **create_violation_dict** will return a dictionary in the form of the single line violation described above.
|
|
Use this to create the initial violation and add to it as necessary.
|
|
|
|
The **get_violation_line_number** will return the lines['number'] attribute of the violation.
|
|
Use this function to abstract away the line number from the underlying data structure.
|
|
|
|
The **get_violating_line** will return a line object at the line the violation occurred.
|
|
This is easier than manually indexing into the oFile list to pull out a line.
|
|
|
|
Rule creation guidelines
|
|
------------------------
|
|
|
|
Keep these points in mind when creating new rules:
|
|
|
|
#. Use an existing rule as a starting point
|
|
#. Remember that **analyze** calls **_pre_analyze** and then **_analyze**
|
|
#. Override **_get_solution** to return complex messages
|
|
#. **analyze** method can be overridden if necessary
|
|
#. If overriding **analyze**, then include a check for *vsg_off*
|