[FileCheck] Add ability to match newline characters

[jhenderson]

Summary

Currently there is no way using FileCheck to match an explicit newline character. Using, for example, the pattern "{{\n}}" matches an 'n' character, not '\n' (nor for that matter the string "\n"). The current suggested method of using [[:space:]] matches all forms of whitespace, so may not be always suitable.

This change coverts the pattern "\n" into a single '\n' character for use by the regex matcher, within regular expression patterns, if the new switch "--match-new-line-characters" is specified. Backslashes preceding 'n' characters can be escaped using double backslashes, if necessary.

I considered putting this change in without the switch. However, in that case FileCheck's behaviour when presented with the string "a\nnewline" would be different to grep's, which matches "annewline" in this case. I'm not sure that this is desirable.

[jhenderson]

Ping!

[dsanders]

Currently there is no way using FileCheck to match an explicit newline character. Using,
for example, the pattern "{{\n}}" matches an 'n' character, not '\n' (nor for that matter the
string "\n"). The current suggested method of using [[:space:]] matches all forms of
whitespace, so may not be always suitable.

Does this kind of pattern work on Windows? That OS uses CRLF (\r\n) for line endings and will probably fail to match patterns that explicitly check for \n.

Does something like this achieve the effect you need?:

// CHECK: foo{{$}}
// CHECK-NEXT: {{^}}bar

[jhenderson]

In D29122#673328, @dsanders wrote:

Currently there is no way using FileCheck to match an explicit newline character. Using,
for example, the pattern "{{\n}}" matches an 'n' character, not '\n' (nor for that matter the
string "\n"). The current suggested method of using [[:space:]] matches all forms of
whitespace, so may not be always suitable.

Does this kind of pattern work on Windows? That OS uses CRLF (\r\n) for line endings and will probably fail to match patterns that explicitly check for \n.

Yes, FileCheck normalises line endings to '\n'. In fact, all my development on this was done on Windows, so I'm more confident about that side than the Linux side!

Does something like this achieve the effect you need?:

// CHECK: foo{{$}}
// CHECK-NEXT: {{^}}bar

Unfortunately, this isn't sufficient for our use case. FileCheck doesn't provide a method for the matching explicit blank lines, due to the way the checks work. If the previous check matches to the end of a line, e.g. foo\n\nbar becomes \n\nbar in the buffer after matching foo{{$}}. A "CHECK-NEXT: {{^$}}" will then match immediately, but be treated as on the same line, causing an error. @probinson suggested an alternative method in D28896 which would work, but is not particularly clear, whereas I think a "CHECK: abc{{\n\n}}def" would be quite clear. It also reduces the need of using {{$}} and {{^}} repeatedly, if exact matches are desired.

[dsanders]

In D29122#673436, @jhenderson wrote:

In D29122#673328, @dsanders wrote:

Currently there is no way using FileCheck to match an explicit newline character. Using,
for example, the pattern "{{\n}}" matches an 'n' character, not '\n' (nor for that matter the
string "\n"). The current suggested method of using [[:space:]] matches all forms of
whitespace, so may not be always suitable.

Does this kind of pattern work on Windows? That OS uses CRLF (\r\n) for line endings and will probably fail to match patterns that explicitly check for \n.

Yes, FileCheck normalises line endings to '\n'. In fact, all my development on this was done on Windows, so I'm more confident about that side than the Linux side!

:-)

Does something like this achieve the effect you need?:

// CHECK: foo{{$}}
// CHECK-NEXT: {{^}}bar

Unfortunately, this isn't sufficient for our use case. FileCheck doesn't provide a method for the matching explicit blank lines, due to the way the checks work. If the previous check matches to the end of a line, e.g. foo\n\nbar becomes \n\nbar in the buffer after matching foo{{$}}. A "CHECK-NEXT: {{^$}}" will then match immediately, but be treated as on the same line, causing an error. @probinson suggested an alternative method in D28896 which would work, but is not particularly clear, whereas I think a "CHECK: abc{{\n\n}}def" would be quite clear. It also reduces the need of using {{$}} and {{^}} repeatedly, if exact matches are desired.

Thanks, I see the problem now. I believe CHECK-NEXT would work as expected if it ate a single leading newline (when present) before attempting the match. That way 'CHECK-NEXT: {{^$}}' would successfully match on the next line. I wouldn't normally be keen on a special case like that but I'd be surprised if anyone would use CHECK-NEXT and {{^}} together and want it to fail on a single leading newline.

The main reason I'm suggesting this as an alternative is because I think that if we're going to support '\n', the right place to do it would be inside llvm::Regex's engine (guarded by a flag). Having had a quick look at that, I wouldn't want to modify it (and more to the point, re-test it) if it can be avoided.

docs/CommandGuide/FileCheck.rst

.. option:: --implicit-check-not check-pattern
   checks. The option allows writing stricter tests without stuffing them with
   ``CHECK-NOT``\ s.
 
   For example, "``--implicit-check-not warning:``" can be useful when testing
   diagnostic messages from tools that don't have an option similar to ``clang
   -verify``. With this option FileCheck will verify that input does not contain
   warnings not covered by any ``CHECK:`` patterns.
 
+.. option:: --match-new-line-characters
+
+  When this option is specified, the string ``\n`` in regular expression
+  patterns matches newline characters.
+
 .. option:: -version
 
  Show the version number of this program.
 
 EXIT STATUS
 -----------
 
 If :program:`FileCheck` verifies that the file matches the expected contents,

 
 .. code-block:: c++
 
    // CHECK: test.cpp:[[@LINE+4]]:6: error: expected ';' after top level declarator
    // CHECK-NEXT: {{^int a}}
    // CHECK-NEXT: {{^     \^}}
    // CHECK-NEXT: {{^     ;}}
    int a
-
-Matching Newline Characters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To match newline characters in regular expressions the character class
-``[[:space:]]`` can be used. For example, the following pattern:
-
-.. code-block:: c++
-
-   // CHECK: DW_AT_location [DW_FORM_sec_offset] ([[DLOC:0x[0-9a-f]+]]){{[[:space:]].*}}"intd"
-
-matches output of the form (from llvm-dwarfdump):
-
-.. code-block:: text
-
-       DW_AT_location [DW_FORM_sec_offset]   (0x00000233)
-       DW_AT_name [DW_FORM_strp]  ( .debug_str[0x000000c9] = "intd")
-
-letting us set the :program:`FileCheck` variable ``DLOC`` to the desired value 
-``0x00000233``, extracted from the line immediately preceding "``intd``".

test/FileCheck/explicit-newlines.txt

+; Test that a literal new line only matches if switch is specified
+; RUN: not FileCheck %s -input-file=%s -check-prefix=NEWLINE
+; RUN: FileCheck %s -input-file=%s -check-prefix=NEWLINE -match-new-line-characters
+; NEWLINE: a{{\n}}newline
+a
+newline
+
+; Test that backslash escape behaviour functions correctly before 'n'
+; RUN: FileCheck %s -input-file=%s -check-prefix=BACKSLASHES
+; RUN: FileCheck %s -input-file=%s -check-prefix=BACKSLASHES -match-new-line-characters
+; BACKSLASHES: {{^\\n}}
+; BACKSLASHES: {{^\\\\n}}
+\n
+\\n
+
+; RUN: not FileCheck %s -input-file=%s -check-prefix=ODDSLASH
+; RUN: FileCheck %s -input-file=%s -check-prefix=ODDSLASH -match-new-line-characters
+; ODDSLASH: the{{\\\n}}next line
+the\
+next line

utils/FileCheck/FileCheck.cpp

cl::desc("Allow the input file to be empty. This is useful when making\n"
              "checks that some error message does not occur, for example."));
 
 static cl::opt<bool> MatchFullLines(
     "match-full-lines", cl::init(false),
     cl::desc("Require all positive matches to cover an entire input line.\n"
              "Allows leading and trailing whitespace if --strict-whitespace\n"
              "is not also passed."));
 
+static cl::opt<bool>
+    MatchNewLineChars("match-new-line-characters", cl::init(false),
+                      cl::desc("Treats \"\\n\" in regular expression patterns "
+                               "as a literal newline character."));
+
 typedef cl::list<std::string>::const_iterator prefix_iterator;
 
 //===----------------------------------------------------------------------===//
 // Pattern Handling Code.
 //===----------------------------------------------------------------------===//
 
 namespace Check {
 enum CheckType {
private:
   void AddBackrefToRegEx(unsigned BackrefNum);
   unsigned
   ComputeMatchDistance(StringRef Buffer,
                        const StringMap<StringRef> &VariableTable) const;
   bool EvaluateExpression(StringRef Expr, std::string &Value) const;
   size_t FindRegexVarEnd(StringRef Str, SourceMgr &SM);
 };
 
+/// Converts instances of the substring "\n" into a literal '\n'. \p PatternStr
+/// is the string to modify. Returns the modified string.
+std::string ParseNewLineCharacters(StringRef PatternStr) {
+  std::string ParsedStr;
+  std::size_t Prev = 0;
+  std::size_t Size = PatternStr.size();
+  for (std::size_t Pos = 0; Pos < Size; ++Pos) {
+    if (PatternStr[Pos] != '\\' || Pos + 1 == Size ||
+        (PatternStr[Pos + 1] != '\\' && PatternStr[Pos + 1] != 'n')) {
+      continue;
+    }
+
+    ParsedStr += PatternStr.substr(Prev, Pos - Prev);
+    // We explicitly skip over pairs of backslashes, so that the second '\' in
+    // "\\n" does not get used to form a newline character.
+    if (PatternStr[Pos + 1] == '\\')
+      ParsedStr += "\\\\";
+    else
+      ParsedStr += '\n';
+
+    ++Pos;
+    Prev = Pos + 1;
+  }
+
+  ParsedStr += PatternStr.substr(Prev, Size - Prev);
+  return ParsedStr;
+}
+
 /// Parses the given string into the Pattern.
 ///
 /// \p Prefix provides which prefix is being matched, \p SM provides the
 /// SourceMgr used for error reports, and \p LineNumber is the line number in
 /// the input file from which the pattern string was read. Returns true in
 /// case of an error, false otherwise.
 bool Pattern::ParsePattern(StringRef PatternStr, StringRef Prefix,
                            SourceMgr &SM, unsigned LineNumber) {
if (PatternStr.startswith("{{")) {
 
       // Enclose {{}} patterns in parens just like [[]] even though we're not
       // capturing the result for any purpose.  This is required in case the
       // expression contains an alternation like: CHECK:  abc{{x|z}}def.  We
       // want this to turn into: "abc(x|z)def" not "abcx|zdef".
       RegExStr += '(';
       ++CurParen;
 
-      if (AddRegExToRegEx(PatternStr.substr(2, End - 2), CurParen, SM))
+      std::string ParsedStr = PatternStr.substr(2, End - 2);
+      if (MatchNewLineChars)
+        ParsedStr = ParseNewLineCharacters(ParsedStr);
+
+      if (AddRegExToRegEx(ParsedStr, CurParen, SM))
         return true;
       RegExStr += ')';
 
       PatternStr = PatternStr.substr(End + 2);
       continue;
     }
 
     // Named RegEx matches.  These are of two forms: [[foo:.*]] which matches .*