# Syntax Rules for Declarative Hints

Use to identify common syntax errors or problems in source code. A hint displays in the Java Source Editor as a result of code inspection that the IDE automatically runs on the sources in focus.

The syntax rules for declarative hints tell the IDE what kind of code structures to look for and how to transform them.

A rule format for a declarative hint is as follows:

       <source-pattern> :: <conditions>
    => <target-pattern> :: <conditions>
    => <target-pattern> :: <conditions>
    ;;

Thus, the hint:

       $1 == null
    => null == $1
    ;;

updates the following code:

       if (a == null) {
       System.err.println("a is null");
       }

to

       if (null == a) {
       System.err.println("a is null");
       }

This topic introduces the following components of a rule:

- Sources
- Conditions
- Targets
- Options

Sources

The source pattern in a declaration can be either a Java expression, statements, class, variable, or method.

All references to classes in the source pattern must be resolvable: either fully qualified names or the custom import section must be used. For example,

    <?
        import java.util.LinkedList;
        import java.util.ArrayList;
    ?>

       new LinkedList()
    => new ArrayList()
    ;;

       LinkedList $0;
    => ArrayList $0;
    ;;

Identifiers starting with the dollar sign (`$`) represent variables (for example, `java.util.Arrays.asList($param)`). In the source pattern, first occurrences of a variable are bound to an actual subtree that exists in the code. Second and following occurrences of the variable in the actual subtree are verified against the subtree that is bound to the variable. A source pattern occurs in the text only if the actual subtree matches the subtree that is bound to the variable.

Identifiers starting and ending with the dollar sign (`$`) consume any number of tree nodes (for example, `java.util.Arrays.asList($params$)`).

Conditions

Both source and target patterns can specify additional conditions for a hint. Conditions must follow the: sign according to the syntax rules.

Conditions have the following limitations:

    $1.isDirectory() :: $1 instanceof java.io.File
    => !$1.isFile()
    ;;

Some condition examples are given here:

- using a new variant of a deprecated method

      $component.show($v) :: $component instanceof java.awt.Component && $v instanceof boolean
      => $component.setVisible($v)
      ;;

- adding a default parameter value

      $component.show() :: $component instanceof java.awt.Component
      => $component.setVisible(true)
      ;;

- changing the method invocation chain to get correct results

      $file.toURL() :: $file instanceof java.io.File
      => $file.toURI().toURL()
      ;;

Targets

The syntax of a target pattern is similar to the syntax of a source pattern.

Special form: `empty == remove`

Use the following variable types in both source and target patterns

Variable Types | Description
--- | ---
`$[a-zA-Z0-9_]+` | Any expression
`$[a-zA-Z0-9_]+;` | Any statement
`$[a-zA-Z0-9_]+$` | Any number of subtrees (except statements)
`$[a-zA-Z0-9_]+$;` | Any number of statements
`$_` | For patterns undefined and for target patterns and conditions that are automatically bound to the current matched region
`$$[a-zA-Z0-9_]+` | Reserved, do not use

Options

Options allow for modifying and fine-tuning the behavior of a hint. The error or warning options allow specifying errors or warnings that are shown in the refactoring UI as appropriate. Suppress warnings allow addition of `@SuppressWarnings` keys.

Examples of options are given here:

- An error option: `<!error="message">`

      remove-from-parent

  Code | Result
  --- | ---
  `int i;` `=> /*remove-from-parent*/` `;;` | Removes the int `i;` variable declaration from the surrounding block
  `float f;` `=> <!error="err">` `;;` | Shows an error to the user when used from the Inspect and Transform dialog box. Does not remove the float `f;` variable declaration from the surrounding block
  `double d;` `=> <!error="err",remove-from-parent=true>` `;;` | Shows an error to the user (in the Inspect and Transform dialog box) and removes the `"double d;"` variable declaration from the surrounding block

- A suppress warnings option: `<!suppress-warnings=xxx>"`

         $1.isDirectory
              :: $1 instanceof java.io.File
      ;;

Note: Before you start writing your own declarative hint, check that it does not exist yet in the complete list of hints available in the IDE at the Java Hints wiki page at `
` .

Related Topics

Developing Applications with NetBeans IDE,

Copyright © 2016, Oracle and/or its affiliates. All rights reserved.