| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <document xmlns="http://maven.apache.org/XDOC/2.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| |
| <head> |
| <title>Headers</title> |
| <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/> |
| <script type="text/javascript" src="js/anchors.js"/> |
| <script type="text/javascript" src="js/google-analytics.js"/> |
| <link rel="icon" href="images/favicon.png" type="image/x-icon" /> |
| <link rel="shortcut icon" href="images/favicon.ico" type="image/ico" /> |
| </head> |
| |
| <body> |
| <section name="Content"> |
| <macro name="toc"> |
| <param name="fromDepth" value="1"/> |
| <param name="toDepth" value="1"/> |
| </macro> |
| </section> |
| |
| <section name="Header"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.9</p> |
| <p> |
| Checks that a source file begins with a specified header. Property |
| <code> headerFile</code> specifies a file that contains |
| the required header. Alternatively, the header specification can be |
| set directly in the <code>header</code> property |
| without the need for an external file. |
| </p> |
| |
| <p> |
| Property <code>ignoreLines</code> specifies the line |
| numbers to ignore when matching lines in a header file. This |
| property is very useful for supporting headers that contain |
| copyright dates. For example, consider the following header: |
| </p> |
| |
| <source> |
| line 1: //////////////////////////////////////////////////////////////////// |
| line 2: // checkstyle: |
| line 3: // Checks Java source code for adherence to a set of rules. |
| line 4: // Copyright (C) 2002 Oliver Burn |
| line 5: //////////////////////////////////////////////////////////////////// |
| </source> |
| |
| <p> |
| Since the year information will change over time, you can tell |
| Checkstyle to ignore line 4 by setting property <code>ignoreLines</code> to <code> 4</code>. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>headerFile</td> |
| <td>name of the file containing the required header</td> |
| <td><a href="property_types.html#uri">URI</a></td> |
| <td><code>null</code></td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>charset</td> |
| <td>character encoding to use when reading the headerFile</td> |
| <td><a href="property_types.html#string">string</a></td> |
| <td>the charset property of the parent |
| <a href="config.html#Checker">Checker</a> module</td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>header</td> |
| <td> |
| the required header specified inline. Individual header lines |
| must be separated by the string <code>"\n"</code> (even on platforms with a |
| different line separator), see examples below. |
| </td> |
| <td><a href="property_types.html#string">string</a></td> |
| <td><code>null</code></td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>ignoreLines</td> |
| <td>line numbers to ignore</td> |
| <td><a href="property_types.html#intSet">Integer Set</a></td> |
| <td><code>{}</code></td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>fileExtensions</td> |
| <td>file type extension of files to process</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>{}</code></td> |
| <td>6.9</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| In default configuration the check does not rise any violations. Default values of properties are used. |
| </p> |
| |
| <source> |
| <module name="Header"/> |
| </source> |
| |
| <p> |
| To configure the check to use header file <code>"config/java.header"</code> and ignore lines <code>2</code>, <code>3</code>, and <code> 4</code> and only process Java files: |
| </p> |
| |
| <source> |
| <module name="Header"> |
| <property name="headerFile" value="config/java.header"/> |
| <property name="ignoreLines" value="2, 3, 4"/> |
| <property name="fileExtensions" value="java"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check to verify that each file starts with the |
| header |
| </p> |
| <source> |
| // Copyright (C) 2004 MyCompany |
| // All rights reserved |
| </source> |
| |
| <p> |
| without the need for an external header file: |
| </p> |
| <source> |
| <module name="Header"> |
| <property name="header" |
| value="// Copyright (C) 2004 MyCompany\n// All rights reserved"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+Header"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fheader+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22header.mismatch%22"> |
| header.mismatch</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fheader+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22header.missing%22"> |
| header.missing</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> com.puppycrawl.tools.checkstyle.checks.header </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#Checker">Checker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| <section name="RegexpHeader"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.9</p> |
| <p> |
| Checks the header of a source file against a header that contains a |
| <a |
| href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">regular |
| expression</a> for each line of the source header. |
| </p> |
| |
| <p> |
| Rationale: In some projects <a href="#Header">checking against a |
| fixed header</a> is not sufficient, e.g. the header might require a |
| copyright line where the year information is not static. |
| </p> |
| |
| <p> |
| For example, consider the following header: |
| </p> |
| <source> |
| 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: ^ \*/ |
| </source> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| 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): |
| </p> |
| <source> |
| 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*$ |
| </source> |
| |
| <p> |
| 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. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>headerFile</td> |
| <td>name of the file containing the required header</td> |
| <td><a href="property_types.html#uri">URI</a></td> |
| <td><code>null</code></td> |
| <td>3.2</td> |
| </tr> |
| <tr> |
| <td>charset</td> |
| <td>character encoding to use when reading the headerFile</td> |
| <td><a href="property_types.html#string">string</a></td> |
| <td>the charset property of the parent |
| <a href="config.html#Checker">Checker</a> module</td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>header</td> |
| <td> |
| the required header specified inline. Individual header lines |
| must be separated by the string <code>"\n"</code> (even on platforms with a |
| different line separator). For header lines containing <code>"\n\n"</code> |
| checkstyle will forcefully expect an empty line to exist. See examples |
| below. Regular expressions must not span multiple lines. |
| </td> |
| <td><a href="property_types.html#string">string</a></td> |
| <td><code>null</code></td> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>multiLines</td> |
| <td>line numbers to repeat (zero or more times)</td> |
| <td><a href="property_types.html#intSet">Integer Set</a></td> |
| <td><code>{}</code></td> |
| <td>3.4</td> |
| </tr> |
| <tr> |
| <td>fileExtensions</td> |
| <td>file type extension of files to process</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>{}</code></td> |
| <td>6.9</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| In default configuration the check does not rise any violations. Default values of properties are used. |
| </p> |
| <source> |
| <module name="RegexpHeader"/> |
| </source> |
| |
| <p> |
| To configure the check to use header file <code>"config/java.header"</code> and <code>10</code> and <code>13</code> multi-lines: |
| </p> |
| <source> |
| <module name="RegexpHeader"> |
| <property name="headerFile" value="config/java.header"/> |
| <property name="multiLines" value="10, 13"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check to verify that each file starts with the |
| header |
| </p> |
| <source> |
| ^// Copyright \(C\) (\d\d\d\d -)? 2004 MyCompany$ |
| ^// All rights reserved$ |
| </source> |
| |
| <p> |
| without the need for an external header file: |
| </p> |
| <source> |
| <module name="RegexpHeader"> |
| <property |
| name="header" |
| value="^// Copyright \(C\) (\d\d\d\d -)? 2004 MyCompany$\n^// All rights reserved$"/> |
| </module> |
| </source> |
| |
| <p> |
| For regex containing <code>"\n\n"</code> |
| </p> |
| <source> |
| <module name="RegexpHeader"> |
| <property |
| name="header" |
| value="^package .*\n\n.*"/> |
| </module> |
| </source> |
| <p> |
| <code>"\n\n"</code> will be treated as '^$' and will forcefully |
| expect the line to be empty. For example - |
| </p> |
| <source> |
| package com.some.package; |
| public class ThisWillFail { } |
| </source> |
| <p> |
| would fail for the regex above. Expected - |
| </p> |
| <source> |
| package com.some.package; |
| |
| public class ThisWillPass { } |
| </source> |
| |
| <p> |
| <u>Note</u>: <code>ignoreLines</code> property has been |
| removed from this check to simplify it. To make some line optional |
| use "^.*$" regexp for this line. |
| </p> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+RegexpHeader"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fheader+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22header.mismatch%22"> |
| header.mismatch</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fheader+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22header.missing%22"> |
| header.missing</a> |
| </li> |
| </ul> |
| <p> |
| All messages can be customized if the default message doesn't suit you. |
| Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to. |
| </p> |
| </subsection> |
| |
| <subsection name="Package"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks.header |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#Checker">Checker</a> |
| </p> |
| </subsection> |
| </section> |
| </body> |
| </document> |