Skip to content

Home

Jump to bottom
Clément Fournier edited this page Jul 23, 2019 · 18 revisions

Welcome to the pmd-designer wiki!

The rule designer

The rule designer is both a way to inspect the tree on which PMD rules run on, and to write XPath rules in an integrated manner. This page describes the features that enable this.

AST inspection

designer_top

You can enter source code in the middle zone.

  • Make sure to select the correct language and version for your source code:
    • Language is set app-wide with the blue button in the menu-bar
    • If the language has several language versions, you can select a specific one with the choicebox just above the code area
  • If the source is valid using this setting, the tree to the right will update to display the AST of the code
  • When selecting a node, the left panel updates with information about a node

Selecting nodes

There are several ways to focus a node for inspection:

  • From the tree view: just click on an item
    • Since 6.16.0, the tree view is also searchable: press CTRL+F when it's focused, or click on the Search 🔎 button and enter a search query. You can cycle through results with CTRL+TAB or CTRL+F3, and cycle back with CTRL+SHIFT+TAB or CTRL+SHIFT+F3
  • From the crumb bar: the crumb bar below the code area shows the ancestors of the currently selected node, and is empty if you have no selection:

Ancestor crumb bar example

  • From the source code: maintain CTRL for a second until the code area becomes mostly blue. Then, each node you hover over on the code area will be selected automatically. Example:

Ctrl-hover selection example

Node inspection

The left panel displays the following information:

  • XPath attributes: this basically are all the attributes available in XPath queries. Those attributes are wrappers around a Java getter, so you can obtain documentation on the relevant Javadoc (that's not yet integrated into the designer)
  • Metrics: for nodes that support it, the values of metrics are displayed in this panel
  • Scopes: This is java specific and displays some representation of the symbol table. You mostly don't need it. If you select eg a variable id, its usages are already highlighted automatically without opening the panel:

Usages highlight example

XPath rule design

The bottom part of the UI is dedicated to designing XPath rules:

Bottom UI

The center is an XPath expression. As you type it, the matched nodes are updated on the right, and highlighted on the code area. Autocompletion is available on some languages.

Note: you can keep several rules in the editor (there's a tab for each of them).

Testing rules

The left panel contains test cases for your rule. Usage of this feature is described on this other page

Rule properties

Above the XPath expression area, the "Properties" button allows you to define new properties for your prototype rule. You can also edit the existing properties.

When you click on it, a small popup appears:

Property definition popup

The popup contains in the center a list of currently defined properties, displaying their name and expected type.

  • Adding: the "Add property" button adds a row to the table
  • Deleting: each item has a "Trash" button to delete the property
  • Editing: each property can be further edited by clicking on the "Ellipsis" button on the right

Editing properties

The edition menu of a property looks like the following:

Property edition popup

  • You can edit the name, description, expected type, and default value of the property
  • All this information is exported with the rule definition (see Exporting to an XML rule)
  • The default value is used unless you're editing a test case, and you set a custom value for the test case. TODO link

Exporting to an XML rule

The little export icon next to the gear icon opens a menu to export your rule. This menu lets you fill-in the metadata necessary for an XPath rule to be included in a ruleset.

Export example

Other stuff

  • Available languages: the pmd-ui jar doesn't include any PMD language module, but picks up on the language modules that are on its the classpath of its VM.
    • You also need a compatible pmd-core. For now, newer designer (eg 6.15.0) support pmd-core + languages as old as version 6.11.0. This will be clarified in the app someday.
  • Main class: The main class of the app is net.sourceforge.pmd.util.fxdesigner.DesignerStarter, and not the Designer class in the same package.
  • Settings management: application state is for now saved in a file somewhere in a sub directory of your user home directory. You can verify exactly where by opening the menu About > About. The format of this file is not public API and is subject to change between minor versions of the designer, until we may figure out a more flexible persistence scheme.
Clone this wiki locally