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