When you create a rule, your goal is to graphically express the pattern that you do not want to appear in your code. When Parasoft static analysis checks a rule, it searches for instances where the specified pattern occurs and flags them as violations.
You can create a rule graphically or automatically (using the Auto-Create feature). The Auto-Create feature can only be used with certain dictionaries.
In this section:
Creating a Rule Graphically
Start by defining the rule that you want to create and enforce or the pattern you want to find. Use plain English, e.g., "Begin class names with an uppercase letter" or “No images should be wider than 550 pixels.” When you've defined what the rule should do, user RuleWizard to create it.
Create the Parent Rule Node
- Choose File> New> Rule and choose the appropriate dictionary from the Dictionary drop-down menu.
- Choose the By Node option in the Rule Creation options.
- Choose the node that is the subject of your rule.
- For a description of a certain node, right-click the node, and choose View Documentation from the shortcut menu that opens.
- If you can’t find the node you want, right-click inside the white space and choose Find from the shortcut menu that opens.
- Click OK. A rule node will appear in the right GUI panel.
Add Additional Qualifications to Your Node
Right-click any of your rule's nodes and choose a command from the shortcut menu. All available options for the chosen node will be displayed in the shortcut menu that opens. Any options that are not programming elements or concepts are explained in the Commands chapter.
Depending on the command that you choose, RuleWizard will add a rule element, modify a rule element, or open a dialog box that lets you add or modify a rule element.
If you want to continue adding to and modifying the rule, you can do so by right-clicking any rule node or rule element, then choosing one of the available commands.
Continue adding qualifications until the node fully expresses your rule.
Determine the Error Message Displayed
Specify the message that appears when this rule is violated or this pattern is found.
Right-click a rule node and choose an option from the Create Output shortcut menu.
The placement of the output arrow when right-clicking determines what line number is used for the output message
If you want the line number of node C included in the output message, place the output arrow on node C.
The default output option is Display. This will send the output to the static analysis results or report. The Method option can be used to invoke a method that you enter or specify. For information on this option, see Using Scripts to Customize Rules.
- Enter a brief explanation of the violation when prompted.
- Click OK and an output arrow will be added to your rule.
The rule is complete once it:
- Expresses the pattern that you want to search for, and
- Contains an output arrow and message, and
- Contains a header and Rule ID.
You must at least enter a rule header and rule ID, which along with the rule description, are the rule's properties (see Customizing Rule Properties). You can save and enable the rule after you customizing the rule's properties so that it can be run with your tool's static analysis functionality.
Creating a Rule Automatically
Start by finding or writing a snippet of code that expresses the pattern you want identified as a rule violation.
Create the Parent Rule Node
- Choose File> New> Rule and choose the appropriate dictionary from the Dictionary drop-down menu.
- Choose the Auto-Create option in the Rule Creation options.
- In the Sample Code area, enter the code/pattern you want identified as a violation and click OK.
Modify the Rule as Needed (Optional)
- To change the output type, right-click the automatically-added output arrow, then choose Output> [desired option] from the shortcut menu. The default output option is Display. This will send the output to the static analysis results or report. The Method option can be used to invoke a method that you enter or specify. For information on this option, see Using Scripts to Customize Rules.
- Right-click the automatically-added output arrow and choose Modify from the shortcut menu
- Enter a brief explanation of the violation when prompted.
The rule is complete once it:
- Expresses the pattern that you want to search for, and
- Contains an output arrow and message, and
- Contains a header and Rule ID.
You must at least enter a rule header and rule ID, which along with the rule description, are the rule's properties (see Customizing Rule Properties). You can save and enable the rule after you customizing the rule's properties so that it can be run with your tool's static analysis functionality.
Searching for Nodes
- Right-click inside the white space of a dictionary tree and choose Find from the shortcut menu.
- Type the name of the node you want inside the dialog that opens. RuleWizard will search through the nodes and highlight the node that matches what you type.
- Click Next to go to the next node that matches the text you typed. Click Clear to clear the field. Click Select to keep that node highlighted as you continue your search.
Additional Rule Creation Notes
Consider the following information as you create rules.
General
- Rule file names may not be more than 30 characters long.
- The status bar in the rule creation interface provides information about creating a valid rule. The icon on the right-hand side of the status bar, as well as the color of the rule nodes, tells you whether or not your rule is valid. The messages in the Message panel tell you how to address issues that prevent a rule from being.
- Include at least one output arrow in each rule. If a rule does not have an output arrow, static analysis will not report an error if this pattern is found in the code under test. To include an output arrow, right-click a rule node (the placement of the output arrow determines what line number is used for the output message; to have the line number of node C included in the output message, place the output arrow on node C) and choose Create Output from the shortcut menu.
- To display an output message in results or reports when the rule is violated (the pattern is found), choose Create Output> Display. You can implement a script to customize an output action by choosing Create Output> Method. For information on using scripting, see Using Scripts to Customize Rules.
- To undo an action, right-click the empty portion of the workspace and choose Undo.
- Enter a header when you customize a rule's properties (see Customizing Rule Properties); rules without headers are not valid.
- Any dictionary element (such as bool Constant) or folder of elements elements (Constants) can be used as a rule node.
- To view a description of a node, right-click the node that you want more information about and choose View Documentation from the shortcut menu.
- You can use scripting within rule definitions to produce highly specialized rules. For information on using scripting, see Using Scripts to Customize Rules.
- The order of elements in your rule is important. If your rule has more than one child node, you can move the child up or down one position by right-clicking the vertical line common to all children and choosing Move up one or Move down one from the shortcut menu.
- Information about a rule will be included in RuleWizard’s Rule Documentation files. To view this documentation, click the View RuleDocs tool bar button. To update this documentation, click the Update RuleDocs tool bar button.
Expressions and Regular Expressions
Use expressions to match number values and regular expressions to match strings of text. For guidelines on using expressions and regular expressions, see Expressions and Regular Expressions.
Rule Conditions
- See Working with Node Sets to create a rule with a pattern that involves a union, intersection, or difference of multiple nodes.
- You can create a rule condition that restricts the number of times a specific element can appear in a block (such as a file or a class) by creating a collector to track the number of instances of that pattern and using Count to specify the number of instances that constitutes a violation. See Working with Node Sets for information on determining how counts are calculated.
- Use Context to create a rule condition about the code element that contains the parent node.
- Use Condition to create a rule condition about the parent node’s condition statement (if, else, init, increment, for, with, while, switch, and do while).
- Use Body to create a rule condition about the code element that is a subnode of the parent node .
- You can indicate whether nodes are analyzed recursively when Parasoft tools search for the rule condition by using the Indirect Check and Direct Check commands (see RuleWizard Commands). Indirect Check is the default setting. To use a Direct Check, right-click the node whose checking type you want to change and choose Direct Check from the shortcut menu.
- To use scripting in a rule condition, use the Create Method command (see RuleWizard Commands). For information on using scripting, see Using Scripts to Customize Rules.
