Class SuppressionCommentFilter
- java.lang.Object
-
- com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
-
- com.puppycrawl.tools.checkstyle.filters.SuppressionCommentFilter
-
- All Implemented Interfaces:
Configurable
,Contextualizable
,TreeWalkerFilter
public class SuppressionCommentFilter extends AbstractAutomaticBean implements TreeWalkerFilter
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.
Note that the suppression comment should be put before the violation. You can use more than one suppression comment each on separate line.
Attention: This filter may only be specified within the TreeWalker module (
<module name="TreeWalker"/>
) and only applies to checks which are also defined within this module. To filter non-TreeWalker checks likeRegexpSingleline
, a SuppressWithPlainTextCommentFilter or similar filter must be used.offCommentFormat
andonCommentFormat
must have equal paren counts.SuppressionCommentFilter can suppress Checks that have Treewalker 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.util.regex.Pattern
. Default value is".*"
. -
Property
messageFormat
- Specify message pattern to suppress. Type isjava.util.regex.Pattern
. Default value isnull
. -
Property
idFormat
- Specify check ID pattern to suppress. Type isjava.util.regex.Pattern
. Default value isnull
. -
Property
checkCPP
- Control whether to check C++ style comments (//
). Type isboolean
. Default value istrue
. -
Property
checkC
- Control whether to check C style comments (/* ... */
). Type isboolean
. Default value istrue
.
To configure a filter to suppress audit events (MemberNameCheck, ConstantNameCheck and IllegalCatchCheck have been taken here for reference) between a comment containing
CHECKSTYLE:OFF
and a comment containingCHECKSTYLE:ON
:<module name="SuppressionCommentFilter"/> <module name="MemberName"/> <module name="ConstantName"/> <module name="IllegalCatch"/>
class InputSuppressionCommentFilter { int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$' //CHECKSTYLE:OFF int VAR2; // suppressed violation //CHECKSTYLE:ON public static final int var3; // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //CHECKSTYLE:OFF public static final int var4; // suppressed violation //CHECKSTYLE:ON public void method1() { try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed //CHECKSTYLE:OFF try {} catch(Exception ex) {} // suppressed violation catch(Error err) {} // suppressed violation //CHECKSTYLE:ON } }
To configure a filter so that
// stop constant check
and// resume constant check
marks legitimate constant names:<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="stop constant check"/> <property name="onCommentFormat" value="resume constant check"/> <property name="checkFormat" value="ConstantNameCheck"/> </module> <module name="MemberName"/> <module name="ConstantName"/> <module name="IllegalCatch"/>
class InputSuppressionCommentFilter { int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$' //stop constant check int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$' //resume constant check public static final int var3; // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //stop constant check public static final int var4; // suppressed violation //resume constant check public void method1() { try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed //stop constant check try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed catch(Error err) {} // violation , Catching 'Error' is not allowed //resume constant check } }
To configure a filter so that
UNUSED OFF: <i>var</i>
andUNUSED ON: <i>var</i>
marks a variable or parameter known not to be used by the code by matching the variable name in the message through a specified message in messageFormat:<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="ILLEGAL OFF\: (\w+)"/> <property name="onCommentFormat" value="ILLEGAL ON\: (\w+)"/> <property name="checkFormat" value="IllegalCatch"/> <property name="messageFormat" value="^Catching '$1' is not allowed.$"/> </module> <module name="MemberName"/> <module name="ConstantName"/> <module name="IllegalCatch"/>
class InputSuppressionCommentFilter { int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$' //ILLEGAL OFF: Exception int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$' //ILLEGAL ON: Exception public static final int var3; // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //ILLEGAL OFF: Exception public static final int var4; // violation above , Name 'var4' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //ILLEGAL ON: Exception public void method1() { try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed //ILLEGAL OFF: Exception try {} catch(Exception ex) {} // suppressed violation catch(Error err) {} // violation , Catching 'Error' is not allowed //ILLEGAL ON: Exception } }
To configure a filter so that name of suppressed check mentioned in comment
CSOFF: <i>regexp</i>
andCSON: <i>regexp</i>
mark a matching check:<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/> <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/> <property name="checkFormat" value="$1"/> </module> <module name="MemberName"/> <module name="ConstantName"/> <module name="IllegalCatch"/>
class InputSuppressionCommentFilter { int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$' //CSOFF: MemberName int VAR2; // suppressed violation //CSON: MemberName public static final int var3; // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //CSOFF: ConstantName public static final int var4; // suppressed violation //CSON: ConstantName public void method1() { try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed //CSOFF: IllegalCatch try {} catch(Exception ex) {} // suppressed violation catch(Error err) {} // suppressed violation //CSON: IllegalCatch } }
To configure a filter to suppress all audit events between a comment containing
CHECKSTYLE_OFF: ALMOST_ALL
and a comment containingCHECKSTYLE_OFF: ALMOST_ALL
except for the ConstantName check:<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/> <property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/> <property name="checkFormat" value="^((?!(ConstantName)).)*$"/> </module> <module name="MemberName"/> <module name="ConstantName"/> <module name="IllegalCatch"/>
class InputSuppressionCommentFilter { int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$' //CHECKSTYLE_OFF: ALMOST_ALL int VAR2; // suppressed violation //CHECKSTYLE_ON: ALMOST_ALL public static final int var3; // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //CHECKSTYLE_OFF: ALMOST_ALL public static final int var4; // violation above , Name 'var4' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //CHECKSTYLE_ON: ALMOST_ALL public void method1() { try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed //CHECKSTYLE_OFF: ALMOST_ALL try {} catch(Exception ex) {} // suppressed violation catch(Error err) {} // suppressed violation //CHECKSTYLE_ON: ALMOST_ALL } }
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>
and// CSON <ID>
, where ID is the ID of checks you want to suppress. In the config of SuppressionCommentFilter, checkFormat is set to '$1' which points to the ID written in the offCommentFormat and onCommentFormat. Config for such a case is written below:<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="CSOFF (\w+)"/> <property name="onCommentFormat" value="CSON (\w+)"/> <property name="idFormat" value="$1"/> </module> <module name="MemberName"> <property name="id" value="MemberID"/> </module> <module name="ConstantName"> <property name="id" value="ConstantID"/> </module> <module name="IllegalCatch"> <property name="id" value="IllegalID"/> </module>
class InputSuppressionCommentFilter { int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$' //CSOFF MemberID int VAR2; // suppressed violation //CSON: MemberID public static final int var3; // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //CSOFF ConstantID public static final int var4; // suppressed violation //CSON ConstantID public void method1() { try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed //CSOFF IllegalID try {} catch(Exception ex) {} // suppressed violation catch(Error err) {} // suppressed violation //CSON IllegalID } }
Example of how to configure the check to suppress checks by name defined in comment.
<module name="SuppressionCommentFilter"> <property name="offCommentFormat" value="csoff (\w+)"/> <property name="onCommentFormat" value="cson (\w+)"/> <property name="checkFormat" value="$1"/> </module> <module name="MemberName"/> <module name="ConstantName"/> <module name="IllegalCatch"/>
class InputSuppressionCommentFilter { int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$' //csoff MemberName int VAR2; // suppressed violation //cson MemberName public static final int var3; // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' //csoff ConstantName //csoff IllegalCatch public static final int var4; // suppressed violation public void method1() { try {} catch(Exception ex) {} // suppressed violation try {} catch(Exception ex) {} // suppressed violation catch(Error err) {} // suppressed violation } //cson ConstantName //cson IllegalCatch }
Example depicting use of checkC and checkCPP style comments
<module name="SuppressionCommentFilter"> <property name="checkC" value="true"/> <property name="checkCPP" value="false"/> </module> <module name="MemberName"/> <module name="ConstantName"/> <module name="IllegalCatch"/>
class InputSuppressionCommentFilter { int VAR1; // violation , Name 'VAR1' must match pattern '^[a-z][a-zA-Z0-9]*$' //CHECKSTYLE:OFF int VAR2; // violation , Name 'VAR2' must match pattern '^[a-z][a-zA-Z0-9]*$' //CHECKSTYLE:ON public static final int var3; // violation above , Name 'var3' must match pattern '^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$' /*CHECKSTYLE:OFF*/ public static final int var4; // suppressed violation /*CHECKSTYLE:ON*/ public void method1() { try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed //CHECKSTYLE:OFF try {} catch(Exception ex) {} // violation , Catching 'Exception' is not allowed catch(Error err) {} // violation , Catching 'Error' is not allowed //CHECKSTYLE:ON } }
Parent is
com.puppycrawl.tools.checkstyle.TreeWalker
- Since:
- 3.5
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
SuppressionCommentFilter.Tag
A Tag holds a suppression comment and its location, and determines whether the suppression turns checkstyle reporting on or off.static class
SuppressionCommentFilter.TagType
Enum to be used for switching checkstyle reporting for tags.-
Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
AbstractAutomaticBean.OutputStreamOptions
-
-
Field Summary
Fields Modifier and Type Field Description private boolean
checkC
Control whether to check C style comments (/* ... */
).private boolean
checkCPP
Control whether to check C++ style comments (//
).private java.lang.String
checkFormat
Specify check pattern to suppress.private static java.lang.String
DEFAULT_CHECK_FORMAT
Control all checks.private static java.lang.String
DEFAULT_OFF_FORMAT
Turns checkstyle reporting off.private static java.lang.String
DEFAULT_ON_FORMAT
Turns checkstyle reporting on.private java.lang.ref.WeakReference<FileContents>
fileContentsReference
References the current FileContents for this filter.private java.lang.String
idFormat
Specify check ID pattern to suppress.private java.lang.String
messageFormat
Specify message pattern to suppress.private java.util.regex.Pattern
offCommentFormat
Specify comment pattern to trigger filter to begin suppression.private java.util.regex.Pattern
onCommentFormat
Specify comment pattern to trigger filter to end suppression.private java.util.List<SuppressionCommentFilter.Tag>
tags
Tagged comments.
-
Constructor Summary
Constructors Constructor Description SuppressionCommentFilter()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
accept(TreeWalkerAuditEvent event)
Determines whether or not a filteredTreeWalkerAuditEvent
is accepted.private void
addTag(java.lang.String text, int line, int column, SuppressionCommentFilter.TagType reportingOn)
Adds aTag
to the list of all tags.private SuppressionCommentFilter.Tag
findNearestMatch(TreeWalkerAuditEvent event)
Finds the nearest comment text tag that matches an audit event.protected void
finishLocalSetup()
Provides a hook to finish the part of this component's setup that was not handled by the bean introspection.private FileContents
getFileContents()
Returns FileContents for this filter.void
setCheckC(boolean checkC)
Setter to control whether to check C style comments (/* ... */
).void
setCheckCPP(boolean checkCpp)
Setter to control whether to check C++ style comments (//
).void
setCheckFormat(java.lang.String format)
Setter to specify check pattern to suppress.void
setFileContents(FileContents fileContents)
Set the FileContents for this filter.void
setIdFormat(java.lang.String format)
Setter to specify check ID pattern to suppress.void
setMessageFormat(java.lang.String format)
Setter to specify message pattern to suppress.void
setOffCommentFormat(java.util.regex.Pattern pattern)
Setter to specify comment pattern to trigger filter to begin suppression.void
setOnCommentFormat(java.util.regex.Pattern pattern)
Setter to specify comment pattern to trigger filter to end suppression.private void
tagCommentLine(java.lang.String text, int line, int column)
Tags a string if it matches the format for turning checkstyle reporting on or the format for turning reporting off.private void
tagSuppressions()
Collects all the suppression tags for all comments into a list and sorts the list.private void
tagSuppressions(java.util.Collection<TextBlock> comments)
Appends the suppressions in a collection of comments to the full set of suppression tags.-
Methods inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
configure, contextualize, getConfiguration, setupChild
-
-
-
-
Field Detail
-
DEFAULT_OFF_FORMAT
private static final java.lang.String DEFAULT_OFF_FORMAT
Turns checkstyle reporting off.- See Also:
- Constant Field Values
-
DEFAULT_ON_FORMAT
private static final java.lang.String DEFAULT_ON_FORMAT
Turns checkstyle reporting on.- See Also:
- Constant Field Values
-
DEFAULT_CHECK_FORMAT
private static final java.lang.String DEFAULT_CHECK_FORMAT
Control all checks.- See Also:
- Constant Field Values
-
tags
private final java.util.List<SuppressionCommentFilter.Tag> tags
Tagged comments.
-
checkC
private boolean checkC
Control whether to check C style comments (/* ... */
).
-
checkCPP
private boolean checkCPP
Control whether to check C++ style comments (//
).
-
offCommentFormat
private java.util.regex.Pattern offCommentFormat
Specify comment pattern to trigger filter to begin suppression.
-
onCommentFormat
private java.util.regex.Pattern onCommentFormat
Specify comment pattern to trigger filter to end suppression.
-
checkFormat
private java.lang.String checkFormat
Specify check pattern to suppress.
-
messageFormat
private java.lang.String messageFormat
Specify message pattern to suppress.
-
idFormat
private java.lang.String idFormat
Specify check ID pattern to suppress.
-
fileContentsReference
private java.lang.ref.WeakReference<FileContents> fileContentsReference
References the current FileContents for this filter. Since this is a weak reference to the FileContents, the FileContents can be reclaimed as soon as the strong references in TreeWalker are reassigned to the next FileContents, at which time filtering for the current FileContents is finished.
-
-
Constructor Detail
-
SuppressionCommentFilter
public SuppressionCommentFilter()
-
-
Method Detail
-
setOffCommentFormat
public final void setOffCommentFormat(java.util.regex.Pattern pattern)
Setter to specify comment pattern to trigger filter to begin suppression.- Parameters:
pattern
- a pattern.
-
setOnCommentFormat
public final void setOnCommentFormat(java.util.regex.Pattern pattern)
Setter to specify comment pattern to trigger filter to end suppression.- Parameters:
pattern
- a pattern.
-
getFileContents
private FileContents getFileContents()
Returns FileContents for this filter.- Returns:
- the FileContents for this filter.
-
setFileContents
public void setFileContents(FileContents fileContents)
Set the FileContents for this filter.- Parameters:
fileContents
- the FileContents for this filter.
-
setCheckFormat
public final void setCheckFormat(java.lang.String format)
Setter to specify check pattern to suppress.- Parameters:
format
- aString
value
-
setMessageFormat
public void setMessageFormat(java.lang.String format)
Setter to specify message pattern to suppress.- Parameters:
format
- aString
value
-
setIdFormat
public void setIdFormat(java.lang.String format)
Setter to specify check ID pattern to suppress.- Parameters:
format
- aString
value
-
setCheckCPP
public void setCheckCPP(boolean checkCpp)
Setter to control whether to check C++ style comments (//
).- Parameters:
checkCpp
-true
if C++ comments are checked.
-
setCheckC
public void setCheckC(boolean checkC)
Setter to control whether to check C style comments (/* ... */
).- Parameters:
checkC
-true
if C comments are checked.
-
finishLocalSetup
protected void finishLocalSetup()
Description copied from class:AbstractAutomaticBean
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 classAbstractAutomaticBean
-
accept
public boolean accept(TreeWalkerAuditEvent event)
Description copied from interface:TreeWalkerFilter
Determines whether or not a filteredTreeWalkerAuditEvent
is accepted.- Specified by:
accept
in interfaceTreeWalkerFilter
- Parameters:
event
- the TreeWalkerAuditEvent to filter.- Returns:
- true if the event is accepted.
-
findNearestMatch
private SuppressionCommentFilter.Tag findNearestMatch(TreeWalkerAuditEvent event)
Finds the nearest comment text tag that matches an audit event. The nearest tag is before the line and column of the event.- Parameters:
event
- theTreeWalkerAuditEvent
to match.- Returns:
- The
Tag
nearest event.
-
tagSuppressions
private void tagSuppressions()
Collects all the suppression tags for all comments into a list and sorts the list.
-
tagSuppressions
private void tagSuppressions(java.util.Collection<TextBlock> comments)
Appends the suppressions in a collection of comments to the full set of suppression tags.- Parameters:
comments
- the set of comments.
-
tagCommentLine
private void tagCommentLine(java.lang.String text, int line, int column)
Tags a string if it matches the format for turning checkstyle reporting on or the format for turning reporting off.- Parameters:
text
- the string to tag.line
- the line number of text.column
- the column number of text.
-
addTag
private void addTag(java.lang.String text, int line, int column, SuppressionCommentFilter.TagType reportingOn)
Adds aTag
to the list of all tags.- Parameters:
text
- the text of the tag.line
- the line number of the tag.column
- the column number of the tag.reportingOn
-true
if the tag turns checkstyle reporting on.
-
-