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