Class RegexpMultilineCheck

  • All Implemented Interfaces:
    Configurable, Contextualizable, FileSetCheck

    public class RegexpMultilineCheck
    extends AbstractFileSetCheck

    Checks that a specified pattern matches across multiple lines in any file type.

    Rationale: This check can be used to when the regular expression can be span multiple lines.

    • Property format - Specify the format of the regular expression to match. Type is java.util.regex.Pattern. Default value is "$.".
    • Property message - Specify the message which is used to notify about violations, if empty then default (hard-coded) message is used. Type is java.lang.String. Default value is null.
    • Property ignoreCase - Control whether to ignore case when searching. Type is boolean. Default value is false.
    • Property minimum - Specify the minimum number of matches required in each file. Type is int. Default value is 0.
    • Property maximum - Specify the maximum number of matches required in each file. Type is int. Default value is 0.
    • Property matchAcrossLines - Control whether to match expressions across multiple lines. Type is boolean. Default value is false.
    • Property fileExtensions - Specify the file type extension of files to process. Type is java.lang.String[]. Default value is "".

    To run the check with its default configuration (no matches will be):

     <module name="RegexpMultiline"/>
     

    Example:

     void method() {
       int i = 5; // OK
       System.out.println(i); // OK
     }
     

    To configure the check to find calls to print to the console:

     <module name="RegexpMultiline">
       <property name="format" value="System\.(out)|(err)\.print(ln)?\("/>
     </module>
     

    Example:

     void method() {
       System.out.print("Example");   // violation
       System.err.println("Example"); // violation
       System.out.print
         ("Example");                 // violation
       System.err.println
         ("Example");          // OK
       System
       .out.print("Example");  // OK
       System
       .err.println("Example");       // violation
       System.
       out.print("Example");   // OK
       System.
       err.println("Example");        // violation
     }
     

    To configure the check to match text that spans multiple lines, like normal code in a Java file:

     <module name="RegexpMultiline">
       <property name="matchAcrossLines" value="true"/>
       <property name="format" value="System\.out.*?print\("/>
     </module>
     

    Example:

     void method() {
       System.out.print("Example");  // violation
       System.err.println("Example");
       System.out.print              // violation
         ("Example");
       System.err.println
         ("Example");
       System
       .out.print("Example");
       System
       .err.println("Example");
       System.
       out.print("Example");
       System.
       err.println("Example");
     }
     

    Note: Beware of the greedy regular expression used in the above example. .* will match as much as possible and not produce multiple violations in the file if multiple groups of lines could match the expression. To prevent an expression being too greedy, avoid overusing matching all text or allow it to be optional, like .*?. Changing the example expression to not be greedy will allow multiple violations in the example to be found in the same file.

    To configure the check to match a maximum of three test strings:

     <module name="RegexpMultiline">
       <property name="format" value="Test #[0-9]+:[A-Za-z ]+"/>
       <property name="ignoreCase" value="true"/>
       <property name="maximum" value="3"/>
     </module>
     

    Example:

     void method() {
       System.out.println("Test #1: this is a test string"); // OK
       System.out.println("TeSt #2: This is a test string"); // OK
       System.out.println("TEST #3: This is a test string"); // OK
       int i = 5;
       System.out.println("Value of i: " + i);
       System.out.println("Test #4: This is a test string"); // violation
       System.out.println("TEst #5: This is a test string"); // violation
     }
     

    To configure the check to match a minimum of two test strings:

     <module name="RegexpMultiline">
       <property name="format" value="Test #[0-9]+:[A-Za-z ]+"/>
       <property name="minimum" value="2"/>
     </module>
     

    Example:

     void method() {
       System.out.println("Test #1: this is a test string"); // violation
       System.out.println("TEST #2: This is a test string"); // OK, "ignoreCase" is false by default
       int i = 5;
       System.out.println("Value of i: " + i);
       System.out.println("Test #3: This is a test string"); // violation
       System.out.println("Test #4: This is a test string"); // violation
     }
     

    To configure the check to restrict an empty file:

     <module name="RegexpMultiline">
         <property name="format" value="^\s*$" />
         <property name="matchAcrossLines" value="true" />
         <property name="message" value="Empty file is not allowed" />
     </module>
     

    Example of violation from the above config:

     /var/tmp$ cat -n Test.java
     1
     2
     3
     4
     

    Result:

     /var/tmp/Test.java // violation, a file must not be empty.
     

    Parent is com.puppycrawl.tools.checkstyle.Checker

    Violation Message Keys:

    • regexp.StackOverflowError
    • regexp.empty
    • regexp.exceeded
    • regexp.minimum
    Since:
    5.0
    • Field Detail

      • format

        private String format
        Specify the format of the regular expression to match.
      • message

        private String message
        Specify the message which is used to notify about violations, if empty then default (hard-coded) message is used.
      • minimum

        private int minimum
        Specify the minimum number of matches required in each file.
      • maximum

        private int maximum
        Specify the maximum number of matches required in each file.
      • ignoreCase

        private boolean ignoreCase
        Control whether to ignore case when searching.
      • matchAcrossLines

        private boolean matchAcrossLines
        Control whether to match expressions across multiple lines.
    • Method Detail

      • getRegexCompileFlags

        private int getRegexCompileFlags()
        Retrieves the compile-flags for the regular expression being built based on matchAcrossLines.
        Returns:
        The compile-flags.
      • setFormat

        public void setFormat​(String format)
        Setter to specify the format of the regular expression to match.
        Parameters:
        format - the format of the regular expression to match.
      • setMessage

        public void setMessage​(String message)
        Setter to specify the message which is used to notify about violations, if empty then default (hard-coded) message is used.
        Parameters:
        message - the message to report for a match.
      • setMinimum

        public void setMinimum​(int minimum)
        Setter to specify the minimum number of matches required in each file.
        Parameters:
        minimum - the minimum number of matches required in each file.
      • setMaximum

        public void setMaximum​(int maximum)
        Setter to specify the maximum number of matches required in each file.
        Parameters:
        maximum - the maximum number of matches required in each file.
      • setIgnoreCase

        public void setIgnoreCase​(boolean ignoreCase)
        Setter to control whether to ignore case when searching.
        Parameters:
        ignoreCase - whether to ignore case when searching.
      • setMatchAcrossLines

        public void setMatchAcrossLines​(boolean matchAcrossLines)
        Setter to control whether to match expressions across multiple lines.
        Parameters:
        matchAcrossLines - whether to match expressions across multiple lines.