Index: llvm/trunk/include/llvm/Support/FileCheck.h =================================================================== --- llvm/trunk/include/llvm/Support/FileCheck.h +++ llvm/trunk/include/llvm/Support/FileCheck.h @@ -52,7 +52,7 @@ /// variable. explicit FileCheckNumExpr(uint64_t Value) : Value(Value) {} - /// Return the value being matched against. + /// \returns the value being matched against. uint64_t getValue() const { return Value; } }; @@ -95,22 +95,22 @@ : Context(Context), IsNumExpr(true), FromStr(Expr), NumExpr(NumExpr), InsertIdx(InsertIdx) {} - /// Return whether this is a numeric expression substitution. + /// \returns whether this is a numeric expression substitution. bool isNumExpr() const { return IsNumExpr; } - /// Return the string to be substituted. + /// \returns the string to be substituted. StringRef getFromString() const { return FromStr; } - /// Return the index where the substitution is to be performed. + /// \returns the index where the substitution is to be performed. size_t getIndex() const { return InsertIdx; } - /// Return the result of the substitution represented by this class instance - /// or None if substitution failed. For a numeric expression we substitute it - /// by its value. For a pattern variable we simply replace it by the text its - /// definition matched. + /// \returns the result of the substitution represented by this class + /// instance or None if substitution failed. For a numeric expression we + /// substitute it by its value. For a pattern variable we simply replace it + /// by the text its definition matched. llvm::Optional getResult() const; - /// Return the name of the undefined variable used in this substitution, if + /// \returns the name of the undefined variable used in this substitution, if /// any, or an empty string otherwise. StringRef getUndefVarName() const; }; @@ -155,6 +155,7 @@ int getCount() const { return Count; } FileCheckType &setCount(int C); + // \returns a description of \p Prefix. std::string getDescription(StringRef Prefix) const; }; } // namespace Check @@ -180,22 +181,22 @@ std::vector> NumExprs; public: - /// Return the value of pattern variable \p VarName or None if no such + /// \returns the value of pattern variable \p VarName or None if no such /// variable has been defined. llvm::Optional getPatternVarValue(StringRef VarName); - /// Define pattern variables from definitions given on the command line, - /// passed as a vector of VAR=VAL strings in \p CmdlineDefines. Report any - /// error to \p SM and return whether an error occured. + /// Defines pattern variables from definitions given on the command line, + /// passed as a vector of VAR=VAL strings in \p CmdlineDefines. Reports any + /// error to \p SM and \returns whether an error occured. bool defineCmdlineVariables(std::vector &CmdlineDefines, SourceMgr &SM); - /// Undefine local variables (variables whose name does not start with a '$' - /// sign), i.e. remove them from GlobalVariableTable. + /// Undefines local variables (variables whose name does not start with a '$' + /// sign), i.e. removes them from GlobalVariableTable. void clearLocalVars(); private: - /// Make a new numeric expression instance and register it for destruction + /// Makes a new numeric expression instance and registers it for destruction /// when the context is destroyed. template FileCheckNumExpr *makeNumExpr(Types... Args); }; @@ -246,31 +247,50 @@ FileCheckPatternContext *Context) : Context(Context), CheckTy(Ty) {} - /// Returns the location in source code. + /// \returns the location in source code. SMLoc getLoc() const { return PatternLoc; } - /// Returns the pointer to the global state for all patterns in this + /// \returns the pointer to the global state for all patterns in this /// FileCheck instance. FileCheckPatternContext *getContext() const { return Context; } - /// Return whether \p is a valid first character for a variable name. + /// \returns whether \p C is a valid first character for a variable name. static bool isValidVarNameStart(char C); - /// Verify that the string at the start of \p Str is a well formed variable. - /// Return false if it is and set \p IsPseudo to indicate if it is a pseudo - /// variable and \p TrailIdx to the position of the last character that is - /// part of the variable name. Otherwise, only return true. + /// Verifies that the string at the start of \p Str is a well formed + /// variable. \returns false if it is and sets \p IsPseudo to indicate if it + /// is a pseudo variable and \p TrailIdx to the position of the last + /// character that is part of the variable name. Otherwise, only + /// \returns true. static bool parseVariable(StringRef Str, bool &IsPseudo, unsigned &TrailIdx); - /// Parse a numeric expression involving pseudo variable \p Name with the + /// Parses a numeric expression involving pseudo variable \p Name with the /// string corresponding to the operation being performed in \p Trailer. - /// Return the class representing the numeric expression or nullptr if + /// \returns the class representing the numeric expression or nullptr if /// parsing fails in which case errors are reported on \p SM. FileCheckNumExpr *parseNumericExpression(StringRef Name, StringRef Trailer, const SourceMgr &SM) const; + /// Parses the pattern in \p PatternStr and initializes this FileCheckPattern + /// instance accordingly. + /// + /// \p Prefix provides which prefix is being matched, \p Req describes the + /// global options that influence the parsing such as whitespace + /// canonicalization, \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 ParsePattern(StringRef PatternStr, StringRef Prefix, SourceMgr &SM, unsigned LineNumber, const FileCheckRequest &Req); + /// Matches the pattern string against the input buffer \p Buffer + /// + /// \returns the position that is matched or npos if there is no match. If + /// there is a match, updates \p MatchLen with the size of the matched + /// string. + /// + /// The GlobalVariableTable StringMap in the FileCheckPatternContext class + /// instance provides the current values of FileCheck pattern variables and + /// is updated if this match defines new values. size_t match(StringRef Buffer, size_t &MatchLen) const; - /// Print value of successful substitutions or name of undefined pattern or - /// numeric variables preventing such a successful substitution. + /// Prints the value of successful substitutions or the name of the undefined + /// pattern or numeric variable preventing such a successful substitution. void printSubstitutions(const SourceMgr &SM, StringRef Buffer, SMRange MatchRange = None) const; void printFuzzyMatch(const SourceMgr &SM, StringRef Buffer, @@ -287,7 +307,16 @@ private: bool AddRegExToRegEx(StringRef RS, unsigned &CurParen, SourceMgr &SM); void AddBackrefToRegEx(unsigned BackrefNum); + /// Computes an arbitrary estimate for the quality of matching this pattern + /// at the start of \p Buffer; a distance of zero should correspond to a + /// perfect match. unsigned computeMatchDistance(StringRef Buffer) const; + /// Finds the closing sequence of a regex variable usage or definition. + /// + /// \p Str has to point in the beginning of the definition (right after the + /// opening sequence). \p SM holds the SourceMgr used for error repporting. + /// \returns the offset of the closing sequence within Str, or npos if it + /// was not found. size_t FindRegexVarEnd(StringRef Str, SourceMgr &SM); }; @@ -366,16 +395,25 @@ FileCheckString(const FileCheckPattern &P, StringRef S, SMLoc L) : Pat(P), Prefix(S), Loc(L) {} + /// Matches check string and its "not strings" and/or "dag strings". size_t Check(const SourceMgr &SM, StringRef Buffer, bool IsLabelScanMode, size_t &MatchLen, FileCheckRequest &Req, std::vector *Diags) const; + /// Verifies that there is a single line in the given \p Buffer. Errors are + /// reported against \p SM. bool CheckNext(const SourceMgr &SM, StringRef Buffer) const; + /// Verifies that there is no newline in the given \p Buffer. Errors are + /// reported against \p SM. bool CheckSame(const SourceMgr &SM, StringRef Buffer) const; + /// Verifies that none of the strings in \p NotStrings are found in the given + /// \p Buffer. Errors are reported against \p SM and diagnostics recorded in + /// \p Diags according to the verbosity level set in \p Req. bool CheckNot(const SourceMgr &SM, StringRef Buffer, const std::vector &NotStrings, const FileCheckRequest &Req, std::vector *Diags) const; + /// Matches "dag strings" and their mixed "not strings". size_t CheckDag(const SourceMgr &SM, StringRef Buffer, std::vector &NotStrings, const FileCheckRequest &Req, @@ -398,24 +436,27 @@ // library. Regex buildCheckPrefixRegex(); - /// Read the check file, which specifies the sequence of expected strings. + /// Reads the check file from \p Buffer and records the expected strings it + /// contains in the \p CheckStrings vector. Errors are reported against + /// \p SM. /// - /// The strings are added to the CheckStrings vector. Returns true in case of - /// an error, false otherwise. + /// Only expected strings whose prefix is one of those listed in \p PrefixRE + /// are recorded. \returns true in case of an error, false otherwise. bool ReadCheckFile(SourceMgr &SM, StringRef Buffer, Regex &PrefixRE, std::vector &CheckStrings); bool ValidateCheckPrefixes(); - /// Canonicalize whitespaces in the file. Line endings are replaced with + /// Canonicalizes whitespaces in the file. Line endings are replaced with /// UNIX-style '\n'. StringRef CanonicalizeFile(MemoryBuffer &MB, SmallVectorImpl &OutputBuffer); - /// Check the input to FileCheck provided in the \p Buffer against the \p - /// CheckStrings read from the check file. + /// Checks the input to FileCheck provided in the \p Buffer against the + /// \p CheckStrings read from the check file and record diagnostics emitted + /// in \p Diags. Errors are recorded against \p SM. /// - /// Returns false if the input fails to satisfy the checks. + /// \returns false if the input fails to satisfy the checks. bool CheckInput(SourceMgr &SM, StringRef Buffer, ArrayRef CheckStrings, std::vector *Diags = nullptr); Index: llvm/trunk/lib/Support/FileCheck.cpp =================================================================== --- llvm/trunk/lib/Support/FileCheck.cpp +++ llvm/trunk/lib/Support/FileCheck.cpp @@ -145,12 +145,6 @@ return Context->makeNumExpr(Value); } -/// 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 FileCheckPattern::ParsePattern(StringRef PatternStr, StringRef Prefix, SourceMgr &SM, unsigned LineNumber, const FileCheckRequest &Req) { @@ -377,15 +371,6 @@ RegExStr += Backref; } -/// Matches the pattern string against the input buffer \p Buffer -/// -/// This returns the position that is matched or npos if there is no match. If -/// there is a match, the size of the matched string is returned in \p -/// MatchLen. -/// -/// The GlobalVariableTable StringMap in the FileCheckPatternContext class -/// instance provides the current values of FileCheck pattern variables and is -/// updated if this match defines new values. size_t FileCheckPattern::match(StringRef Buffer, size_t &MatchLen) const { // If this is the EOF pattern, match it immediately. if (CheckTy == Check::CheckEOF) { @@ -451,9 +436,6 @@ return FullMatch.data() - Buffer.data() + MatchStartSkip; } -/// Computes an arbitrary estimate for the quality of matching this pattern at -/// the start of \p Buffer; a distance of zero should correspond to a perfect -/// match. unsigned FileCheckPattern::computeMatchDistance(StringRef Buffer) const { // Just compute the number of matching characters. For regular expressions, we // just compare against the regex itself and hope for the best. @@ -590,11 +572,6 @@ return NumExprs.back().get(); } -/// Finds the closing sequence of a regex variable usage or definition. -/// -/// \p Str has to point in the beginning of the definition (right after the -/// opening sequence). Returns the offset of the closing sequence within Str, -/// or npos if it was not found. size_t FileCheckPattern::FindRegexVarEnd(StringRef Str, SourceMgr &SM) { // Offset keeps track of the current offset within the input Str size_t Offset = 0; @@ -633,8 +610,6 @@ return StringRef::npos; } -/// Canonicalize whitespaces in the file. Line endings are replaced with -/// UNIX-style '\n'. StringRef llvm::FileCheck::CanonicalizeFile(MemoryBuffer &MB, SmallVectorImpl &OutputBuffer) { @@ -693,7 +668,6 @@ return *this; } -// Get a description of the type. std::string Check::FileCheckType::getDescription(StringRef Prefix) const { switch (Kind) { case Check::CheckNone: @@ -786,7 +760,7 @@ return Loc; } -/// Search the buffer for the first prefix in the prefix regular expression. +/// Searches the buffer for the first prefix in the prefix regular expression. /// /// This searches the buffer using the provided regular expression, however it /// enforces constraints beyond that: @@ -795,7 +769,7 @@ /// 2) The found prefix must be followed by a valid check type suffix using \c /// FindCheckType above. /// -/// Returns a pair of StringRefs into the Buffer, which combines: +/// \returns a pair of StringRefs into the Buffer, which combines: /// - the first match of the regular expression to satisfy these two is /// returned, /// otherwise an empty StringRef is returned to indicate failure. @@ -856,10 +830,6 @@ return {StringRef(), StringRef()}; } -/// Read the check file, which specifies the sequence of expected strings. -/// -/// The strings are added to the CheckStrings vector. Returns true in case of -/// an error, false otherwise. bool llvm::FileCheck::ReadCheckFile( SourceMgr &SM, StringRef Buffer, Regex &PrefixRE, std::vector &CheckStrings) { @@ -1111,7 +1081,7 @@ MatchedCount, Buffer, VerboseVerbose, Diags); } -/// Count the number of newlines in the specified range. +/// Counts the number of newlines in the specified range. static unsigned CountNumNewlinesBetween(StringRef Range, const char *&FirstNewLine) { unsigned NumNewLines = 0; @@ -1134,7 +1104,6 @@ } } -/// Match check string and its "not strings" and/or "dag strings". size_t FileCheckString::Check(const SourceMgr &SM, StringRef Buffer, bool IsLabelScanMode, size_t &MatchLen, FileCheckRequest &Req, @@ -1215,7 +1184,6 @@ return FirstMatchPos; } -/// Verify there is a single line in the given buffer. bool FileCheckString::CheckNext(const SourceMgr &SM, StringRef Buffer) const { if (Pat.getCheckTy() != Check::CheckNext && Pat.getCheckTy() != Check::CheckEmpty) @@ -1255,7 +1223,6 @@ return false; } -/// Verify there is no newline in the given buffer. bool FileCheckString::CheckSame(const SourceMgr &SM, StringRef Buffer) const { if (Pat.getCheckTy() != Check::CheckSame) return false; @@ -1278,7 +1245,6 @@ return false; } -/// Verify there's no "not strings" in the given buffer. bool FileCheckString::CheckNot( const SourceMgr &SM, StringRef Buffer, const std::vector &NotStrings, @@ -1304,7 +1270,6 @@ return false; } -/// Match "dag strings" and their mixed "not strings". size_t FileCheckString::CheckDag(const SourceMgr &SM, StringRef Buffer, std::vector &NotStrings, @@ -1459,11 +1424,6 @@ return true; } -// Combines the check prefixes into a single regex so that we can efficiently -// scan for any of the set. -// -// The semantics are that the longest-match wins which matches our regex -// library. Regex llvm::FileCheck::buildCheckPrefixRegex() { // I don't think there's a way to specify an initial value for cl::list, // so if nothing was specified, add the default @@ -1548,10 +1508,6 @@ GlobalVariableTable.erase(Var); } -/// Check the input to FileCheck provided in the \p Buffer against the \p -/// CheckStrings read from the check file. -/// -/// Returns false if the input fails to satisfy the checks. bool llvm::FileCheck::CheckInput(SourceMgr &SM, StringRef Buffer, ArrayRef CheckStrings, std::vector *Diags) {