include/llvm/AsmParser/Parser.h

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