contrib/llvm/tools/clang/include/clang/Lex/ModuleLoader.h

   1 //===- ModuleLoader.h - Module Loader Interface -----------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 //  This file defines the ModuleLoader interface, which is responsible for
  11 //  loading named modules.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 #ifndef LLVM_CLANG_LEX_MODULELOADER_H
  16 #define LLVM_CLANG_LEX_MODULELOADER_H
  17
  18 #include "clang/Basic/LLVM.h"
  19 #include "clang/Basic/Module.h"
  20 #include "clang/Basic/SourceLocation.h"
  21 #include "llvm/ADT/ArrayRef.h"
  22 #include "llvm/ADT/PointerIntPair.h"
  23 #include "llvm/ADT/StringRef.h"
  24 #include <utility>
  25
  26 namespace clang {
  27
  28 class GlobalModuleIndex;
  29 class IdentifierInfo;
  30
  31 /// \brief A sequence of identifier/location pairs used to describe a particular
  32 /// module or submodule, e.g., std.vector.
  33 using ModuleIdPath = ArrayRef<std::pair<IdentifierInfo *, SourceLocation>>;
  34
  35 /// \brief Describes the result of attempting to load a module.
  36 class ModuleLoadResult {
  37 public:
  38   enum LoadResultKind {
  39     // We either succeeded or failed to load the named module.
  40     Normal,
  41
  42     // The module exists, but does not actually contain the named submodule.
  43     // This should only happen if the named submodule was inferred from an
  44     // umbrella directory, but not actually part of the umbrella header.
  45     MissingExpected,
  46
  47     // The module exists but cannot be imported due to a configuration mismatch.
  48     ConfigMismatch
  49   };
  50   llvm::PointerIntPair<Module *, 2, LoadResultKind> Storage;
  51
  52   ModuleLoadResult() = default;
  53   ModuleLoadResult(Module *M) : Storage(M, Normal) {}
  54   ModuleLoadResult(LoadResultKind Kind) : Storage(nullptr, Kind) {}
  55
  56   operator Module *() const { return Storage.getPointer(); }
  57
  58   /// \brief Determines whether the module, which failed to load, was
  59   /// actually a submodule that we expected to see (based on implying the
  60   /// submodule from header structure), but didn't materialize in the actual
  61   /// module.
  62   bool isMissingExpected() const { return Storage.getInt() == MissingExpected; }
  63
  64   /// \brief Determines whether the module failed to load due to a configuration
  65   /// mismatch with an explicitly-named .pcm file from the command line.
  66   bool isConfigMismatch() const { return Storage.getInt() == ConfigMismatch; }
  67 };
  68
  69 /// \brief Abstract interface for a module loader.
  70 ///
  71 /// This abstract interface describes a module loader, which is responsible
  72 /// for resolving a module name (e.g., "std") to an actual module file, and
  73 /// then loading that module.
  74 class ModuleLoader {
  75   // Building a module if true.
  76   bool BuildingModule;
  77
  78 public:
  79   explicit ModuleLoader(bool BuildingModule = false)
  80       : BuildingModule(BuildingModule) {}
  81
  82   virtual ~ModuleLoader();
  83
  84   /// \brief Returns true if this instance is building a module.
  85   bool buildingModule() const {
  86     return BuildingModule;
  87   }
  88
  89   /// \brief Flag indicating whether this instance is building a module.
  90   void setBuildingModule(bool BuildingModuleFlag) {
  91     BuildingModule = BuildingModuleFlag;
  92   }
  93
  94   /// \brief Attempt to load the given module.
  95   ///
  96   /// This routine attempts to load the module described by the given
  97   /// parameters.
  98   ///
  99   /// \param ImportLoc The location of the 'import' keyword.
 100   ///
 101   /// \param Path The identifiers (and their locations) of the module
 102   /// "path", e.g., "std.vector" would be split into "std" and "vector".
 103   ///
 104   /// \param Visibility The visibility provided for the names in the loaded
 105   /// module.
 106   ///
 107   /// \param IsInclusionDirective Indicates that this module is being loaded
 108   /// implicitly, due to the presence of an inclusion directive. Otherwise,
 109   /// it is being loaded due to an import declaration.
 110   ///
 111   /// \returns If successful, returns the loaded module. Otherwise, returns
 112   /// NULL to indicate that the module could not be loaded.
 113   virtual ModuleLoadResult loadModule(SourceLocation ImportLoc,
 114                                       ModuleIdPath Path,
 115                                       Module::NameVisibilityKind Visibility,
 116                                       bool IsInclusionDirective) = 0;
 117
 118   /// Attempt to load the given module from the specified source buffer. Does
 119   /// not make any submodule visible; for that, use loadModule or
 120   /// makeModuleVisible.
 121   ///
 122   /// \param Loc The location at which the module was loaded.
 123   /// \param ModuleName The name of the module to build.
 124   /// \param Source The source of the module: a (preprocessed) module map.
 125   virtual void loadModuleFromSource(SourceLocation Loc, StringRef ModuleName,
 126                                     StringRef Source) = 0;
 127
 128   /// \brief Make the given module visible.
 129   virtual void makeModuleVisible(Module *Mod,
 130                                  Module::NameVisibilityKind Visibility,
 131                                  SourceLocation ImportLoc) = 0;
 132
 133   /// \brief Load, create, or return global module.
 134   /// This function returns an existing global module index, if one
 135   /// had already been loaded or created, or loads one if it
 136   /// exists, or creates one if it doesn't exist.
 137   /// Also, importantly, if the index doesn't cover all the modules
 138   /// in the module map, it will be update to do so here, because
 139   /// of its use in searching for needed module imports and
 140   /// associated fixit messages.
 141   /// \param TriggerLoc The location for what triggered the load.
 142   /// \returns Returns null if load failed.
 143   virtual GlobalModuleIndex *loadGlobalModuleIndex(
 144                                                 SourceLocation TriggerLoc) = 0;
 145
 146   /// Check global module index for missing imports.
 147   /// \param Name The symbol name to look for.
 148   /// \param TriggerLoc The location for what triggered the load.
 149   /// \returns Returns true if any modules with that symbol found.
 150   virtual bool lookupMissingImports(StringRef Name,
 151                                     SourceLocation TriggerLoc) = 0;
 152
 153   bool HadFatalFailure = false;
 154 };
 155
 156 /// A module loader that doesn't know how to load modules.
 157 class TrivialModuleLoader : public ModuleLoader {
 158 public:
 159   ModuleLoadResult loadModule(SourceLocation ImportLoc, ModuleIdPath Path,
 160                               Module::NameVisibilityKind Visibility,
 161                               bool IsInclusionDirective) override {
 162     return {};
 163   }
 164
 165   void loadModuleFromSource(SourceLocation ImportLoc, StringRef ModuleName,
 166                             StringRef Source) override {}
 167
 168   void makeModuleVisible(Module *Mod, Module::NameVisibilityKind Visibility,
 169                          SourceLocation ImportLoc) override {}
 170
 171   GlobalModuleIndex *loadGlobalModuleIndex(SourceLocation TriggerLoc) override {
 172     return nullptr;
 173   }
 174
 175   bool lookupMissingImports(StringRef Name,
 176                             SourceLocation TriggerLoc) override {
 177     return false;
 178   }
 179 };
 180
 181 } // namespace clang
 182
 183 #endif // LLVM_CLANG_LEX_MODULELOADER_H