Class SuppressWithPlainTextCommentFilter
- All Implemented Interfaces:
Configurable
,Contextualizable
,Filter
Filter SuppressWithPlainTextCommentFilter
uses plain text to suppress
audit events. The filter can be used only to suppress audit events received
from the checks which implement FileSetCheck interface. In other words, the
checks which have Checker as a parent module. The filter knows nothing about
AST, it treats only plain text comments and extracts the information required
for suppression from the plain text comments. Currently the filter supports
only single line comments.
Please, be aware of the fact that, it is not recommended to use the filter for Java code anymore, however you still are able to use it to suppress audit events received from the checks which implement FileSetCheck interface.
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.
Note that the suppression comment should be put before the violation. You can use more than one suppression comment each on separate line.
Properties offCommentFormat
and onCommentFormat
must have equal
paren counts.
SuppressionWithPlainTextCommentFilter can suppress Checks that have Treewalker or Checker as parent module.
-
Property
offCommentFormat
- Specify comment pattern to trigger filter to begin suppression. Type isjava.util.regex.Pattern
. Default value is"// CHECKSTYLE:OFF"
. -
Property
onCommentFormat
- Specify comment pattern to trigger filter to end suppression. Type isjava.util.regex.Pattern
. Default value is"// CHECKSTYLE:ON"
. -
Property
checkFormat
- Specify check pattern to suppress. Type isjava.lang.String
. Default value is".*"
. -
Property
messageFormat
- Specify message pattern to suppress. Type isjava.lang.String
. Default value isnull
. -
Property
idFormat
- Specify check ID pattern to suppress. Type isjava.lang.String
. Default value isnull
.
To configure a filter to suppress audit events between a comment containing
CHECKSTYLE:OFF
and a comment containing CHECKSTYLE:ON
:
<module name="Checker"> ... <module name="SuppressWithPlainTextCommentFilter"/> ... </module>
To configure a filter to suppress audit events between a comment containing
line BEGIN GENERATED CONTENT
and a comment containing line
END GENERATED CONTENT
(Checker is configured to check only properties files):
<module name="Checker"> <property name="fileExtensions" value="properties"/> <module name="SuppressWithPlainTextCommentFilter"> <property name="offCommentFormat" value="BEGIN GENERATED CONTENT"/> <property name="onCommentFormat" value="END GENERATED CONTENT"/> </module> </module>
//BEGIN GENERATED CONTENT my.property=value1 // No violation events will be reported my.property=value2 // No violation events will be reported //END GENERATED CONTENT . . .
To configure a filter so that -- stop tab check
and -- resume tab check
marks allowed tab positions (Checker is configured to check only sql files):
<module name="Checker"> <property name="fileExtensions" value="sql"/> <module name="SuppressWithPlainTextCommentFilter"> <property name="offCommentFormat" value="stop tab check"/> <property name="onCommentFormat" value="resume tab check"/> <property name="checkFormat" value="FileTabCharacterCheck"/> </module> </module>
-- stop tab check SELECT * FROM users // won't warn here if there is a tab character on line -- resume tab check SELECT 1 // will warn here if there is a tab character on line
To configure a filter so that name of suppressed check mentioned in comment
CSOFF: <i>regexp</i>
and CSON: <i>regexp</i>
mark a matching
check (Checker is configured to check only xml files):
<module name="Checker"> <property name="fileExtensions" value="xml"/> <module name="SuppressWithPlainTextCommentFilter"> <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/> <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/> <property name="checkFormat" value="$1"/> </module> </module>
// CSOFF: RegexpSinglelineCheck // RegexpSingleline check won't warn any lines below here if the line matches regexp <condition property="checkstyle.ant.skip"> <isset property="checkstyle.ant.skip"/> </condition> // CSON: RegexpSinglelineCheck // RegexpSingleline check will warn below here if the line matches regexp <property name="checkstyle.pattern.todo" value="NOTHingWillMatCH_-"/>
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 (Checker is configured to check only java files):
<module name="Checker"> <property name="fileExtensions" value="java"/> <module name="SuppressWithPlainTextCommentFilter"> <property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/> <property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/> <property name="checkFormat" value="^((?!(FileTabCharacterCheck)).)*$"/> </module> </module>
// CHECKSTYLE_OFF: ALMOST_ALL public static final int array []; private String [] strArray; // CHECKSTYLE_ON: ALMOST_ALL private int array1 [];
To configure a filter to suppress Check's violation message which matches
specified message in messageFormat(so suppression will not be only by
Check's name, but also by message text, as the same Check can report violations
with different message format) between a comment containing stop
and
comment containing resume
:
<module name="Checker"> <module name="SuppressWithPlainTextCommentFilter"> <property name="offCommentFormat" value="stop"/> <property name="onCommentFormat" value="resume"/> <property name="checkFormat" value="FileTabCharacterCheck"/> <property name="messageFormat" value="^File contains tab characters (this is the first instance)\.$"/> </module> </module>
It is possible to specify an ID of checks, so that it can be leveraged by the
SuppressWithPlainTextCommentFilter 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:
<module name="RegexpSinglelineJava"> <property name="id" value="count"/> <property name="format" value="^.*COUNT(*).*$"/> <property name="message" value="Don't use COUNT(*), use COUNT(1) instead."/> </module> <module name="RegexpSinglelineJava"> <property name="id" value="join"/> <property name="format" value="^.*JOIN\s.+\s(ON|USING)$"/> <property name="message" value="Don't use JOIN, use sub-select instead."/> </module>
Example of SuppressWithPlainTextCommentFilter configuration (checkFormat which is set to '$1' points that ID of the checks is in the first group of offCommentFormat and onCommentFormat regular expressions):
<module name="Checker"> <property name="fileExtensions" value="sql"/> <module name="SuppressWithPlainTextCommentFilter"> <property name="offCommentFormat" value="CSOFF (\w+) \(\w+\)"/> <property name="onCommentFormat" value="CSON (\w+)"/> <property name="idFormat" value="$1"/> </module> </module>
-- CSOFF join (it is ok to use join here for performance reasons) SELECT name, job_name FROM users AS u JOIN jobs AS j ON u.job_id = j.id -- CSON join -- CSOFF count (test query execution plan) EXPLAIN SELECT COUNT(*) FROM restaurants -- CSON count
Example of how to configure the check to suppress more than one check (Checker is configured to check only sql files).
<module name="Checker"> <property name="fileExtensions" value="sql"/> <module name="SuppressWithPlainTextCommentFilter"> <property name="offCommentFormat" value="@cs-\: ([\w\|]+)"/> <property name="checkFormat" value="$1"/> </module> </module>
-- @cs-: RegexpSinglelineCheck -- @cs-: FileTabCharacterCheck CREATE TABLE STATION ( ID INTEGER PRIMARY KEY, CITY CHAR(20), STATE CHAR(2), LAT_N REAL, LONG_W REAL);
Parent is com.puppycrawl.tools.checkstyle.Checker
- Since:
- 8.6
-
Nested Class Summary
Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
AutomaticBean.OutputStreamOptions
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionboolean
accept
(AuditEvent event) Determines whether or not a filtered AuditEvent is accepted.protected void
Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.final void
setCheckFormat
(String format) Setter to specify check pattern to suppress.final void
setIdFormat
(String format) Setter to specify check ID pattern to suppress.final void
setMessageFormat
(String format) Setter to specify message pattern to suppress.final void
setOffCommentFormat
(Pattern pattern) Setter to specify comment pattern to trigger filter to begin suppression.final void
setOnCommentFormat
(Pattern pattern) Setter to specify comment pattern to trigger filter to end suppression.Methods inherited from class com.puppycrawl.tools.checkstyle.api.AutomaticBean
configure, contextualize, getConfiguration, setupChild
-
Constructor Details
-
SuppressWithPlainTextCommentFilter
public SuppressWithPlainTextCommentFilter()
-
-
Method Details
-
setOffCommentFormat
Setter to specify comment pattern to trigger filter to begin suppression.- Parameters:
pattern
- off comment format pattern.
-
setOnCommentFormat
Setter to specify comment pattern to trigger filter to end suppression.- Parameters:
pattern
- on comment format pattern.
-
setCheckFormat
Setter to specify check pattern to suppress.- Parameters:
format
- pattern for check format.
-
setMessageFormat
Setter to specify message pattern to suppress.- Parameters:
format
- pattern for message format.
-
setIdFormat
Setter to specify check ID pattern to suppress.- Parameters:
format
- pattern for check ID format
-
accept
Description copied from interface:Filter
Determines whether or not a filtered AuditEvent is accepted. -
finishLocalSetup
protected void finishLocalSetup()Description copied from class:AutomaticBean
Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.The default implementation does nothing.
- Specified by:
finishLocalSetup
in classAutomaticBean
-