//===--- iwyu_location_util.h - SourceLoc-related utilities for iwyu ------===//

//

// The LLVM Compiler Infrastructure

//

// This file is distributed under the University of Illinois Open Source

// License. See LICENSE.TXT for details.

//

//===----------------------------------------------------------------------===//

// clang-File utilities for the IWYU checker.

//

// This file deals with clang's FileEntry and SourceLocation classes,

// and useful utilities on them. It does not deal with file paths

// per se; for that, see iwyu_path_util.h

//

// In addition to some ad hoc helper routines, in general, for every

// type we consider, we try to provide 3 routines (as appropriate):

// GetLocation(): convert the object to an appropriate SourceLocation

// GetFileEntry(): convert the object to the file it's in

// GetFilePath(): convert the object to the filename it's in

//

//

// Background on Clang data structures:

//

// Clang uses the type FileEntry to identify a physical file in the

// file system. A FileEntry is created for each source file Clang

// processes. Clang never creates two FileEntry objects for the same

// file, so FileEntry objects have pointer identity. Clang wraps

// FileEntry in a couple of stronger types with similar semantics

// (FileEntryRef and OptionalFileEntryRef). We use these wrappers

// as file identities in IWYU.

//

// Clang's FileID type is a misnomer. It's actually an ID of a

// particular #include statement. If a file is #included in two

// places, it will have two different FildIDs.

//

// A SourceLocation is a compact encoding of a location in a

// particular #include of a source file. From it you can find the

// file path, line number, column number, and which file (if any)

// #includes the file.

#ifndef INCLUDE_WHAT_YOU_USE_IWYU_LOCATION_UTIL_H_

#define INCLUDE_WHAT_YOU_USE_IWYU_LOCATION_UTIL_H_

#include <optional>

#include <string> // for string

#include "clang/Basic/FileEntry.h"

#include "clang/Basic/SourceLocation.h"

#include "clang/Basic/SourceManager.h"

#include "clang/Lex/Token.h"

#include "iwyu_globals.h"

#include "iwyu_path_util.h"

#include "llvm/ADT/StringRef.h"

namespace clang {

class Decl;

class NestedNameSpecifierLoc;

class Stmt;

class TemplateArgumentLoc;

class TypeLoc;

} // namespace clang

namespace include_what_you_use {

using std::string;

//------------------------------------------------------------

// Helper functions for FileEntry.

inline const clang::FileEntry* RawFileEntry(clang::OptionalFileEntryRef file) {

if (!file) {

return nullptr;

}

return &file->getFileEntry();

}

// When macro args are concatenated e.g. '#define CAT(A, B) A##B', their

// location ends up outside the source text, in what the compiler calls

// "<scratch space>".

// This function returns true if the provided loc is in scratch space.

bool IsInScratchSpace(clang::SourceLocation loc);

// Resolve canonical file path from various file entry types.

inline string GetFilePath(clang::OptionalFileEntryRef file) {

return (!file ? "<built-in>" : NormalizeFilePath(file->getName().str()));

}

inline string GetFilePath(clang::FileEntryRef file) {

return NormalizeFilePath(file.getName().str());

}

//------------------------------------------------------------

// Helper functions for SourceLocation

inline clang::SourceLocation GetSpellingLoc(clang::SourceLocation loc) {

return loc.isValid() ? GlobalSourceManager()->getSpellingLoc(loc) : loc;

}

inline clang::SourceLocation GetInstantiationLoc(clang::SourceLocation loc) {

return loc.isValid() ? GlobalSourceManager()->getExpansionLoc(loc) : loc;

}

inline bool IsInMacro(clang::SourceLocation loc) {

return GetSpellingLoc(loc) != GetInstantiationLoc(loc);

}

// Returns the line number corresponding to a source location.

// Prefers the spelling line number, but if it's not useful (because

// the location is in <scratch space> for instance, due to macro token

// concatenation), uses the instantiation line number. Returns -1 if

// we can't figure out the line #.

inline int GetLineNumber(clang::SourceLocation loc) {

}

// The rest of this section of the file is for returning the

// FileEntry corresponding to a source location: the file that the

// location is in. This is a surprising amount of work.

// Tells which #include loc comes from.

// This is the most basic FileEntry getter, it only does a simple lookup in

// SourceManager to determine which file the location is associated with.

inline clang::OptionalFileEntryRef GetLocFileEntry(clang::SourceLocation loc) {

}

inline clang::OptionalFileEntryRef GetFileEntry(clang::SourceLocation loc) {

}

//------------------------------------------------------------

// GetFileEntry(), GetFilePath(), and GetLocation().

inline clang::SourceLocation GetLocation(const clang::Token& token) {

return token.getLocation();

}

inline clang::SourceLocation GetLocation(clang::SourceLocation loc) {

return loc; // the identity location-getter, useful with templates

}

clang::SourceLocation GetLocation(const clang::Decl* decl);

clang::SourceLocation GetLocation(const clang::Stmt* stmt);

clang::SourceLocation GetLocation(const clang::TypeLoc* typeloc);

clang::SourceLocation GetLocation(const clang::NestedNameSpecifierLoc* nnsloc);

clang::SourceLocation GetLocation(const clang::TemplateArgumentLoc* argloc);

// These define default implementations of GetFileEntry() and

// GetFilePath() in terms of GetLocation(). As long as an object defines

// its own GetLocation(), it will get these other two for free.

template <typename T>

clang::OptionalFileEntryRef GetFileEntry(const T& obj) {

return GetFileEntry(GetLocation(obj));

}

template <typename T>

const string GetFilePath(const T& obj) {

return GetFilePath(GetFileEntry(obj));

}

//------------------------------------------------------------

// Some utility, location-based routines.

// Given any two objects that have instantiation-locations, says

// whether one occurs before the other in the translation unit (using

// instantiated locations). This means that one would occur before

// the other looking at the output of cc -E or equivalent.

template<typename T, typename U>

inline bool IsBeforeInTranslationUnit(const T& a, const U& b) {

}

// Like IsBeforeInTranslationUnit, but both a and b must be

// instantiated in the same file as well.

template<typename T, typename U>

inline bool IsBeforeInSameFile(const T& a, const U& b) {

}

// Returns true if argument is one of the special files used by Clang for

// implicit buffers ("<built-in>", "<command-line>", etc).

// A null value is considered the same as "<built-in>".

inline bool IsSpecialFile(clang::OptionalFileEntryRef file) {

}

// Returns true if obj is in a special file, as defined above.

// Note that it also returns true for objects at invalid locations, as they

// resolve to a null file.

template <typename T>

inline bool IsInSpecialFile(const T& obj) {

return IsSpecialFile(GetFileEntry(obj));

}

// Returns true if the given declaration is located in a header file.

bool IsInHeader(const clang::Decl*);

// Returns true if file is a system header.

bool IsSystemHeader(clang::OptionalFileEntryRef file);

} // namespace include_what_you_use

#endif // INCLUDE_WHAT_YOU_USE_IWYU_LOCATION_UTIL_H_