Source code

001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2020 the original author or authors.
004//
005// This library is free software; you can redistribute it and/or
006// modify it under the terms of the GNU Lesser General Public
007// License as published by the Free Software Foundation; either
008// version 2.1 of the License, or (at your option) any later version.
009//
010// This library is distributed in the hope that it will be useful,
011// but WITHOUT ANY WARRANTY; without even the implied warranty of
012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
013// Lesser General Public License for more details.
014//
015// You should have received a copy of the GNU Lesser General Public
016// License along with this library; if not, write to the Free Software
017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018////////////////////////////////////////////////////////////////////////////////
019
020package com.puppycrawl.tools.checkstyle.checks.regexp;
021
022import java.io.File;
023import java.io.IOException;
024import java.util.regex.Pattern;
025
026import com.puppycrawl.tools.checkstyle.StatelessCheck;
027import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck;
028import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
029import com.puppycrawl.tools.checkstyle.api.FileText;
030import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
031
032/**
033 * <p>
034 * Checks that a specified pattern matches based on file and/or folder path.
035 * It can also be used to verify files
036 * match specific naming patterns not covered by other checks (Ex: properties,
037 * xml, etc.).
038 * </p>
039 *
040 * <p>
041 * When customizing the check, the properties are applied in a specific order.
042 * The fileExtensions property first picks only files that match any of the
043 * specific extensions supplied. Once files are matched against the
044 * fileExtensions, the match property is then used in conjunction with the
045 * patterns to determine if the check is looking for a match or mis-match on
046 * those files. If the fileNamePattern is supplied, the matching is only applied
047 * to the fileNamePattern and not the folderPattern. If no fileNamePattern is
048 * supplied, then matching is applied to the folderPattern only and will result
049 * in all files in a folder to be reported on violations. If no folderPattern is
050 * supplied, then all folders that checkstyle finds are examined for violations.
051 * The ignoreFileNameExtensions property drops the file extension and applies
052 * the fileNamePattern only to the rest of file name. For example, if the file
053 * is named 'test.java' and this property is turned on, the pattern is only
054 * applied to 'test'.
055 * </p>
056 *
057 * <p>
058 * If this check is configured with no properties, then the default behavior of
059 * this check is to report file names with spaces in them. When at least one
060 * pattern property is supplied, the entire check is under the user's control to
061 * allow them to fully customize the behavior.
062 * </p>
063 *
064 * <p>
065 * It is recommended that if you create your own pattern, to also specify a
066 * custom violation message. This allows the violation message printed to be clear what
067 * the violation is, especially if multiple RegexpOnFilename checks are used.
068 * Argument 0 for the message populates the check's folderPattern. Argument 1
069 * for the message populates the check's fileNamePattern. The file name is not
070 * passed as an argument since it is part of CheckStyle's default violation
071 * messages.
072 * </p>
073 * <ul>
074 * <li>
075 * Property {@code folderPattern} - Specify the regular expression to match the folder path against.
076 * Default value is {@code null}.</li>
077 *
078 * <li>
079 * Property {@code fileNamePattern} - Specify the regular expression to match the file name against.
080 * Default value is {@code null}.</li>
081 *
082 * <li>
083 * Property {@code match} - Control whether to look for a match or mis-match on the file name, if
084 * the fileNamePattern is supplied, otherwise it is applied on the folderPattern.
085 * Default value is {@code true}.</li>
086 *
087 * <li>
088 * Property {@code ignoreFileNameExtensions} - Control whether to ignore the file extension for
089 * the file name match. Default value is {@code false}.</li>
090 *
091 * <li>
092 * Property {@code fileExtensions} - Specify the file type extension of files to process. If this is
093 * specified, then only files that match these types are examined with the other
094 * patterns. Default value is {@code all files}.</li>
095 * </ul>
096 *
097 * <p>
098 * To configure the check to report file names that contain a space:
099 * </p>
100 *
101 * <pre>
102 * &lt;module name=&quot;RegexpOnFilename&quot;/&gt;
103 * </pre>
104 * <p>
105 * To configure the check to force picture files to not be 'gif':
106 * </p>
107 *
108 * <pre>
109 * &lt;module name=&quot;RegexpOnFilename&quot;&gt;
110 *   &lt;property name=&quot;fileNamePattern&quot; value=&quot;\.gif$&quot;/&gt;
111 * &lt;/module&gt;
112 * </pre>
113 * <p>
114 * OR:
115 * </p>
116 *
117 * <pre>
118 * &lt;module name=&quot;RegexpOnFilename&quot;&gt;
119 *   &lt;property name=&quot;fileNamePattern&quot; value=&quot;.&quot;/&gt;
120 *   &lt;property name=&quot;fileExtensions&quot; value=&quot;gif&quot;/&gt;
121 * &lt;/module&gt;
122 * </pre>
123 *
124 * <p>
125 * To configure the check to only allow property and xml files to be located in
126 * the resource folder:
127 * </p>
128 *
129 * <pre>
130 * &lt;module name=&quot;RegexpOnFilename&quot;&gt;
131 *   &lt;property name=&quot;folderPattern&quot;
132 *     value=&quot;[\\/]src[\\/]\w+[\\/]resources[\\/]&quot;/&gt;
133 *   &lt;property name=&quot;match&quot; value=&quot;false&quot;/&gt;
134 *   &lt;property name=&quot;fileExtensions&quot; value=&quot;properties, xml&quot;/&gt;
135 * &lt;/module&gt;
136 * </pre>
137 *
138 * <p>
139 * To configure the check to only allow Java and XML files in your folders use
140 * the below.
141 * </p>
142 *
143 * <pre>
144 * &lt;module name=&quot;RegexpOnFilename&quot;&gt;
145 *   &lt;property name=&quot;fileNamePattern&quot; value=&quot;\.(java|xml)$&quot;/&gt;
146 *   &lt;property name=&quot;match&quot; value=&quot;false&quot;/&gt;
147 * &lt;/module&gt;
148 * </pre>
149 *
150 * <p>
151 * To configure the check to only allow Java and XML files only in your source
152 * folder and ignore any other folders:
153 * </p>
154 *
155 * <pre>
156 * &lt;module name=&quot;RegexpOnFilename&quot;&gt;
157 *   &lt;property name=&quot;folderPattern&quot; value=&quot;[\\/]src[\\/]&quot;/&gt;
158 *   &lt;property name=&quot;fileNamePattern&quot; value=&quot;\.(java|xml)$&quot;/&gt;
159 *   &lt;property name=&quot;match&quot; value=&quot;false&quot;/&gt;
160 * &lt;/module&gt;
161 * </pre>
162 *
163 * <p>
164 * <b>Note:</b> 'folderPattern' must be specified if checkstyle is analyzing
165 * more than the normal source folder, like the 'bin' folder where class files
166 * can be located.
167 * </p>
168 *
169 * <p>
170 * To configure the check to only allow file names to be camel case:
171 * </p>
172 *
173 * <pre>
174 * &lt;module name=&quot;RegexpOnFilename&quot;&gt;
175 *   &lt;property name=&quot;fileNamePattern&quot; value=&quot;^([A-Z][a-z0-9]+\.?)+$&quot;/&gt;
176 *   &lt;property name=&quot;match&quot; value=&quot;false&quot;/&gt;
177 *   &lt;property name=&quot;ignoreFileNameExtensions&quot; value=&quot;true&quot;/&gt;
178 * &lt;/module&gt;
179 * </pre>
180 *
181 * @since 6.15
182 */
183@StatelessCheck
184public class RegexpOnFilenameCheck extends AbstractFileSetCheck {
185
186    /**
187     * A key is pointing to the warning message text in "messages.properties"
188     * file.
189     */
190    public static final String MSG_MATCH = "regexp.filename.match";
191    /**
192     * A key is pointing to the warning message text in "messages.properties"
193     * file.
194     */
195    public static final String MSG_MISMATCH = "regexp.filename.mismatch";
196
197    /** Specify the regular expression to match the folder path against. */
198    private Pattern folderPattern;
199    /** Specify the regular expression to match the file name against. */
200    private Pattern fileNamePattern;
201    /**
202     * Control whether to look for a match or mis-match on the file name,
203     * if the fileNamePattern is supplied, otherwise it is applied on the folderPattern.
204     */
205    private boolean match = true;
206    /** Control whether to ignore the file extension for the file name match. */
207    private boolean ignoreFileNameExtensions;
208
209    /**
210     * Setter to specify the regular expression to match the folder path against.
211     *
212     * @param folderPattern format of folder.
213     */
214    public void setFolderPattern(Pattern folderPattern) {
215        this.folderPattern = folderPattern;
216    }
217
218    /**
219     * Setter to specify the regular expression to match the file name against.
220     *
221     * @param fileNamePattern format of file.
222     */
223    public void setFileNamePattern(Pattern fileNamePattern) {
224        this.fileNamePattern = fileNamePattern;
225    }
226
227    /**
228     * Setter to control whether to look for a match or mis-match on the file name,
229     * if the fileNamePattern is supplied, otherwise it is applied on the folderPattern.
230     *
231     * @param match check's option for matching file names.
232     */
233    public void setMatch(boolean match) {
234        this.match = match;
235    }
236
237    /**
238     * Setter to control whether to ignore the file extension for the file name match.
239     *
240     * @param ignoreFileNameExtensions check's option for ignoring file extension.
241     */
242    public void setIgnoreFileNameExtensions(boolean ignoreFileNameExtensions) {
243        this.ignoreFileNameExtensions = ignoreFileNameExtensions;
244    }
245
246    @Override
247    public void init() {
248        if (fileNamePattern == null && folderPattern == null) {
249            fileNamePattern = CommonUtil.createPattern("\\s");
250        }
251    }
252
253    @Override
254    protected void processFiltered(File file, FileText fileText) throws CheckstyleException {
255        final String fileName = getFileName(file);
256        final String folderPath = getFolderPath(file);
257
258        if (isMatchFolder(folderPath) && isMatchFile(fileName)) {
259            log();
260        }
261    }
262
263    /**
264     * Retrieves the file name from the given {@code file}.
265     *
266     * @param file Input file to examine.
267     * @return The file name.
268     */
269    private String getFileName(File file) {
270        String fileName = file.getName();
271
272        if (ignoreFileNameExtensions) {
273            fileName = CommonUtil.getFileNameWithoutExtension(fileName);
274        }
275
276        return fileName;
277    }
278
279    /**
280     * Retrieves the folder path from the given {@code file}.
281     *
282     * @param file Input file to examine.
283     * @return The folder path.
284     * @throws CheckstyleException if there is an error getting the canonical
285     *         path of the {@code file}.
286     */
287    private static String getFolderPath(File file) throws CheckstyleException {
288        try {
289            return file.getCanonicalFile().getParent();
290        }
291        catch (IOException ex) {
292            throw new CheckstyleException("unable to create canonical path names for "
293                    + file.getAbsolutePath(), ex);
294        }
295    }
296
297    /**
298     * Checks if the given {@code folderPath} matches the specified
299     * {@link #folderPattern}.
300     *
301     * @param folderPath Input folder path to examine.
302     * @return true if they do match.
303     */
304    private boolean isMatchFolder(String folderPath) {
305        final boolean result;
306
307        // null pattern always matches, regardless of value of 'match'
308        if (folderPattern == null) {
309            result = true;
310        }
311        else {
312            // null pattern means 'match' applies to the folderPattern matching
313            final boolean useMatch = fileNamePattern != null || match;
314            result = folderPattern.matcher(folderPath).find() == useMatch;
315        }
316
317        return result;
318    }
319
320    /**
321     * Checks if the given {@code fileName} matches the specified
322     * {@link #fileNamePattern}.
323     *
324     * @param fileName Input file name to examine.
325     * @return true if they do match.
326     */
327    private boolean isMatchFile(String fileName) {
328        // null pattern always matches, regardless of value of 'match'
329        return fileNamePattern == null || fileNamePattern.matcher(fileName).find() == match;
330    }
331
332    /** Logs the violations for the check. */
333    private void log() {
334        final String folder = getStringOrDefault(folderPattern, "");
335        final String fileName = getStringOrDefault(fileNamePattern, "");
336
337        if (match) {
338            log(1, MSG_MATCH, folder, fileName);
339        }
340        else {
341            log(1, MSG_MISMATCH, folder, fileName);
342        }
343    }
344
345    /**
346     * Retrieves the String form of the {@code pattern} or {@code defaultString}
347     * if null.
348     *
349     * @param pattern The pattern to convert.
350     * @param defaultString The result to use if {@code pattern} is null.
351     * @return The String form of the {@code pattern}.
352     */
353    private static String getStringOrDefault(Pattern pattern, String defaultString) {
354        final String result;
355
356        if (pattern == null) {
357            result = defaultString;
358        }
359        else {
360            result = pattern.toString();
361        }
362
363        return result;
364    }
365
366}