1//===--- Module.h - Describe a module ---------------------------*- 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/// \file
11/// \brief Defines the clang::Module class, which describes a module in the
12/// source code.
13///
14//===----------------------------------------------------------------------===//
15#ifndef LLVM_CLANG_BASIC_MODULE_H
16#define LLVM_CLANG_BASIC_MODULE_H
17
18#include "clang/Basic/SourceLocation.h"
19#include "llvm/ADT/PointerIntPair.h"
20#include "llvm/ADT/PointerUnion.h"
21#include "llvm/ADT/SmallVector.h"
22#include "llvm/ADT/StringMap.h"
23#include "llvm/ADT/StringRef.h"
24#include <string>
25#include <utility>
26#include <vector>
27
28namespace llvm {
29  class raw_ostream;
30}
31
32namespace clang {
33
34class DirectoryEntry;
35class FileEntry;
36class LangOptions;
37class TargetInfo;
38
39/// \brief Describes the name of a module.
40typedef llvm::SmallVector<std::pair<std::string, SourceLocation>, 2>
41  ModuleId;
42
43/// \brief Describes a module or submodule.
44class Module {
45public:
46  /// \brief The name of this module.
47  std::string Name;
48
49  /// \brief The location of the module definition.
50  SourceLocation DefinitionLoc;
51
52  /// \brief The parent of this module. This will be NULL for the top-level
53  /// module.
54  Module *Parent;
55
56  /// \brief The umbrella header or directory.
57  llvm::PointerUnion<const DirectoryEntry *, const FileEntry *> Umbrella;
58
59private:
60  /// \brief The submodules of this module, indexed by name.
61  std::vector<Module *> SubModules;
62
63  /// \brief A mapping from the submodule name to the index into the
64  /// \c SubModules vector at which that submodule resides.
65  llvm::StringMap<unsigned> SubModuleIndex;
66
67public:
68  /// \brief The headers that are part of this module.
69  llvm::SmallVector<const FileEntry *, 2> Headers;
70
71  /// \brief The set of language features required to use this module.
72  ///
73  /// If any of these features is not present, the \c IsAvailable bit
74  /// will be false to indicate that this (sub)module is not
75  /// available.
76  llvm::SmallVector<std::string, 2> Requires;
77
78  /// \brief Whether this module is available in the current
79  /// translation unit.
80  unsigned IsAvailable : 1;
81
82  /// \brief Whether this module was loaded from a module file.
83  unsigned IsFromModuleFile : 1;
84
85  /// \brief Whether this is a framework module.
86  unsigned IsFramework : 1;
87
88  /// \brief Whether this is an explicit submodule.
89  unsigned IsExplicit : 1;
90
91  /// \brief Whether this is a "system" module (which assumes that all
92  /// headers in it are system headers).
93  unsigned IsSystem : 1;
94
95  /// \brief Whether we should infer submodules for this module based on
96  /// the headers.
97  ///
98  /// Submodules can only be inferred for modules with an umbrella header.
99  unsigned InferSubmodules : 1;
100
101  /// \brief Whether, when inferring submodules, the inferred submodules
102  /// should be explicit.
103  unsigned InferExplicitSubmodules : 1;
104
105  /// \brief Whether, when inferring submodules, the inferr submodules should
106  /// export all modules they import (e.g., the equivalent of "export *").
107  unsigned InferExportWildcard : 1;
108
109  /// \brief Describes the visibility of the various names within a
110  /// particular module.
111  enum NameVisibilityKind {
112    /// \brief All of the names in this module are hidden.
113    ///
114    Hidden,
115    /// \brief Only the macro names in this module are visible.
116    MacrosVisible,
117    /// \brief All of the names in this module are visible.
118    AllVisible
119  };
120
121  ///\ brief The visibility of names within this particular module.
122  NameVisibilityKind NameVisibility;
123
124  /// \brief The location of the inferred submodule.
125  SourceLocation InferredSubmoduleLoc;
126
127  /// \brief The set of modules imported by this module, and on which this
128  /// module depends.
129  llvm::SmallVector<Module *, 2> Imports;
130
131  /// \brief Describes an exported module.
132  ///
133  /// The pointer is the module being re-exported, while the bit will be true
134  /// to indicate that this is a wildcard export.
135  typedef llvm::PointerIntPair<Module *, 1, bool> ExportDecl;
136
137  /// \brief The set of export declarations.
138  llvm::SmallVector<ExportDecl, 2> Exports;
139
140  /// \brief Describes an exported module that has not yet been resolved
141  /// (perhaps because the module it refers to has not yet been loaded).
142  struct UnresolvedExportDecl {
143    /// \brief The location of the 'export' keyword in the module map file.
144    SourceLocation ExportLoc;
145
146    /// \brief The name of the module.
147    ModuleId Id;
148
149    /// \brief Whether this export declaration ends in a wildcard, indicating
150    /// that all of its submodules should be exported (rather than the named
151    /// module itself).
152    bool Wildcard;
153  };
154
155  /// \brief The set of export declarations that have yet to be resolved.
156  llvm::SmallVector<UnresolvedExportDecl, 2> UnresolvedExports;
157
158  /// \brief Construct a top-level module.
159  explicit Module(StringRef Name, SourceLocation DefinitionLoc,
160                  bool IsFramework)
161    : Name(Name), DefinitionLoc(DefinitionLoc), Parent(0), Umbrella(),
162      IsAvailable(true), IsFromModuleFile(false), IsFramework(IsFramework),
163      IsExplicit(false), IsSystem(false),
164      InferSubmodules(false), InferExplicitSubmodules(false),
165      InferExportWildcard(false), NameVisibility(Hidden) { }
166
167  /// \brief Construct a new module or submodule.
168  Module(StringRef Name, SourceLocation DefinitionLoc, Module *Parent,
169         bool IsFramework, bool IsExplicit);
170
171  ~Module();
172
173  /// \brief Determine whether this module is available for use within the
174  /// current translation unit.
175  bool isAvailable() const { return IsAvailable; }
176
177  /// \brief Determine whether this module is available for use within the
178  /// current translation unit.
179  ///
180  /// \param LangOpts The language options used for the current
181  /// translation unit.
182  ///
183  /// \param Target The target options used for the current translation unit.
184  ///
185  /// \param Feature If this module is unavailable, this parameter
186  /// will be set to one of the features that is required for use of
187  /// this module (but is not available).
188  bool isAvailable(const LangOptions &LangOpts,
189                   const TargetInfo &Target,
190                   StringRef &Feature) const;
191
192  /// \brief Determine whether this module is a submodule.
193  bool isSubModule() const { return Parent != 0; }
194
195  /// \brief Determine whether this module is a submodule of the given other
196  /// module.
197  bool isSubModuleOf(Module *Other) const;
198
199  /// \brief Determine whether this module is a part of a framework,
200  /// either because it is a framework module or because it is a submodule
201  /// of a framework module.
202  bool isPartOfFramework() const {
203    for (const Module *Mod = this; Mod; Mod = Mod->Parent)
204      if (Mod->IsFramework)
205        return true;
206
207    return false;
208  }
209
210  /// \brief Retrieve the full name of this module, including the path from
211  /// its top-level module.
212  std::string getFullModuleName() const;
213
214  /// \brief Retrieve the top-level module for this (sub)module, which may
215  /// be this module.
216  Module *getTopLevelModule() {
217    return const_cast<Module *>(
218             const_cast<const Module *>(this)->getTopLevelModule());
219  }
220
221  /// \brief Retrieve the top-level module for this (sub)module, which may
222  /// be this module.
223  const Module *getTopLevelModule() const;
224
225  /// \brief Retrieve the name of the top-level module.
226  ///
227  StringRef getTopLevelModuleName() const {
228    return getTopLevelModule()->Name;
229  }
230
231  /// \brief Retrieve the directory for which this module serves as the
232  /// umbrella.
233  const DirectoryEntry *getUmbrellaDir() const;
234
235  /// \brief Retrieve the header that serves as the umbrella header for this
236  /// module.
237  const FileEntry *getUmbrellaHeader() const {
238    return Umbrella.dyn_cast<const FileEntry *>();
239  }
240
241  /// \brief Determine whether this module has an umbrella directory that is
242  /// not based on an umbrella header.
243  bool hasUmbrellaDir() const {
244    return Umbrella && Umbrella.is<const DirectoryEntry *>();
245  }
246
247  /// \brief Add the given feature requirement to the list of features
248  /// required by this module.
249  ///
250  /// \param Feature The feature that is required by this module (and
251  /// its submodules).
252  ///
253  /// \param LangOpts The set of language options that will be used to
254  /// evaluate the availability of this feature.
255  ///
256  /// \param Target The target options that will be used to evaluate the
257  /// availability of this feature.
258  void addRequirement(StringRef Feature, const LangOptions &LangOpts,
259                      const TargetInfo &Target);
260
261  /// \brief Find the submodule with the given name.
262  ///
263  /// \returns The submodule if found, or NULL otherwise.
264  Module *findSubmodule(StringRef Name) const;
265
266  typedef std::vector<Module *>::iterator submodule_iterator;
267  typedef std::vector<Module *>::const_iterator submodule_const_iterator;
268
269  submodule_iterator submodule_begin() { return SubModules.begin(); }
270  submodule_const_iterator submodule_begin() const {return SubModules.begin();}
271  submodule_iterator submodule_end()   { return SubModules.end(); }
272  submodule_const_iterator submodule_end() const { return SubModules.end(); }
273
274  /// \brief Print the module map for this module to the given stream.
275  ///
276  void print(llvm::raw_ostream &OS, unsigned Indent = 0) const;
277
278  /// \brief Dump the contents of this module to the given output stream.
279  void dump() const;
280};
281
282} // end namespace clang
283
284
285#endif // LLVM_CLANG_BASIC_MODULE_H
286