Filter SeverityMatchFilter
decides
audit events according to the severity
level of the event.
name | description | type | default value |
---|---|---|---|
severity | the severity level of this filter | Severity | error |
acceptOnMatch |
If acceptOnMatch is true , then
the filter accepts an audit event if and only if there is
a match between the event's severity level and property
severity. If acceptOnMatch
is false , then the filter
accepts an audit event if and only if there is not a match
between the event's severity level and property severity.
|
Boolean | true |
For example, the following configuration fragment directs the
Checker to not report audit events with severity
level info
:
com.puppycrawl.tools.checkstyle.filters
Filter SuppressionCommentFilter
uses
pairs of comments to suppress audit events.
Rationale: Sometimes there are legitimate reasons for violating a check. When this is a matter of the code in question and not personal preference, the best place to override the policy is in the code itself. Semi-structured comments can be associated with the check. This is sometimes superior to a separate suppressions file, which must be kept up-to-date as the source file is edited.
Usage: This filter only works in conjunction with a FileContentsHolder
, since that check makes
the suppression comments in the Java files available. A configuration that includes this filter must
configure FileContentsHolder
as a
child module of TreeWalker
. Note that the suppression comment should be put
before the violation. You can use more than one suppression comment each on separate line.
name | description | type | default value |
---|---|---|---|
offCommentFormat | comment pattern to trigger filter to begin suppression | Regular Expression | "CHECKSTYLE:OFF" |
onCommentFormat | comment pattern to trigger filter to end suppression | Regular Expression | "CHECKSTYLE:ON" |
checkFormat | check pattern to suppress | Regular Expression | ".*" |
messageFormat | message pattern to suppress | Regular Expression | null |
checkCPP | whether to check C++ style comments (// ) |
Boolean | true |
checkC | whether to check C style comments (/* ... */ ) |
Boolean | true |
offCommentFormat and onCommentFormat must have equal paren counts.
Make sure that comments are available to the filter by enabling FileContentsHolder:
To configure a filter to suppress audit events between a comment
containing CHECKSTYLE:OFF
and a comment containing
CHECKSTYLE:ON
:
To configure a filter to suppress audit events between a comment
containing line BEGIN GENERATED CODE
and a comment
containing line END GENERATED CODE
:
To configure a filter so that // stop constant
check
and // resume constant check
marks
legitimate constant names:
To configure a filter so that UNUSED OFF:
var
and UNUSED ON: var
marks a
variable or parameter known not to be used by the code by
matching the variable name in the message:
To configure a filter so that name of suppressed check mentioned
in comment CSOFF: regexp
and CSN: regexp
mark a matching check:
To configure a filter to suppress all audit events between a comment
containing CHECKSTYLE_OFF: ALMOST_ALL
and a comment containing
CHECKSTYLE_OFF: ALMOST_ALL
except for the EqualsHashCode check:
To configure a filter to suppress Check's violation message which matches
specified message in messageFormat (so suppression will be not only by
Check's name, but by message text additionally, as the same Check could report
different by message format violations) between a comment
containing stop
and comment containing resume
:
Code before filter above is applied with Check's audit events:
Code after filter is applied:
It is possible to specify an ID of checks, so that it can be leveraged by the
SuppressionCommentFilter to skip validations. The following examples show how to skip
validations near code that is surrounded with // CSOFF <ID> (reason)
and // CSON <ID>
, where ID is the ID of checks you want to suppress.
Examples of Checkstyle checks configuration:
Example of SuppressionCommentFilter configuration (checkFormat which is set to '$1' points that ID of the checks is in the first group of offCommentFormat and onCommentFormat regular expressions):
Example of how to configure the check to suppress more than one checks.
com.puppycrawl.tools.checkstyle.filters
Filter SuppressionFilter
rejects
audit events for Check errors according to
a suppressions XML
document in a file. If there is no configured
suppressions file or the optional is set to true and
suppressions file was not found the Filter accepts all audit events.
name | description | type | default value |
---|---|---|---|
file |
the location of the suppressions XML document file.
The order the location is checked is:
|
string | none |
optional | Tells what to do when the file is not existing. If optional is set to false the file must exist, or else it ends with error. On the other hand if optional is true and file is not found, the filter accept all audit events. | Boolean | false |
For example, the following configuration fragment directs the
Checker to use a SuppressionFilter
with suppressions
file config/suppressions.xml
:
A suppressions XML
document contains a set
of suppress
elements, where
each suppress
element can have the
following attributes:
files
-
a Regular Expression
matched against the file name associated with an audit
event. It is mandatory.
checks
-
a Regular Expression
matched against the name of the check associated with an audit
event. Optional if id
is specified.
id
-
a string
matched against the ID of the check associated with an audit
event. Optional if checks
is specified.
lines
- a comma-separated list of
values, where each value is
an integer or a
range of integers denoted by integer-integer. It is optional.
columns
- a comma-separated list of
values, where each value is
an integer or a
range of integers denoted by integer-integer. It is optional.
Each audit event is checked against
each suppress
element. It is
suppressed if all specified attributes match against the audit
event.
You can download template of empty suppression filter here.
The following suppressions XML document directs
a SuppressionFilter
to
reject JavadocStyleCheck
errors for
lines 82 and 108 to 122 of
file AbstractComplexityCheck.java
,
and MagicNumberCheck
errors for line
221 of file JavadocStyleCheck.java
:
As another example to suppress Check by module id:
Then the following can be used to suppress only the first
check and not the second by using
the id
attribute:
Suppress checks for hidden files and folders:
Suppress checks for Maven-generated code:
Suppress checks for archives, classes and other binary files:
Suppress checks for image files:
Suppress checks for non-java files:
Suppress all checks in generated sources:
Suppress FileLength check on integration tests in certain folder:
com.puppycrawl.tools.checkstyle.filters
Filter SuppressWarningsFilter
uses annotations to
suppress audit events.
Rationale: Same as for
SuppressionCommentFilter
. In the contrary to it
here, comments are not used comments but the builtin syntax of
@SuppressWarnings
. This can be perceived as a
more elegant solution than using comments. Also this approach
maybe supported by various IDE.
Usage: This filter only works in conjunction with a
SuppressWarningsHolder, since that check finds
the annotations in the Java files and makes them available for
the filter. Because of that, a configuration that includes
this filter must also include
SuppressWarningsHolder
as a child module of the
TreeWalker
. Name of check in annotation is case-insensitive
and should be written with any dotted prefix or "Check" suffix removed.
To configure the check that makes tha annotations available to the filter.
To configure filter to suppress audit events for annotations add:
It is possible to specify an ID of checks, so that it can be leveraged by the
SuppressWarningsFilter to skip validations. The following examples show how to skip
validations near code that has @SuppressWarnings("checkstyle:<ID>")
or
just @SuppressWarnings("<ID>")
annotation, where ID is the ID of checks
you want to suppress.
Example of Checkstyle check configuration:
To make the annotations available to the filter.
To configure filter to suppress audit events for annotations add:
com.puppycrawl.tools.checkstyle.filters
Filter SuppressWithNearbyCommentFilter
uses
individual comments to suppress audit events.
Rationale: Same as SuppressionCommentFilter
.
Whereas the SuppressionCommentFilter uses matched pairs of
filters to turn on/off comment matching,
SuppressWithNearbyCommentFilter
uses
single comments. This requires fewer lines to mark a region, and
may be aesthetically preferable in some contexts.
Usage: This filter only works in conjunction with a FileContentsHolder
, since that check makes
the suppression comments in the Java files available. A configuration that includes this filter must
configure FileContentsHolder
as a
child module of TreeWalker
.
name | description | type | default value |
---|---|---|---|
commentFormat | comment pattern to trigger filter to begin suppression | Regular Expression | "SUPPRESS CHECKSTYLE (\w+)" |
checkFormat | check pattern to suppress | Regular Expression | ".*" |
messageFormat | message pattern to suppress | Regular Expression | null |
influenceFormat | a negative/zero/positive value that defines the number of lines preceding/at/following the suppression comment | Regular Expression | "0" |
checkCPP | whether to check C++ style comments (// ) |
Boolean | true |
checkC | whether to check C style comments (/* ... */ ) |
Boolean | true |
To configure the check that makes comments available to the filter:
To configure a filter to suppress audit events for check
on any line with a comment SUPPRESS CHECKSTYLE check
:
To configure a filter to suppress all audit events on any line
containing the comment CHECKSTYLE IGNORE THIS LINE
:
To configure a filter so that
// OK to catch (Throwable|Exception|RuntimeException) here
permits the current and previous line to avoid generating an IllegalCatch
audit event:
To configure a filter so that CHECKSTYLE IGNORE check FOR NEXT var LINES
avoids triggering any audits for the given check for the current line and the next var lines
(for a total of var+1 lines):
To configure a filter to avoid any audits on code like:
To configure a filter to allow suppress one or more Checks(separated by "|") and demand comment no less than 14 symbols:
It is possible to specify an ID of checks, so that it can be leveraged by the
SuppressWithNearbyCommentFilter to skip validations. The following examples
show how to skip validations near code that has comment like
// @cs-: <ID/> (reason)
, where ID is the ID of checks you want to
suppress.
Examples of Checkstyle checks configuration:
Example of SuppressWithNearbyCommentFilter configuration (checkFormat which is set to '$1' points that ID of the checks is in the first group of commentFormat regular expressions):
Example of how to configure the check to suppress more than one checks. The influence format format is specified in the second regexp group.
com.puppycrawl.tools.checkstyle.filters