Class RegexpHeaderCheck
- java.lang.Object
-
- com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
-
- com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
-
- com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck
-
- com.puppycrawl.tools.checkstyle.checks.header.AbstractHeaderCheck
-
- com.puppycrawl.tools.checkstyle.checks.header.RegexpHeaderCheck
-
- All Implemented Interfaces:
Configurable
,Contextualizable
,ExternalResourceHolder
,FileSetCheck
public class RegexpHeaderCheck extends AbstractHeaderCheck
Checks the header of a source file against a header that contains a pattern for each line of the source header.Rationale: In some projects checking against a fixed header is not sufficient, e.g. the header might require a copyright line where the year information is not static.
For example, consider the following header:
line 1: ^/{71}$ line 2: ^// checkstyle:$ line 3: ^// Checks Java source code for adherence to a set of rules\.$ line 4: ^// Copyright \(C\) \d\d\d\d Oliver Burn$ line 5: ^// Last modification by \$Author.*\$$ line 6: ^/{71}$ line 7: line 8: ^package line 9: line 10: ^import line 11: line 12: ^/\*\* line 13: ^ \*([^/]|$) line 14: ^ \*/
Lines 1 and 6 demonstrate a more compact notation for 71 '/' characters. Line 4 enforces that the copyright notice includes a four digit year. Line 5 is an example how to enforce revision control keywords in a file header. Lines 12-14 is a template for javadoc (line 13 is so complicated to remove conflict with and of javadoc comment). Lines 7, 9 and 11 will be treated as '^$' and will forcefully expect the line to be empty.
Different programming languages have different comment syntax rules, but all of them start a comment with a non-word character. Hence, you can often use the non-word character class to abstract away the concrete comment syntax and allow checking the header for different languages with a single header definition. For example, consider the following header specification (note that this is not the full Apache license header):
line 1: ^#! line 2: ^<\?xml.*>$ line 3: ^\W*$ line 4: ^\W*Copyright 2006 The Apache Software Foundation or its licensors, as applicable\.$ line 5: ^\W*Licensed under the Apache License, Version 2\.0 \(the "License"\);$ line 6: ^\W*$
Lines 1 and 2 leave room for technical header lines, e.g. the "#!/bin/sh" line in Unix shell scripts, or the XML file header of XML files. Set the multiline property to "1, 2" so these lines can be ignored for file types where they do no apply. Lines 3 through 6 define the actual header content. Note how lines 2, 4 and 5 use escapes for characters that have special regexp semantics.
In default configuration, if header is not specified, the default value of header is set to null and the check does not rise any violations.
-
Property
charset
- Specify the character encoding to use when reading the headerFile. Type isjava.lang.String
. Default value isthe charset property of the parent <a href="https://checkstyle.org/config.html#Checker">Checker</a> module
. -
Property
fileExtensions
- Specify the file extensions of the files to process. Type isjava.lang.String[]
. Default value is""
. -
Property
header
- Define the required header specified inline. Individual header lines must be separated by the string"\n"
(even on platforms with a different line separator). For header lines containing"\n\n"
checkstyle will forcefully expect an empty line to exist. See examples below. Regular expressions must not span multiple lines. Type isjava.lang.String
. Default value isnull
. -
Property
headerFile
- Specify the name of the file containing the required header. Type isjava.net.URI
. Default value isnull
. -
Property
multiLines
- Specify the line numbers to repeat (zero or more times). Type isint[]
. Default value is""
.
Parent is
com.puppycrawl.tools.checkstyle.Checker
Violation Message Keys:
-
header.mismatch
-
header.missing
- Since:
- 6.9
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
AbstractAutomaticBean.OutputStreamOptions
-
-
Field Summary
Fields Modifier and Type Field Description private static Pattern
BLANK_LINE
Compiled regex pattern for a blank line.private static String
EMPTY_LINE_PATTERN
Regex pattern for a blank line.private List<Pattern>
headerRegexps
The compiled regular expressions.static String
MSG_HEADER_MISMATCH
A key is pointing to the warning message text in "messages.properties" file.static String
MSG_HEADER_MISSING
A key is pointing to the warning message text in "messages.properties" file.private BitSet
multiLines
Specify the line numbers to repeat (zero or more times).
-
Constructor Summary
Constructors Constructor Description RegexpHeaderCheck()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description private String
getHeaderLine(int headerLineNo)
Returns the line from the header.private boolean
isMatch(String line, int headerLineNo)
Checks if a code line matches the required header line.private boolean
isMultiLine(int lineNo)
Returns true if line is multiline header lines or false.private void
logFirstSinglelineLine(int startHeaderLine, int headerSize)
Logs warning if any non-multiline lines left in header regexp.protected void
postProcessHeaderLines()
Hook method for post-processing header lines.protected void
processFiltered(File file, FileText fileText)
Called to process a file that matches the specified file extensions.void
setHeader(String header)
Setter to define the required header specified inline.void
setMultiLines(int... list)
Setter to specify the line numbers to repeat (zero or more times).-
Methods inherited from class com.puppycrawl.tools.checkstyle.checks.header.AbstractHeaderCheck
finishLocalSetup, getExternalResourceLocations, getHeaderLines, setCharset, setHeaderFile
-
Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck
addViolations, beginProcessing, destroy, finishProcessing, fireErrors, getFileContents, getFileExtensions, getMessageDispatcher, getTabWidth, getViolations, init, log, log, process, setFileContents, setFileExtensions, setMessageDispatcher, setTabWidth
-
Methods inherited from class com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
getCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverity
-
Methods inherited from class com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
configure, contextualize, getConfiguration, setupChild
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface com.puppycrawl.tools.checkstyle.api.Configurable
configure
-
Methods inherited from interface com.puppycrawl.tools.checkstyle.api.Contextualizable
contextualize
-
-
-
-
Field Detail
-
MSG_HEADER_MISSING
public static final String MSG_HEADER_MISSING
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
MSG_HEADER_MISMATCH
public static final String MSG_HEADER_MISMATCH
A key is pointing to the warning message text in "messages.properties" file.- See Also:
- Constant Field Values
-
EMPTY_LINE_PATTERN
private static final String EMPTY_LINE_PATTERN
Regex pattern for a blank line.- See Also:
- Constant Field Values
-
BLANK_LINE
private static final Pattern BLANK_LINE
Compiled regex pattern for a blank line.
-
headerRegexps
private final List<Pattern> headerRegexps
The compiled regular expressions.
-
multiLines
private BitSet multiLines
Specify the line numbers to repeat (zero or more times).
-
-
Constructor Detail
-
RegexpHeaderCheck
public RegexpHeaderCheck()
-
-
Method Detail
-
setMultiLines
public void setMultiLines(int... list)
Setter to specify the line numbers to repeat (zero or more times).- Parameters:
list
- line numbers to repeat in header.- Since:
- 3.4
-
processFiltered
protected void processFiltered(File file, FileText fileText)
Description copied from class:AbstractFileSetCheck
Called to process a file that matches the specified file extensions.- Specified by:
processFiltered
in classAbstractFileSetCheck
- Parameters:
file
- the file to be processedfileText
- the contents of the file.
-
getHeaderLine
private String getHeaderLine(int headerLineNo)
Returns the line from the header. Where the line is blank return the regexp pattern for a blank line.- Parameters:
headerLineNo
- header line number to return- Returns:
- the line from the header
-
logFirstSinglelineLine
private void logFirstSinglelineLine(int startHeaderLine, int headerSize)
Logs warning if any non-multiline lines left in header regexp.- Parameters:
startHeaderLine
- header line number to start fromheaderSize
- whole header size
-
isMatch
private boolean isMatch(String line, int headerLineNo)
Checks if a code line matches the required header line.- Parameters:
line
- the code lineheaderLineNo
- the header line number.- Returns:
- true if and only if the line matches the required header line.
-
isMultiLine
private boolean isMultiLine(int lineNo)
Returns true if line is multiline header lines or false.- Parameters:
lineNo
- a line number- Returns:
- if
lineNo
is one of the repeat header lines.
-
postProcessHeaderLines
protected void postProcessHeaderLines()
Description copied from class:AbstractHeaderCheck
Hook method for post-processing header lines. This implementation does nothing.- Specified by:
postProcessHeaderLines
in classAbstractHeaderCheck
-
setHeader
public void setHeader(String header)
Setter to define the required header specified inline. Individual header lines must be separated by the string"\n"
(even on platforms with a different line separator). For header lines containing"\n\n"
checkstyle will forcefully expect an empty line to exist. See examples below. Regular expressions must not span multiple lines.- Overrides:
setHeader
in classAbstractHeaderCheck
- Parameters:
header
- the header value to validate and set (in that order)- Since:
- 5.0
-
-