Rule group json syntax?

[urbite]

A customer's project requires all VHDL keywords to be capitalized. I've had to replace my SHFT keyswitch 3 times 😁

The following in the docs regarding setting case for all keywords seems to point to the solution.
https://vhdl-style-guide.readthedocs.io/en/latest/configuring_rule_groups.html

rule:
  group:
     case::keyword:
       case: 'lower'
     case::label:
       case: 'upper'
     case::name:
       case: 'upper'
     length:
       disable: True
     naming:
       disable: True

As a json neophyte, I didn't see how to handle the rule group :: syntax in the json file.

Initially I'd like to use vsg to just uppercase all the keywords. I found an example on how to disable all rules, then attempted to add the rule group to just uppercase the keywords. Here's the resulting json file, vsg_keyworks_us.json that was created.

{       
  "rule":{
    "global":{
      "disable": true
    },
    "group":{
      "case": {
        "keyword" : {
          "case": 'upper'
        }
      }
    },
  }
}

Here's the command used to apply the rules to the target vhdl file, along with the results. Examining the file shows that no keywords were changed to uppercase.

vsg -c vsg_keywrd_uc.json --fix -f foo_vsg.vhd

File:  foo_vsg.vhd
================================================================================
Phase 7 of 7... Reporting
Total Rules Checked: 0
Total Violations:    0
  Error   :     0
  Warning :     0

Any suggestions or help is appreciated.

[urbite]

Modified the json file and also tried a yaml file (as the rule group example is in yaml).

Neither configuration reported and violations, so subsequently no changes to the vhdl file.

modified json rule file

{       
  "rule":{
    "global":{
      "disable": true
    },
    "group":{
      "case::keyword": {
        "case": 'upper'
      }
    },
  }
}

yaml rule file

rule:
  global:
    disable: True
  group:
     case::keyword:
       case: 'upper'

[urbite]

I wondered if after globally disabling everything, the keyword group needed to be enabled.

rule:
  global:
    disable: True
  group:
     case::keyword:
       disable: False
       case: 'upper'

After setting 'disable' false, most of the keywords were capitalized. Some of the keywords that weren't capitalized (but were expected to be) included:

• parameter class (signal, variable, constant) and direction (in, out, inout) in procedure parameter lists. Didn't have any functions, but assume the same would apply. Note that declarations local to the procedure (constant, variable) were capitlized.
• wait statements (wait on, wait for, wait until)
• conditional exit from loop (exit when)
• the 'in' keyword in for loops. FOR , LOOP, TO, DOWNTO are capitalized
• null statement
• others in case statement
• others in element mapping (e.g. foo <= (0 => '1', others => '0')

The vhdl code that was used had an empty entity (no port list) and no component prototypes. So it's not certain if the direction parameters in port lists are capitalized with the group setting.

[JHertz5]

I'm going to track the progress of these tasks here

Token	Issue	PR Raised
parameter class (signal, variable, constant) in function and procedure parameter lists	#1263	✅
direction (in, out, inout) in function and procedure parameter lists	#1252	✅
wait statements (wait on, wait for, wait until)	#1261	✅
conditional exit from loop (exit when)	#1269	✅
'in' keyword in for loops	#1273	✅
null statement	#1271	✅
others in case statement	#1277	✅
others in element mapping (e.g. foo <= (0 => '1', others => '0')	#1279	✅

[urbite]

@JHertz5 Really awesome work and quick turnaround! 👏

I'm an on again/off again python learner. I'll have a look at your PR's to hopefully gain enough understanding to make some contributions in the future.

Looks like these PRs are just awaiting acceptance to be merged. Will I receive notification when they've been accepted?

[JHertz5]

@urbite No problem. If you are interested in contributing, a great place to start is to find a rule that is similar to what you are trying to achieve, but maybe for a different token, and use that as a template for your changes. The repo owner has done a great job of making it very easy to create new rules.

Yes, the PRs will need to be reviewed, merged and integrated into a release by the repo owner. This may take a while due to the volume of changes, so don't expect the updates to be available on an officiaal release very soon. In the meantime, you are welcome to clone my fork of the repository and check that the branches behave as you'd expect. If you're subscribed to the PRs, as I mentioned elsewhere, you'll receive notifications when they are updated/merged.

[JHertz5]

PRs have now been raised for all of the issues described.

[JHertz5]

Hi @urbite.

I wondered if after globally disabling everything, the keyword group needed to be enabled.

As you've discovered, after disabling all rules, you need to enable the rules that you want to check; otherwise, no rules will be checked.

To answer your original question, you need to use case::keyword, in the same way that you have done in the YAML.
The JSON below will set all rules in the case::keyword group to use uppercase.

{
  "rule":{
    "group":{
      "case::keyword" : {
          "case": "upper"
        }
    }
  }
}

Some of the keywords that weren't capitalized (but were expected to be) included:

Thanks for doing this check and putting this list together. I've raised an issue already and am working on a PR to get case rules in place for parameter directions in procedures and functions. For the others, feel free to raise issues. I recommend raising separate issues for different keywords to make the work easier to manage. If you don't raise the issues, I'll work through your list and raise issues as I go.

The vhdl code that was used had an empty entity (no port list) and no component prototypes. So it's not certain if the direction parameters in port lists are capitalized with the group setting.

I can confirm that port directions have a case rule:
VHDL input:

ENTITY FIFO IS
  PORT (
    clk : in    STD_LOGIC;
    sig : out   STD_LOGIC;
    dat : inout STD_LOGIC
  );
END ENTITY FIFO;

Config:

{
  "rule":{
    "group":{
      "case::keyword" : {
          "case": "upper"
        }
    }
  }
}

Output

$ bin/vsg -f test.vhd -c test.json
================================================================================
File:  test.vhd
================================================================================
Phase 6 of 7... Reporting
Total Rules Checked: 766
Total Violations:    3
  Error   :     3
  Warning :     0
----------------------------+------------+------------+--------------------------------------
  Rule                      |  severity  |  line(s)   | Solution
----------------------------+------------+------------+--------------------------------------
  port_019                  | Error      |          3 | Change "in" to "IN"
  port_019                  | Error      |          4 | Change "out" to "OUT"
  port_019                  | Error      |          5 | Change "inout" to "INOUT"
----------------------------+------------+------------+--------------------------------------
NOTE: Refer to online documentation at https://vhdl-style-guide.readthedocs.io/en/latest/index.html for more information.

[urbite]

hi @JHertz5 - thanks for the clarification on the correct JSON.

I'm a total newbie - this is my first attempt to configure vsg. Is there any capability in vsg to apply regex's to vhdl file content that isn't comments?

If so, then a quick hack workaround for the keywords that aren't capitalized might be to:

1. find the non-capitalized keywords in non-comment areas
2. replace with uppercase

Not sure if the vsg regex flavor can handle this. Nor do I know the syntax for converting the case of a backreference (would be more googling for me).

Not sure when I'll be able to submit PRs for the missing keywords. I'm down the rabbit hole thus far in investigating this. 😄 So, you may beat me to it - and if so it will be much appreciated. If you do submit PRs, what can I do to get notifications of PR activity?

[JHertz5]

@urbite no problem!

Is there any capability in vsg to apply regex's to vhdl file content that isn't comments?

Unfortunately, this is not a feature that the tool offers AFAIK. However, you may be able to get this done fairly easily if you use a text editor that support regex and you have your list of keywords that you want to change.
The following regex matches non-VHDL comment lines that include the keyword others, and captures everything prior the others keyword:

^(( *(?!--).)*)others

Then you can use replace $1OTHERS to replace the lowercase others with uppercase. This works for me in VS code and I've tested it on this code

architecture rtl of test is

begin

  -- I wish every instance of others was uppercase.
  my_signal_others <= (bit_0 => '1', others => '0'); -- Inline comment others

end architecture rtl;

The regex ignores the instances of "others" in comments and only replaces the keyword. I hope that helps!

Not sure when I'll be able to submit PRs for the missing keywords

No problem, I'll make a start on raising issues and they'll be added to the list of things to do. I'll try to raise PRs that address the issues when I have some time, but it may take a couple fo weeks to work through the list. Fortunately, keyname case rules are usually very simple, so most of them shouldn't be a lot of work. 🤞

If you do submit PRs, what can I do to get notifications of PR activity?

For issues and PRs, you can click this buttonn to get notifications when that issue/PR is updated. I can try to tag you when I raise issues, but I might not always remember.

[jeremiah-c-leary]

Morning @urbite and @JHertz5,

I just saw this discussion and thought I should jump in.

@urbite there is a page of documentation which lists all the keyword case rules.

As you have realized there is a rule for each keyword and not all of them have been implemented. I really appreciate @JHertz5 , creating the rules for to catch the ones you have identified. I'm wondering if we could maybe grep for all the keywords in vsg/tokens and then check if they are covered by a case test. Not sure how difficult that would be.

I will prioritize checking the PRs @JHertz5 has implemented.

Thanks again.

--Jeremy

[JHertz5]

Thanks @jeremiah-c-leary. It's a good idea to take a more structured approach. Grepping the keywords is easy enough; I've come up with a list of 263 keywords
keywords.txt
On the master branch, there are currently 139 case::keyword rules, so it appears that there is some way to go! I'll see if I can find some time to go through and cut the list of keywords down to those that need case rules.