[FileCheck] Annotate input dump (final tweaks)

[jdenny]

Summary

Apply final suggestions from probinson for this patch series plus a
few more tweaks:

• Improve various docs, for MatchType in particular.

• Rename some members of MatchType. The main problem was that the term "final match" became a misnomer when CHECK-COUNT-<N> was created.

• Split InputStartLine, etc. declarations into multiple lines.

This patch doesn't necessarily require a review, but I wanted to put it in phabricator for safe keeping while waiting for D53899 to be accepted.

[probinson]

Much better, thanks! LGTM

llvm/include/llvm/Support/FileCheck.h

 /// Summary of a FileCheck diagnostic.
 //===----------------------------------------------------------------------===//
 
 struct FileCheckDiag {
   /// What is the FileCheck directive for this diagnostic?
   Check::FileCheckType CheckTy;
   /// Where is the FileCheck directive for this diagnostic?
   unsigned CheckLine, CheckCol;
-  /// What kind of match result does this diagnostic describe?
+  /// What type of match result does this diagnostic describe?
   ///
-  /// There might be more than one of these for the same directive.  For
-  /// example, there might be several discards before either a final or fail,
-  /// and there might be a fuzzy match after a fail.
+  /// A directive's supplied pattern is said to be either expected or excluded
+  /// depending on whether the pattern must have or must not have a match in
+  /// order for the directive to succeed.  For example, a CHECK directive's
+  /// pattern is expected, and a CHECK-NOT directive's pattern is excluded.
+  /// All match result types whose names end with "Excluded" are for excluded
+  /// patterns, and all others are for expected patterns.
+  ///
+  /// There might be more than one match result for a single pattern.  For
+  /// example, there might be several discarded matches
+  /// (MatchFoundButDiscarded) before either a good match
+  /// (MatchFoundAndExpected) or a failure to match (MatchNoneButExpected),
+  /// and there might be a fuzzy match (MatchFuzzy) after the latter.
   enum MatchType {
-    // TODO: More members will appear with later patches in this series.
-    /// Indicates the final match for an expected pattern.
-    MatchFinalAndExpected,
-    /// Indicates the final match for an excluded pattern.
-    MatchFinalButExcluded,
-    /// Indicates the final match for an expected pattern, but the match is on
-    /// the wrong line.
-    MatchFinalButWrongLine,
+    /// Indicates a good match for an expected pattern.
+    MatchFoundAndExpected,
+    /// Indicates a match for an excluded pattern.
+    MatchFoundButExcluded,
+    /// Indicates a match for an expected pattern, but the match is on the
+    /// wrong line.
+    MatchFoundButWrongLine,
     /// Indicates a discarded match for an expected pattern.
-    MatchDiscard,
+    MatchFoundButDiscarded,
     /// Indicates no match for an excluded pattern.
     MatchNoneAndExcluded,
-    /// Indicates no match for an expected pattern.
+    /// Indicates no match for an expected pattern, but this might follow good
+    /// matches when multiple matches are expected for the pattern, or it might
+    /// follow discarded matches for the pattern.
     MatchNoneButExpected,
-    /// Indicates a possible intended match because there's no perfect match.
+    /// Indicates a fuzzy match that serves as a suggestion for the next
+    /// intended match for an expected pattern with too few or no good matches.
     MatchFuzzy,
   } MatchTy;
-  /// The match range if MatchTy is not MatchNoneAndExcluded or
-  /// MatchNoneButExpected, or the search range otherwise.
-  unsigned InputStartLine, InputStartCol, InputEndLine, InputEndCol;
+  /// The search range if MatchTy is MatchNoneAndExcluded or
+  /// MatchNoneButExpected, or the match range otherwise.
+  unsigned InputStartLine;
+  unsigned InputStartCol;
+  unsigned InputEndLine;
+  unsigned InputEndCol;
   FileCheckDiag(const SourceMgr &SM, const Check::FileCheckType &CheckTy,
                 SMLoc CheckLoc, MatchType MatchTy, SMRange InputRange);
 };
 
 //===----------------------------------------------------------------------===//
 // Check Strings.
 //===----------------------------------------------------------------------===//
 

llvm/lib/Support/FileCheck.cpp

static void PrintMatch(bool ExpectedMatch, const SourceMgr &SM,
                        std::vector<FileCheckDiag> *Diags) {
   if (ExpectedMatch) {
     if (!Req.Verbose)
       return;
     if (!Req.VerboseVerbose && Pat.getCheckTy() == Check::CheckEOF)
       return;
   }
   SMRange MatchRange = ProcessMatchResult(
-      ExpectedMatch ? FileCheckDiag::MatchFinalAndExpected
-                    : FileCheckDiag::MatchFinalButExcluded,
+      ExpectedMatch ? FileCheckDiag::MatchFoundAndExpected
+                    : FileCheckDiag::MatchFoundButExcluded,
       SM, Loc, Pat.getCheckTy(), Buffer, MatchPos, MatchLen, Diags);
   std::string Message = formatv("{0}: {1} string found in input",
                                 Pat.getCheckTy().getDescription(Prefix),
                                 (ExpectedMatch ? "expected" : "excluded"))
                             .str();
   if (Pat.getCount() > 1)
     Message += formatv(" ({0} out of {1})", MatchedCount, Pat.getCount()).str();
 
size_t FileCheckString::Check(const SourceMgr &SM, StringRef Buffer,
   if (!IsLabelScanMode) {
     size_t MatchPos = FirstMatchPos - LastPos;
     StringRef MatchBuffer = Buffer.substr(LastPos);
     StringRef SkippedRegion = Buffer.substr(LastPos, MatchPos);
 
     // If this check is a "CHECK-NEXT", verify that the previous match was on
     // the previous line (i.e. that there is one newline between them).
     if (CheckNext(SM, SkippedRegion)) {
-      ProcessMatchResult(FileCheckDiag::MatchFinalButWrongLine, SM, Loc,
+      ProcessMatchResult(FileCheckDiag::MatchFoundButWrongLine, SM, Loc,
                          Pat.getCheckTy(), MatchBuffer, MatchPos, MatchLen,
                          Diags, Req.Verbose);
       return StringRef::npos;
     }
 
     // If this check is a "CHECK-SAME", verify that the previous match was on
     // the same line (i.e. that there is no newline between them).
     if (CheckSame(SM, SkippedRegion)) {
-      ProcessMatchResult(FileCheckDiag::MatchFinalButWrongLine, SM, Loc,
+      ProcessMatchResult(FileCheckDiag::MatchFoundButWrongLine, SM, Loc,
                          Pat.getCheckTy(), MatchBuffer, MatchPos, MatchLen,
                          Diags, Req.Verbose);
       return StringRef::npos;
     }
 
     // If this match had "not strings", verify that they don't exist in the
     // skipped region.
     if (CheckNot(SM, SkippedRegion, NotStrings, VariableTable, Req, Diags))
for (auto MI = MatchRanges.begin(), ME = MatchRanges.end(); true; ++MI) {
       if (Req.VerboseVerbose) {
         SMLoc OldStart = SMLoc::getFromPointer(Buffer.data() + MI->Pos);
         SMLoc OldEnd = SMLoc::getFromPointer(Buffer.data() + MI->End);
         SMRange OldRange(OldStart, OldEnd);
         SM.PrintMessage(OldStart, SourceMgr::DK_Note,
                         "match discarded, overlaps earlier DAG match here",
                         {OldRange});
         if (Diags)
-          Diags->rbegin()->MatchTy = FileCheckDiag::MatchDiscard;
+          Diags->rbegin()->MatchTy = FileCheckDiag::MatchFoundButDiscarded;
       }
       MatchPos = MI->End;
     }
     if (!Req.VerboseVerbose)
       PrintMatch(true, SM, Prefix, Pat.getLoc(), Pat, 1, Buffer, VariableTable,
                  MatchPos, MatchLen, Req, Diags);
 
     // Handle the end of a CHECK-DAG group.

llvm/test/FileCheck/dump-input-annotations.txt

 ; RUN: echo 'def' >> %t.in
 ; RUN: echo 'abc' >> %t.in
 
 ; RUN: echo 'CHECK-DAG: def' > %t.chk
 ; RUN: echo 'CHECK-DAG: abc' >> %t.chk
 ; RUN: echo 'CHECK-DAG: abc' >> %t.chk
 ; RUN: echo 'CHECK-DAG: def' >> %t.chk
 
+; Prefixes used here:
+; DAG    = quiet, -v, or -vv
+; DAG-V  = -v or -vv
+; DAG-VQ = -v only
+; DAG-VV = -vv only
+
 ; RUN: not FileCheck -dump-input=always -input-file %t.in %t.chk 2>&1 \
 ; RUN: | FileCheck -match-full-lines %s -check-prefixes=DAG,DAG-Q
 ; RUN: not FileCheck -dump-input=always -input-file %t.in %t.chk -v 2>&1 \
 ; RUN: | FileCheck -match-full-lines %s -check-prefixes=DAG,DAG-V,DAG-VQ
 ; RUN: not FileCheck -dump-input=always -input-file %t.in %t.chk -vv 2>&1 \
 ; RUN: | FileCheck -match-full-lines %s -check-prefixes=DAG,DAG-V,DAG-VV
 
 ; DAG:         <<<<<<

llvm/utils/FileCheck/FileCheck.cpp

struct MarkerStyle {
   MarkerStyle() {}
   MarkerStyle(char Lead, raw_ostream::Colors Color,
               const std::string &Note = "")
       : Lead(Lead), Color(Color), Note(Note) {}
 };
 
 static MarkerStyle GetMarker(FileCheckDiag::MatchType MatchTy) {
   switch (MatchTy) {
-  case FileCheckDiag::MatchFinalAndExpected:
+  case FileCheckDiag::MatchFoundAndExpected:
     return MarkerStyle('^', raw_ostream::GREEN);
-  case FileCheckDiag::MatchFinalButExcluded:
+  case FileCheckDiag::MatchFoundButExcluded:
     return MarkerStyle('!', raw_ostream::RED, "error: no match expected");
-  case FileCheckDiag::MatchFinalButWrongLine:
+  case FileCheckDiag::MatchFoundButWrongLine:
     return MarkerStyle('!', raw_ostream::RED, "error: match on wrong line");
-  case FileCheckDiag::MatchDiscard:
+  case FileCheckDiag::MatchFoundButDiscarded:
     return MarkerStyle('!', raw_ostream::CYAN,
                        "discard: overlaps earlier match");
   case FileCheckDiag::MatchNoneAndExcluded:
     return MarkerStyle('X', raw_ostream::GREEN);
   case FileCheckDiag::MatchNoneButExpected:
     return MarkerStyle('X', raw_ostream::RED, "error: no match found");
   case FileCheckDiag::MatchFuzzy:
     return MarkerStyle('?', raw_ostream::MAGENTA, "possible intended match");
struct InputAnnotation {
   /// multiple lines.
   unsigned InputLine;
   /// The column range (one-origin indexing, open end) in which to to mark the
   /// input line.  If InputEndCol is UINT_MAX, treat it as the last column
   /// before the newline.
   unsigned InputStartCol, InputEndCol;
   /// The marker to use.
   MarkerStyle Marker;
-  /// Whether this annotation represents a final match for an expected pattern.
-  bool FinalAndExpectedMatch;
+  /// Whether this annotation represents a good match for an expected pattern.
+  bool FoundAndExpectedMatch;
 };
 
 /// Get an abbreviation for the check type.
 std::string GetCheckTypeAbbreviation(Check::FileCheckType Ty) {
   switch (Ty) {
   case Check::CheckPlain:
     if (Ty.getCount() > 1)
       return "count";
if (A.CheckDiagIndex != UINT_MAX)
       Label << "'" << A.CheckDiagIndex;
     else
       A.CheckDiagIndex = 0;
     Label.flush();
     LabelWidth = std::max((std::string::size_type)LabelWidth, A.Label.size());
 
     MarkerStyle Marker = GetMarker(DiagItr->MatchTy);
     A.Marker = Marker;
-    A.FinalAndExpectedMatch =
-        DiagItr->MatchTy == FileCheckDiag::MatchFinalAndExpected;
+    A.FoundAndExpectedMatch =
+        DiagItr->MatchTy == FileCheckDiag::MatchFoundAndExpected;
 
     // Compute the mark location, and break annotation into multiple
     // annotations if it spans multiple lines.
     A.InputLine = DiagItr->InputStartLine;
     A.InputStartCol = DiagItr->InputStartCol;
     if (DiagItr->InputStartLine == DiagItr->InputEndLine) {
       // Sometimes ranges are empty in order to indicate a specific point, but
       // that would mean nothing would be marked, so adjust the range to
if (DiagItr->InputStartLine == DiagItr->InputEndLine) {
         B.Marker = Marker;
         B.Marker.Lead = '~';
         B.InputStartCol = 1;
         if (L != E) {
           B.InputEndCol = UINT_MAX;
           B.Marker.Note = "";
         } else
           B.InputEndCol = DiagItr->InputEndCol;
-        B.FinalAndExpectedMatch = A.FinalAndExpectedMatch;
+        B.FoundAndExpectedMatch = A.FoundAndExpectedMatch;
         Annotations.push_back(B);
       }
     }
   }
 }
 
 static void DumpAnnotatedInput(raw_ostream &OS, const FileCheckRequest &Req,
                                StringRef InputFileText,
for (unsigned Line = 1;
        InputFilePtr != InputFileEnd || AnnotationItr != AnnotationEnd;
        ++Line) {
     const unsigned char *InputFileLine = InputFilePtr;
 
     // Print right-aligned line number.
     WithColor(OS, raw_ostream::BLACK, true)
         << format_decimal(Line, LabelWidth) << ": ";
 
-    // For case where -v and colors are enabled, find the annotations for final
-    // matches for expected patterns in order to highlight everything else in
-    // the line.  There are no such annotations if -v is disabled.
-    std::vector<InputAnnotation> FinalAndExpectedMatches;
+    // For the case where -v and colors are enabled, find the annotations for
+    // good matches for expected patterns in order to highlight everything
+    // else in the line.  There are no such annotations if -v is disabled.
+    std::vector<InputAnnotation> FoundAndExpectedMatches;
     if (Req.Verbose && WithColor(OS).colorsEnabled()) {
       for (auto I = AnnotationItr; I != AnnotationEnd && I->InputLine == Line;
            ++I) {
-        if (I->FinalAndExpectedMatch)
-          FinalAndExpectedMatches.push_back(*I);
+        if (I->FoundAndExpectedMatch)
+          FoundAndExpectedMatches.push_back(*I);
       }
     }
 
     // Print numbered line with highlighting where there are no matches for
     // expected patterns.
     bool Newline = false;
     {
       WithColor COS(OS);
       bool InMatch = false;
       if (Req.Verbose)
         COS.changeColor(raw_ostream::CYAN, true, true);
       for (unsigned Col = 1; InputFilePtr != InputFileEnd && !Newline; ++Col) {
         bool WasInMatch = InMatch;
         InMatch = false;
-        for (auto M : FinalAndExpectedMatches) {
+        for (auto M : FoundAndExpectedMatches) {
           if (M.InputStartCol <= Col && Col < M.InputEndCol) {
             InMatch = true;
             break;
           }
         }
         if (!WasInMatch && InMatch)
           COS.resetColor();
         else if (WasInMatch && !InMatch)