1 //===-- Parser.h - Parser for LLVM IR text assembly files -------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 //  These classes are implemented by the lib/AsmParser library.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_ASMPARSER_PARSER_H
14 #define LLVM_ASMPARSER_PARSER_H
15 
16 #include "llvm/ADT/Optional.h"
17 #include "llvm/ADT/STLForwardCompat.h"
18 #include "llvm/ADT/STLFunctionalExtras.h"
19 #include "llvm/ADT/StringRef.h"
20 #include <memory>
21 
22 namespace llvm {
23 
24 class Constant;
25 class LLVMContext;
26 class MemoryBufferRef;
27 class Module;
28 class ModuleSummaryIndex;
29 struct SlotMapping;
30 class SMDiagnostic;
31 class Type;
32 
33 typedef llvm::function_ref<Optional<std::string>(StringRef)>
34     DataLayoutCallbackTy;
35 
36 /// This function is a main interface to the LLVM Assembly Parser. It parses
37 /// an ASCII file that (presumably) contains LLVM Assembly code. It returns a
38 /// Module (intermediate representation) with the corresponding features. Note
39 /// that this does not verify that the generated Module is valid, so you should
40 /// run the verifier after parsing the file to check that it is okay.
41 /// Parse LLVM Assembly from a file
42 /// \param Filename The name of the file to parse
43 /// \param Err Error result info.
44 /// \param Context Context in which to allocate globals info.
45 /// \param Slots The optional slot mapping that will be initialized during
46 ///              parsing.
47 std::unique_ptr<Module> parseAssemblyFile(StringRef Filename, SMDiagnostic &Err,
48                                           LLVMContext &Context,
49                                           SlotMapping *Slots = nullptr);
50 
51 /// The function is a secondary interface to the LLVM Assembly Parser. It parses
52 /// an ASCII string that (presumably) contains LLVM Assembly code. It returns a
53 /// Module (intermediate representation) with the corresponding features. Note
54 /// that this does not verify that the generated Module is valid, so you should
55 /// run the verifier after parsing the file to check that it is okay.
56 /// Parse LLVM Assembly from a string
57 /// \param AsmString The string containing assembly
58 /// \param Err Error result info.
59 /// \param Context Context in which to allocate globals info.
60 /// \param Slots The optional slot mapping that will be initialized during
61 ///              parsing.
62 std::unique_ptr<Module> parseAssemblyString(StringRef AsmString,
63                                             SMDiagnostic &Err,
64                                             LLVMContext &Context,
65                                             SlotMapping *Slots = nullptr);
66 
67 /// Holds the Module and ModuleSummaryIndex returned by the interfaces
68 /// that parse both.
69 struct ParsedModuleAndIndex {
70   std::unique_ptr<Module> Mod;
71   std::unique_ptr<ModuleSummaryIndex> Index;
72 };
73 
74 /// This function is a main interface to the LLVM Assembly Parser. It parses
75 /// an ASCII file that (presumably) contains LLVM Assembly code, including
76 /// a module summary. It returns a Module (intermediate representation) and
77 /// a ModuleSummaryIndex with the corresponding features. Note that this does
78 /// not verify that the generated Module or Index are valid, so you should
79 /// run the verifier after parsing the file to check that they are okay.
80 /// Parse LLVM Assembly from a file
81 /// \param Filename The name of the file to parse
82 /// \param Err Error result info.
83 /// \param Context Context in which to allocate globals info.
84 /// \param Slots The optional slot mapping that will be initialized during
85 ///              parsing.
86 /// \param DataLayoutCallback Override datalayout in the llvm assembly.
87 ParsedModuleAndIndex parseAssemblyFileWithIndex(
88     StringRef Filename, SMDiagnostic &Err, LLVMContext &Context,
89     SlotMapping *Slots = nullptr,
90     DataLayoutCallbackTy DataLayoutCallback = [](StringRef) { return None; });
91 
92 /// Only for use in llvm-as for testing; this does not produce a valid module.
93 ParsedModuleAndIndex parseAssemblyFileWithIndexNoUpgradeDebugInfo(
94     StringRef Filename, SMDiagnostic &Err, LLVMContext &Context,
95     SlotMapping *Slots, DataLayoutCallbackTy DataLayoutCallback);
96 
97 /// This function is a main interface to the LLVM Assembly Parser. It parses
98 /// an ASCII file that (presumably) contains LLVM Assembly code for a module
99 /// summary. It returns a a ModuleSummaryIndex with the corresponding features.
100 /// Note that this does not verify that the generated Index is valid, so you
101 /// should run the verifier after parsing the file to check that it is okay.
102 /// Parse LLVM Assembly Index from a file
103 /// \param Filename The name of the file to parse
104 /// \param Err Error result info.
105 std::unique_ptr<ModuleSummaryIndex>
106 parseSummaryIndexAssemblyFile(StringRef Filename, SMDiagnostic &Err);
107 
108 /// parseAssemblyFile and parseAssemblyString are wrappers around this function.
109 /// Parse LLVM Assembly from a MemoryBuffer.
110 /// \param F The MemoryBuffer containing assembly
111 /// \param Err Error result info.
112 /// \param Slots The optional slot mapping that will be initialized during
113 ///              parsing.
114 /// \param DataLayoutCallback Override datalayout in the llvm assembly.
115 std::unique_ptr<Module> parseAssembly(
116     MemoryBufferRef F, SMDiagnostic &Err, LLVMContext &Context,
117     SlotMapping *Slots = nullptr,
118     DataLayoutCallbackTy DataLayoutCallback = [](StringRef) { return None; });
119 
120 /// Parse LLVM Assembly including the summary index from a MemoryBuffer.
121 ///
122 /// \param F The MemoryBuffer containing assembly with summary
123 /// \param Err Error result info.
124 /// \param Slots The optional slot mapping that will be initialized during
125 ///              parsing.
126 ///
127 /// parseAssemblyFileWithIndex is a wrapper around this function.
128 ParsedModuleAndIndex parseAssemblyWithIndex(MemoryBufferRef F,
129                                             SMDiagnostic &Err,
130                                             LLVMContext &Context,
131                                             SlotMapping *Slots = nullptr);
132 
133 /// Parse LLVM Assembly for summary index from a MemoryBuffer.
134 ///
135 /// \param F The MemoryBuffer containing assembly with summary
136 /// \param Err Error result info.
137 ///
138 /// parseSummaryIndexAssemblyFile is a wrapper around this function.
139 std::unique_ptr<ModuleSummaryIndex>
140 parseSummaryIndexAssembly(MemoryBufferRef F, SMDiagnostic &Err);
141 
142 /// This function is the low-level interface to the LLVM Assembly Parser.
143 /// This is kept as an independent function instead of being inlined into
144 /// parseAssembly for the convenience of interactive users that want to add
145 /// recently parsed bits to an existing module.
146 ///
147 /// \param F The MemoryBuffer containing assembly
148 /// \param M The module to add data to.
149 /// \param Index The index to add data to.
150 /// \param Err Error result info.
151 /// \param Slots The optional slot mapping that will be initialized during
152 ///              parsing.
153 /// \return true on error.
154 /// \param DataLayoutCallback Override datalayout in the llvm assembly.
155 bool parseAssemblyInto(
156     MemoryBufferRef F, Module *M, ModuleSummaryIndex *Index, SMDiagnostic &Err,
157     SlotMapping *Slots = nullptr,
158     DataLayoutCallbackTy DataLayoutCallback = [](StringRef) { return None; });
159 
160 /// Parse a type and a constant value in the given string.
161 ///
162 /// The constant value can be any LLVM constant, including a constant
163 /// expression.
164 ///
165 /// \param Slots The optional slot mapping that will restore the parsing state
166 /// of the module.
167 /// \return null on error.
168 Constant *parseConstantValue(StringRef Asm, SMDiagnostic &Err, const Module &M,
169                              const SlotMapping *Slots = nullptr);
170 
171 /// Parse a type in the given string.
172 ///
173 /// \param Slots The optional slot mapping that will restore the parsing state
174 /// of the module.
175 /// \return null on error.
176 Type *parseType(StringRef Asm, SMDiagnostic &Err, const Module &M,
177                 const SlotMapping *Slots = nullptr);
178 
179 /// Parse a string \p Asm that starts with a type.
180 /// \p Read[out] gives the number of characters that have been read to parse
181 /// the type in \p Asm.
182 ///
183 /// \param Slots The optional slot mapping that will restore the parsing state
184 /// of the module.
185 /// \return null on error.
186 Type *parseTypeAtBeginning(StringRef Asm, unsigned &Read, SMDiagnostic &Err,
187                            const Module &M, const SlotMapping *Slots = nullptr);
188 
189 } // End llvm namespace
190 
191 #endif
192