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
21namespace llvm {
22
23class Constant;
24class LLVMContext;
25class MemoryBufferRef;
26class Module;
27class ModuleSummaryIndex;
28struct SlotMapping;
29class SMDiagnostic;
30class Type;
31
32typedef 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.
46std::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.
61std::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.
68struct 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.
86ParsedModuleAndIndex 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.
94ParsedModuleAndIndex 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.
106std::unique_ptr<ModuleSummaryIndex>
107parseSummaryIndexAssemblyFile(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.
117std::unique_ptr<ModuleSummaryIndex>
118parseSummaryIndexAssemblyString(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.
127std::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.
142ParsedModuleAndIndex 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.
153std::unique_ptr<ModuleSummaryIndex>
154parseSummaryIndexAssembly(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.
169bool 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.
184Constant *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.
192Type *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.
202Type *parseTypeAtBeginning(StringRef Asm, unsigned &Read, SMDiagnostic &Err,
203                           const Module &M, const SlotMapping *Slots = nullptr);
204
205} // End llvm namespace
206
207#endif
208