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.
headerFile - Specify the name of the file containing the required header.
Type is java.net.URI.
Default value is null.
charset - Specify the character encoding to use when reading the headerFile.
Type is java.lang.String.
Default value is the charset property of the parent
<a href="https://checkstyle.org/config.html#Checker">Checker</a> module.
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 is java.lang.String.
Default value is null.
multiLines - Specify the line numbers to repeat (zero or more times).
Type is int[].
Default value is "".
fileExtensions - Specify the file type extension of files to process.
Type is java.lang.String[].
Default value is "".
To configure the check such that no violations arise. Default values of properties are used.
<module name="RegexpHeader"/>
To configure the check to use header file "config/java.header" and
10 and 13 multi-lines:
<module name="RegexpHeader"> <property name="headerFile" value="config/java.header"/> <property name="multiLines" value="10, 13"/> </module>
To configure the check to verify that each file starts with the header
^// Copyright \(C\) (\d\d\d\d -)? 2004 MyCompany$ ^// All rights reserved$
without the need for an external header file:
<module name="RegexpHeader">
<property
name="header"
value="^// Copyright \(C\) (\d\d\d\d -)? 2004 MyCompany$
\n^// All rights reserved$"/>
</module>
For regex containing "\n\n"
<module name="RegexpHeader">
<property
name="header"
value="^package .*\n\n.*"/>
</module>
"\n\n" will be treated as '^$' and will forcefully expect the line
to be empty. For example -
package com.some.package;
public class ThisWillFail { }
would fail for the regex above. Expected -
package com.some.package;
public class ThisWillPass { }
Note: ignoreLines property has been removed from this check to simplify it.
To make some line optional use "^.*$" regexp for this line.
Parent is com.puppycrawl.tools.checkstyle.Checker
Violation Message Keys:
header.mismatch
header.missing
AutomaticBean.OutputStreamOptions| Modifier and Type | Field and Description |
|---|---|
private static java.util.regex.Pattern |
BLANK_LINE
Compiled regex pattern for a blank line.
|
private static int[] |
EMPTY_INT_ARRAY
Empty array to avoid instantiations.
|
private static java.lang.String |
EMPTY_LINE_PATTERN
Regex pattern for a blank line.
|
private java.util.List<java.util.regex.Pattern> |
headerRegexps
The compiled regular expressions.
|
static java.lang.String |
MSG_HEADER_MISMATCH
A key is pointing to the warning message text in "messages.properties"
file.
|
static java.lang.String |
MSG_HEADER_MISSING
A key is pointing to the warning message text in "messages.properties"
file.
|
private int[] |
multiLines
Specify the line numbers to repeat (zero or more times).
|
| Constructor and Description |
|---|
RegexpHeaderCheck() |
| Modifier and Type | Method and Description |
|---|---|
private java.lang.String |
getHeaderLine(int headerLineNo)
Returns the line from the header.
|
private boolean |
isMatch(java.lang.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(java.io.File file,
FileText fileText)
Called to process a file that matches the specified file extensions.
|
void |
setHeader(java.lang.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).
|
finishLocalSetup, getExternalResourceLocations, getHeaderLines, setCharset, setHeaderFileaddViolations, beginProcessing, destroy, finishProcessing, fireErrors, getFileContents, getFileExtensions, getMessageDispatcher, getTabWidth, getViolations, init, log, log, process, setFileContents, setFileExtensions, setMessageDispatcher, setTabWidthgetCustomMessages, getId, getMessageBundle, getSeverity, getSeverityLevel, setId, setSeverityconfigure, contextualize, getConfiguration, setupChildclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitconfigurecontextualizepublic static final java.lang.String MSG_HEADER_MISSING
public static final java.lang.String MSG_HEADER_MISMATCH
private static final int[] EMPTY_INT_ARRAY
private static final java.lang.String EMPTY_LINE_PATTERN
private static final java.util.regex.Pattern BLANK_LINE
private final java.util.List<java.util.regex.Pattern> headerRegexps
private int[] multiLines
public RegexpHeaderCheck()
public void setMultiLines(int... list)
list - comma separated list of line numbers to repeat in header.protected void processFiltered(java.io.File file, FileText fileText)
AbstractFileSetCheckprocessFiltered in class AbstractFileSetCheckfile - the file to be processedfileText - the contents of the file.private java.lang.String getHeaderLine(int headerLineNo)
headerLineNo - header line number to returnprivate void logFirstSinglelineLine(int startHeaderLine, int headerSize)
startHeaderLine - header line number to start fromheaderSize - whole header sizeprivate boolean isMatch(java.lang.String line, int headerLineNo)
line - the code lineheaderLineNo - the header line number.private boolean isMultiLine(int lineNo)
lineNo - a line numberlineNo is one of the repeat header lines.protected void postProcessHeaderLines()
AbstractHeaderCheckpostProcessHeaderLines in class AbstractHeaderCheckpublic void setHeader(java.lang.String header)
"\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.setHeader in class AbstractHeaderCheckheader - the header value to validate and set (in that order)Copyright © 2001-2022. All Rights Reserved.