//===-- llvm/Bytecode/Reader.h - Reader for VM bytecode files ---*- C++ -*-===//
//
+// The LLVM Compiler Infrastructure
+//
+// This file was developed by the LLVM research group and is distributed under
+// the University of Illinois Open Source License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+//
// This functionality is implemented by the lib/Bytecode/Reader library.
// This library is used to read VM bytecode files from an iostream.
//
#ifndef LLVM_BYTECODE_READER_H
#define LLVM_BYTECODE_READER_H
+#include "llvm/System/Path.h"
#include "llvm/ModuleProvider.h"
+#include "llvm/Module.h"
#include <string>
-#include <vector>
-
-/// getBytecodeModuleProvider - lazy function-at-a-time loading from a file
-///
-AbstractModuleProvider*
-getBytecodeModuleProvider(const std::string &Filename);
-
-/// getBytecodeBufferModuleProvider - lazy function-at-a-time loading from a
-/// buffer
-///
-AbstractModuleProvider*
-getBytecodeBufferModuleProvider(const unsigned char *Buffer,
- unsigned BufferSize,
- const std::string &ModuleID = "");
-
-/// ParseBytecodeFile - Parse the given bytecode file
-///
-Module* ParseBytecodeFile(const std::string &Filename,
- std::string *ErrorStr = 0);
-
-/// ParseBytecodeBuffer - Parse a given bytecode buffer
-///
-Module* ParseBytecodeBuffer(const unsigned char *Buffer,
- unsigned BufferSize,
- const std::string &ModuleID = "",
- std::string *ErrorStr = 0);
-
-/// ReadArchiveFile - Read bytecode files from the specfied .a file, returning
-/// true on error, or false on success.
-///
-bool ReadArchiveFile(const std::string &Filename,
- std::vector<Module*> &Objects,
- std::string *ErrorStr = 0);
+
+namespace llvm {
+
+// Forward declare the handler class
+class BytecodeHandler;
+
+/// This function returns a ModuleProvider that can be used to do lazy
+/// function-at-a-time loading from a bytecode file.
+/// @returns NULL on error
+/// @returns ModuleProvider* if successful
+/// @brief Get a ModuleProvide for a bytecode file.
+ModuleProvider *getBytecodeModuleProvider(
+ const std::string &Filename, ///< Name of file to be read
+ std::string* ErrMsg = 0, ///< Optional error message holder
+ BytecodeHandler* H = 0 ///< Optional handler for reader events
+);
+
+/// This function returns a ModuleProvider that can be used to do lazy
+/// function function-at-a-time loading from a bytecode buffer.
+/// @returns NULL on error
+/// @returns ModuleProvider* if successful
+/// @brief Get a ModuleProvider for a bytecode buffer.
+ModuleProvider *getBytecodeBufferModuleProvider(
+ const unsigned char *Buffer, ///< Start of buffer to parse
+ unsigned BufferSize, ///< Size of the buffer
+ const std::string &ModuleID, ///< Name to give the module
+ std::string* ErrMsg = 0, ///< Optional place to return an error message
+ BytecodeHandler* H = 0 ///< Optional handler for reader events
+);
+
+/// This is the main interface to bytecode parsing. It opens the file specified
+/// by \p Filename and parses the entire file, returing the corresponding Module
+/// object if successful.
+/// @returns NULL on error
+/// @returns the module corresponding to the bytecode file, if successful
+/// @brief Parse the given bytecode file
+Module* ParseBytecodeFile(
+ const std::string &Filename, ///< Name of file to parse
+ std::string *ErrMsg = 0 ///< Optional place to return an error message
+);
+
+/// Parses a bytecode buffer specified by \p Buffer and \p BufferSize.
+/// @returns NULL on error
+/// @returns the module corresponding to the bytecode buffer, if successful
+/// @brief Parse a given bytecode buffer
+Module* ParseBytecodeBuffer(
+ const unsigned char *Buffer, ///< Start of buffer to parse
+ unsigned BufferSize, ///< Size of the buffer
+ const std::string &ModuleID="", ///< Name to give the module
+ std::string *ErrMsg = 0 ///< Optional place to return an error message
+);
+
+/// This function will read only the necessary parts of a bytecode file in order
+/// to determine the list of dependent libraries encoded within it. The \p
+/// deplibs parameter will contain a vector of strings of the bytecode module's
+/// dependent libraries.
+/// @returns true on error, false otherwise
+/// @brief Get the list of dependent libraries from a bytecode file.
+bool GetBytecodeDependentLibraries(
+ const std::string &fileName, ///< File name to read bytecode from
+ Module::LibraryListType& deplibs, ///< List of dependent libraries extracted
+ std::string* ErrMsg = 0 ///< Optional error message holder
+);
+
+/// This function will read only the necessary parts of a bytecode file in order
+/// to obtain a list of externally visible global symbols that the bytecode
+/// module defines. This is used for archiving and linking when only the list
+/// of symbols the module defines is needed.
+/// @returns true on error, false otherwise
+/// @brief Get a bytecode file's externally visibile defined global symbols.
+bool GetBytecodeSymbols(
+ const sys::Path& fileName, ///< Filename to read bytecode from
+ std::vector<std::string>& syms, ///< Vector to return symbols in
+ std::string* ErrMsg = 0 ///< Optional error message holder
+);
+
+/// This function will read only the necessary parts of a bytecode buffer in
+/// order to obtain a list of externally visible global symbols that the
+/// bytecode module defines. This is used for archiving and linking when only
+/// the list of symbols the module defines is needed and the bytecode is
+/// already in memory.
+/// @returns the ModuleProvider on success, 0 if the bytecode can't be parsed
+/// @brief Get a bytecode file's externally visibile defined global symbols.
+ModuleProvider* GetBytecodeSymbols(
+ const unsigned char*Buffer, ///< The buffer to be parsed
+ unsigned Length, ///< The length of \p Buffer
+ const std::string& ModuleID, ///< An identifier for the module
+ std::vector<std::string>& symbols, ///< The symbols defined in the module
+ std::string* ErrMsg = 0 ///< Optional error message holder
+);
+
+} // End llvm namespace
#endif