luaState.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file luaState.h
//! \ingroup vreUtil
//! \brief Provides an interface for interacting with a Lua state in VREngage
//!
//! This file defines the DtLuaState class which provides a high-level interface
//! for working with Lua states, including executing scripts, manipulating the stack,
//! and encoding/decoding values between C++ and Lua.
 
#pragma once
 
#include "vreUtil/export.h"
#include "vreUtil/assert.h"
 
#include "vreUtil/luaEncoderDecoder.h"
#include "vreUtil/luaObject.h"
 
#include <string>
#include <map>
 
struct lua_State;
 
namespace makVre
{
//! \brief Error handler function for Lua errors
//! \param L Pointer to the Lua state
//! \return Number of values returned on the Lua stack
//!
//! This function captures Lua errors, formats them with additional information,
//! and returns them as a string on the Lua stack.
int UTIL_DLL DtLuaErrorHandler(lua_State* L);
 
//! \brief Class for managing a Lua state and providing high-level operations
//!
//! This class encapsulates a Lua state and provides methods for executing scripts,
//! accessing Lua objects, and converting between C++ and Lua data types. It also
//! manages the encoder/decoder registry for type conversion.
class UTIL_DLL DtLuaState
{
private:
   //! \brief Copy constructor (not implemented)
   //!
   //! Copying a Lua state is not supported
   DtLuaState(const DtLuaState& orig); // not implemented
 
public:
   //! \brief Default constructor
   //!
   //! Creates a new Lua state and initializes it with standard libraries
   DtLuaState();
 
   //! \brief Constructor with existing Lua state
   //! \param L Reference to an existing Lua state to use
   DtLuaState(lua_State& L);
 
   //! \brief Virtual destructor
   //!
   //! Closes the Lua state if it was created by this object
   virtual ~DtLuaState();
 
   //! \brief Assignment operator
   //! \param orig The Lua state to copy from
   //! \return Reference to this object
   //!
   //! Copies the Lua state reference but does not copy the actual Lua state
   DtLuaState& operator=(const DtLuaState& orig);
 
   //! \brief Gets the underlying Lua state
   //! \return Pointer to the Lua state
   lua_State* state();
 
   //! \brief Checks if an object exists in the Lua state
   //! \param name Name of the object to check for
   //! \return True if the object exists, false otherwise
   virtual bool hasObject(const std::string& name);
 
   //! \brief Finds and returns a Lua object
   //! \param name Name of the object to find
   //! \return The Lua object if found
   virtual DtLuaObject findObject(const std::string& name);
 
   //! \brief Executes a Lua script from a file
   //! \param filename Path to the Lua script file
   //! \return True if execution succeeded, false otherwise
   virtual bool doFile(const std::string& filename);
 
   //! \brief Executes a Lua script from a string
   //! \param data The Lua script code as a string
   //! \return True if execution succeeded, false otherwise
   virtual bool doScript(const std::string& data);
 
   //! \brief Gets a value from the Lua stack and converts it to a C++ type
   //! \tparam RT Return type to convert the Lua value to
   //! \param stackIndex Index on the Lua stack
   //! \return The value converted to the requested C++ type
   //! \throw std::string if a decoder for the requested type is not found
   template <typename RT>
   RT get(int stackIndex);
 
   //! \brief Gets a named value from Lua and converts it to a C++ type
   //! \tparam RT Return type to convert the Lua value to
   //! \param name Name of the Lua variable/object to get
   //! \param resolveDots Whether to resolve dotted names (e.g., 'table.field')
   //! \return The value converted to the requested C++ type
   //! \throw std::string if the variable doesn't exist or a decoder for the type is not found
   template <typename RT>
   RT get(const std::string& name, bool resolveDots = true);
 
   //! \brief Pushes a C++ value onto the Lua stack
   //! \tparam T Type of the value to push
   //! \param data The value to push onto the Lua stack
   //! \throw std::string if an encoder for the specified type is not found
   template <typename T>
   void push(const T& data);
 
   //! \brief Stores a C++ value as a named variable in Lua
   //! \tparam T Type of the value to store
   //! \param name Name to give the variable in Lua
   //! \param data The value to store
   //! \return True if storage succeeded, false otherwise
   template <typename T>
   bool store(const std::string& name, const T& data);
 
   //! \brief Creates a new Lua table
   //! \param narr Pre-allocated array slots (optimization hint)
   //! \param nrec Pre-allocated record slots (optimization hint)
   //! \return A Lua object representing the new table
   virtual DtLuaObject createTable(int narr = 0, int nrec = 0);
 
   //! \brief Clears the Lua stack
   //!
   //! Removes all items from the Lua stack
   virtual void clearStack();
 
   //! \brief Dumps the contents of the Lua stack for debugging
   //!
   //! Prints each item on the stack to standard output
   virtual void stackDump();
 
   //! \brief Forces a full Lua garbage collection cycle
   virtual void forceGarbageCollection();
 
   //! \brief Registers an encoder for a specific C++ type
   //! \tparam T The C++ type to register an encoder for
   //! \param encoder Pointer to the encoder implementation
   template <typename T>
   static void addEncoder(DtBaseEncoder* encoder);
 
   //! \brief Registers a decoder for a specific C++ type
   //! \tparam T The C++ type to register a decoder for
   //! \param decoder Pointer to the decoder implementation
   template <typename T>
   static void addDecoder(DtBaseDecoder* decoder);
 
   //! \brief Retrieves a named item and pushes it onto the stack
   //! \param name Name of the item to retrieve
   //! \param resolveDots Whether to resolve dotted names (e.g., 'table.field')
   //! \return True if the item was found and pushed, false otherwise
   virtual bool getItemOnStack(const std::string& name, bool resolveDots = true);
 
   //! \brief Checks if the top stack value is valid
   //! \return True if the top stack value is valid, false otherwise
   virtual bool topStackValueOk();
 
   //! \brief Gets the current size of the Lua stack
   //! \return Number of items on the stack
   virtual int stackSize();
 
protected:
   //! \brief Prints a single value from the stack for debugging
   //! \param index Index of the value to print
   virtual void printValue(int index);
 
   //! \brief Prints a table from the stack for debugging
   //! \param index Index of the table to print
   virtual void printTable(int index);
 
   //! \brief Pointer to the Lua state
   lua_State* myState;
 
   //! \brief Flag indicating if the state should be closed on destruction
   bool myNeedToCloseState;
 
   //! \brief Type definition for the encoder registry map
   using EncoderMap = std::map<std::string, DtBaseEncoder*>;
 
   //! \brief Type definition for the decoder registry map
   using DecoderMap = std::map<std::string, DtBaseDecoder*>;
 
   //! \brief Static map of type names to encoder implementations
   static EncoderMap theEncoders;
 
   //! \brief Static map of type names to decoder implementations
   static DecoderMap theDecoders;
 
   //! \brief Initializes the standard encoders
   static void initEncoders();
 
   //! \brief Initializes the standard decoders
   static void initDecoders();
 
   //! \brief Flag indicating if encoders and decoders have been initialized
   static bool theInitializedEncoderDecoders;
};
 
template <typename RT>
RT DtLuaState::get(int stackIndex)
{
   DtLuaStackCleaner cleaner(*myState);
   DecoderMap::iterator iter = theDecoders.find(typeid(RT).name());
   if (iter == theDecoders.end())
   {
      std::string error = std::string("Cannot find data type decoder for type") + std::string(typeid(RT).name());
      DtASSERT(0, error.c_str());
      throw error;
   }
 
   DtTypeDecoder<RT>* decoder = (DtTypeDecoder<RT>*)iter->second;
   return decoder->get(myState, stackIndex);
};
 
template <typename RT>
RT DtLuaState::get(const std::string& name, bool resolveDots /* = true */)
{
   DtLuaStackCleaner cleaner(*myState);
   getItemOnStack(name, resolveDots);
 
   return get<RT>(-1);
};
 
template <typename T>
void DtLuaState::push(const T& data)
{
   EncoderMap::iterator iter = theEncoders.find(typeid(T).name());
   if (iter == theEncoders.end())
   {
      std::string error = std::string("Cannot find data type encoder for type") + std::string(typeid(T).name());
      DtASSERT(0, error.c_str());
      throw error;
   }
 
   DtTypeEncoder<T>* encoder = (DtTypeEncoder<T>*)iter->second;
 
   encoder->push(myState, data);
};
 
template <typename T>
static void DtLuaState::addEncoder(DtBaseEncoder* encoder)
{
   theEncoders[typeid(T).name()] = encoder;
};
 
template <typename T>
static void DtLuaState::addDecoder(DtBaseDecoder* decoder)
{
   theDecoders[typeid(T).name()] = decoder;
};
 
} // namespace makVre