SuppressWithNearbyTextFilter

Since Checkstyle 10.10.0

Description

Filter SuppressWithNearbyTextFilter uses plain text to suppress nearby audit events. The filter can suppress all checks which have Checker as a parent module.

Notes

Setting .* value to nearbyTextPattern property will see any text as a suppression and will likely suppress all audit events in the file. It is best to set this to a key phrase not commonly used in the file to help denote it out of the rest of the file as a suppression. See the default value as an example.

Properties

name description type default value since
checkPattern Specify check name pattern to suppress. Property can also be a RegExp group index at nearbyTextPattern in format of $x and be picked from line that matches nearbyTextPattern. Pattern ".*" 10.10.0
idPattern Specify check ID pattern to suppress. Pattern null 10.10.0
lineRange Specify negative/zero/positive value that defines the number of lines preceding/at/following the suppressing nearby text. Property can also be a RegExp group index at nearbyTextPattern in format of $x and be picked from line that matches nearbyTextPattern. String "0" 10.10.0
messagePattern Specify check violation message pattern to suppress. Pattern null 10.10.0
nearbyTextPattern Specify nearby text pattern to trigger filter to begin suppression. Pattern "SUPPRESS CHECKSTYLE (\w+)" 10.10.0

Examples

To configure the filter to suppress audit events on the same line: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter"/>
  <module name="TreeWalker">
    <module name="MagicNumber"/>
  </module>
</module>

Example: 

int hoursInDay = 24; // SUPPRESS CHECKSTYLE because it is too obvious
int daysInWeek = 7; // violation

To configure the filter to suppress audit events on any line that contains DO NOT CHECK THIS LINE: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter">
    <property name="nearbyTextPattern" value="DO NOT CHECK THIS LINE"/>
  </module>
  <module name="TreeWalker">
    <module name="MagicNumber"/>
  </module>
</module>

Example: 

int a = 42; // DO NOT CHECK THIS LINE
int b = 43; // violation

To configure the filter to suppress audit events whose check message contains the word Line. In this case, LineLengthCheck's violation message contains it: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter">
    <property name="messagePattern" value=".*Line.*"/>
    <property name="nearbyTextPattern" value=".*"/>
  </module>
  <module name="LineLength">
    <property name="max" value="10"/>
  </module>
</module>

Example: 

export FOO=BAR # ok, because violation message is matching suppress pattern

To configure the filter to suppress audit events only on a check whose id is ignoreMe: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter">
    <property name="idPattern" value="ignoreMe"/>
  </module>
  <module name="LineLength">
    <property name="max" value="55"/>
  </module>
  <module name="TreeWalker">
    <module name="MagicNumber">
      <property name="id" value="ignoreMe"/>
    </module>
  </module>
</module>

Example: 

int a = 42; // SUPPRESS CHECKSTYLE because i want to
static final int LONG_VAR_NAME_TO_TAKE_MORE_THAN_55_CHARS = 22; // LineLength violation

To configure the filter to suppress audit events for the current and next 2 lines: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter">
    <property name="lineRange" value="2"/>
  </module>
  <module name="UniqueProperties"/>
</module>

Example: 

key.one=41 # SUPPRESS CHECKSTYLE because I want to
key.one=42 # ok
key.one=43 # ok
key.one=44 # violation

To configure the filter to suppress audit events for the current and previous line: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter">
    <property name="lineRange" value="-1"/>
  </module>
  <module name="UniqueProperties"/>
</module>

Example: 

key.one=41 # violation
key.one=42 # ok
key.one=43 # SUPPRESS CHECKSTYLE because I want to
key.one=44 # violation

To configure the filter with a more compact nearbyTextPattern to accept variable checkPattern: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter">
    <property name="nearbyTextPattern"
      value="-@cs\[(\w+)\] (\w+)"/>
    <property name="checkPattern" value="$1"/>
  </module>
  <module name="TreeWalker">
    <module name="MagicNumber"/>
  </module>
</module>

Example: 

int a = 42; // -@cs[MagicNumber] We do not consider this number as magic for some reason.
int b = 43; // violation

To configure the filter to accept variable checkPattern and lineRange: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter">
    <property name="nearbyTextPattern"
      value="@cs-: (\w+) for ([+-]\d+) lines"/>
    <property name="checkPattern" value="$1"/>
    <property name="lineRange" value="$2"/>
  </module>
  <module name="TreeWalker">
    <module name="MagicNumber"/>
  </module>
</module>

Example: 

int a = 42; // @cs-: MagicNumber for +3 lines
int b = 43;
int c = 44;
int d = 45;
int e = 46; // violation

To configure the filter to suppress LineLength violations for lines containing a URL: 

<module name="Checker">
  <module name="SuppressWithNearbyTextFilter">
    <property name="checkPattern" value="LineLength"/>
    <property name="nearbyTextPattern"
      value="&lt;a href=&quot;[^&quot;]+&quot;&gt;"/>
  </module>
  <module name="LineLength">
    <property name="max" value="90"/>
  </module>
</module>

Example: 

/**
* Flag description.
*
* Disabled until <a href="www.github.com/owner/repo/issue/9#comment"> // ok
*/
public static final boolean SOME_FLAG = false;

Example of Usage

Package

com.puppycrawl.tools.checkstyle.filters

Parent Module

Checker