001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2019 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.util.regex.Pattern;
024
025import com.puppycrawl.tools.checkstyle.StatelessCheck;
026import com.puppycrawl.tools.checkstyle.api.AbstractFileSetCheck;
027import com.puppycrawl.tools.checkstyle.api.FileText;
028
029/**
030 * <p>
031 * A check for detecting that matches across multiple lines. Works with any file type.
032 * </p>
033 * <p>
034 * Rationale: This check can be used to when the regular expression can be span multiple lines.
035 * </p>
036 * <ul>
037 * <li>
038 * Property {@code format} - Specify the format of the regular expression to match.
039 * Default value is {@code "$."}.
040 * </li>
041 * <li>
042 * Property {@code message} - Specify the message which is used to notify about
043 * violations, if empty then default (hard-coded) message is used.
044 * Default value is {@code null}.
045 * </li>
046 * <li>
047 * Property {@code ignoreCase} - Control whether to ignore case when searching.
048 * Default value is {@code false}.
049 * </li>
050 * <li>
051 * Property {@code minimum} - Specify the minimum number of matches required in each file.
052 * Default value is {@code 0}.
053 * </li>
054 * <li>
055 * Property {@code maximum} - Specify the maximum number of matches required in each file.
056 * Default value is {@code 0}.
057 * </li>
058 * <li>
059 * Property {@code matchAcrossLines} - Control whether to match expressions
060 * across multiple lines.
061 * Default value is {@code false}.
062 * </li>
063 * <li>
064 * Property {@code fileExtensions} - Specify the file type extension of files to process.
065 * Default value is {@code all files}.
066 * </li>
067 * </ul>
068 * <p>
069 * To configure the check to find calls to print to the console:
070 * </p>
071 * <pre>
072 * &lt;module name="RegexpMultiline"&gt;
073 *   &lt;property name="format"
074 *     value="System\.(out)|(err)\.print(ln)?\("/&gt;
075 * &lt;/module&gt;
076 * </pre>
077 * <p>
078 * To configure the check to match text that spans multiple lines,
079 * like normal code in a Java file:
080 * </p>
081 * <pre>
082 * &lt;module name="RegexpMultiline"&gt;
083 *   &lt;property name="matchAcrossLines" value="true"/&gt;
084 *   &lt;property name="format" value="System\.out.*print\("/&gt;
085 * &lt;/module&gt;
086 * </pre>
087 * <p>
088 * Example of violation from the above config:
089 * </p>
090 * <pre>
091 * void method() {
092 *   System.out. // violation
093 *   print("Example");
094 *   System.out.
095 *   print("Example");
096 * }
097 * </pre>
098 * <p>
099 * Note: Beware of the greedy regular expression used in the above example.
100 * {@code .*} will match as much as possible and not produce multiple violations
101 * in the file if multiple groups of lines could match the expression. To prevent
102 * an expression being too greedy, avoid overusing matching all text or allow it
103 * to be optional, like {@code .*?}. Changing the example expression to not be
104 * greedy will allow multiple violations in the example to be found in the same file.
105 * </p>
106 *
107 * @since 5.0
108 */
109@StatelessCheck
110public class RegexpMultilineCheck extends AbstractFileSetCheck {
111
112    /** Specify the format of the regular expression to match. */
113    private String format = "$.";
114    /**
115     * Specify the message which is used to notify about violations,
116     * if empty then default (hard-coded) message is used.
117     */
118    private String message;
119    /** Specify the minimum number of matches required in each file. */
120    private int minimum;
121    /** Specify the maximum number of matches required in each file. */
122    private int maximum;
123    /** Control whether to ignore case when searching. */
124    private boolean ignoreCase;
125    /** Control whether to match expressions across multiple lines. */
126    private boolean matchAcrossLines;
127
128    /** The detector to use. */
129    private MultilineDetector detector;
130
131    @Override
132    public void beginProcessing(String charset) {
133        final DetectorOptions options = DetectorOptions.newBuilder()
134            .reporter(this)
135            .compileFlags(getRegexCompileFlags())
136            .format(format)
137            .message(message)
138            .minimum(minimum)
139            .maximum(maximum)
140            .ignoreCase(ignoreCase)
141            .build();
142        detector = new MultilineDetector(options);
143    }
144
145    @Override
146    protected void processFiltered(File file, FileText fileText) {
147        detector.processLines(fileText);
148    }
149
150    /**
151     * Retrieves the compile flags for the regular expression being built based
152     * on {@code matchAcrossLines}.
153     * @return The compile flags.
154     */
155    private int getRegexCompileFlags() {
156        final int result;
157
158        if (matchAcrossLines) {
159            result = Pattern.DOTALL;
160        }
161        else {
162            result = Pattern.MULTILINE;
163        }
164
165        return result;
166    }
167
168    /**
169     * Setter to specify the format of the regular expression to match.
170     *
171     * @param format the format of the regular expression to match.
172     */
173    public void setFormat(String format) {
174        this.format = format;
175    }
176
177    /**
178     * Setter to specify the message which is used to notify about violations,
179     * if empty then default (hard-coded) message is used.
180     *
181     * @param message the message to report for a match.
182     */
183    public void setMessage(String message) {
184        this.message = message;
185    }
186
187    /**
188     * Setter to specify the minimum number of matches required in each file.
189     *
190     * @param minimum the minimum number of matches required in each file.
191     */
192    public void setMinimum(int minimum) {
193        this.minimum = minimum;
194    }
195
196    /**
197     * Setter to specify the maximum number of matches required in each file.
198     *
199     * @param maximum the maximum number of matches required in each file.
200     */
201    public void setMaximum(int maximum) {
202        this.maximum = maximum;
203    }
204
205    /**
206     * Setter to control whether to ignore case when searching.
207     *
208     * @param ignoreCase whether to ignore case when searching.
209     */
210    public void setIgnoreCase(boolean ignoreCase) {
211        this.ignoreCase = ignoreCase;
212    }
213
214    /**
215     * Setter to control whether to match expressions across multiple lines.
216     *
217     * @param matchAcrossLines whether to match expressions across multiple lines.
218     */
219    public void setMatchAcrossLines(boolean matchAcrossLines) {
220        this.matchAcrossLines = matchAcrossLines;
221    }
222
223}