luaObject.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file luaObject.h
//! \ingroup vreUtil
//! \brief Provides access to Lua tables and objects with C++ wrappers
//!
//! This file defines the DtLuaObject class which provides a C++ interface to
//! Lua objects. It allows for retrieval and manipulation of Lua tables and values
//! through C++ methods, simplifying the interaction between C++ and Lua.
 
#pragma once
 
#include "vreUtil/export.h"
#include "vreUtil/luaValue.h"
#include "vreUtil/luaStackCleaner.h"
#include "vreUtil/logger.h"
 
#include <string>
#include <vector>
 
struct lua_State;
 
namespace makVre
{
class DtLuaReference;
class DtLuaState;
 
//! \brief Represents a Lua object (typically a table) in C++
//!
//! This class provides a C++ interface to Lua objects, primarily tables.
//! It allows for retrieval and manipulation of Lua values through C++ methods,
//! simplifying the interaction between C++ and Lua code.
class UTIL_DLL DtLuaObject : public DtLuaValue
{
public:
   //! \brief Default constructor
   //!
   //! Creates an empty, invalid Lua object reference
   DtLuaObject();
 
   //! \brief Constructor from Lua stack value
   //! \param state The Lua state containing the object
   //! \param index Index of the object on the Lua stack
   DtLuaObject(lua_State& state, int index);
 
   //! \brief Virtual destructor
   //!
   //! Releases the reference to the Lua object
   virtual ~DtLuaObject() override;
 
   //! \brief Copy constructor
   //! \param orig The source object to copy from
   DtLuaObject(const DtLuaObject& orig);
 
   //! \brief Assignment operator
   //! \param orig The source object to assign from
   //! \return Reference to this object
   DtLuaObject& operator=(const DtLuaObject& orig);
 
   //! \brief Equality comparison operator
   //! \param rhs Right-hand side object to compare with
   //! \return True if objects reference the same Lua object, false otherwise
   virtual bool operator==(const DtLuaObject& rhs);
 
   //! \brief Gets the value of this object converted to a C++ type
   //! \tparam RT The C++ type to convert the Lua value to
   //! \return The Lua value converted to the specified C++ type
   //! \throw std::string if the object is invalid or conversion fails
   template <typename RT>
   RT get();
 
   //! \brief Pushes this object onto the Lua stack
   //!
   //! This method pushes a reference to the Lua object onto the Lua stack
   //! for operations that require the object to be on the stack.
   virtual void push() const;
 
   //! \name Table Access Methods
   //! \brief Methods for accessing table fields
   //! @{
 
   //! \brief Checks if the table has a field with the given name
   //! \param name The name of the field to check for
   //! \param resolveDots If true, handles dotted notation for nested tables (e.g., "table.field")
   //! \return True if the field exists, false otherwise
   virtual bool hasField(const std::string& name, bool resolveDots = true);
 
   //! \brief Checks if the table has a field at the given numeric index
   //! \param index The numeric index to check
   //! \return True if the field exists, false otherwise
   virtual bool hasField(int index);
   //! \brief Gets a field by name
   //! \param name The name of the field to retrieve
   //! \return A new DtLuaObject referencing the field
   virtual DtLuaObject operator[](std::string name);
 
   //! \brief Gets a field by numeric index
   //! \param index The numeric index of the field to retrieve
   //! \return A new DtLuaObject referencing the field
   virtual DtLuaObject operator[](int index);
   //! \brief Gets the number of elements in the table
   //! \return The number of elements in the table
   virtual int tableSize();
 
   //! \brief Gets all string keys in the table
   //! \return Vector of all string keys in the table
   std::vector<std::string> keys();
   //! \brief Sets a field value by name
   //! \tparam T The C++ type of the value to set
   //! \param name The name of the field to set
   //! \param val The value to set the field to
   //! \throw std::string if the object is invalid or not a table
   template <typename T>
   void setField(const std::string& name, const T& val);
 
   //! \brief Sets a field value by numeric index
   //! \tparam T The C++ type of the value to set
   //! \param index The numeric index of the field to set
   //! \param val The value to set the field to
   template <typename T>
   void setField(int index, const T& val);
   //! @}
 
   //! \brief Gets the Lua state associated with this object
   //! \return Pointer to the Lua state
   virtual lua_State* state();
 
   //! \brief Serializes the object to a string representation
   //! \return String representation of the Lua object
   virtual std::string serialize();
 
   //! \brief Checks if this object is valid
   //! \return True if the object is valid, false otherwise
   //!
   //! An object is valid if it has a valid Lua state and reference
   virtual bool isValid() const;
 
protected:
   //! \brief Retrieves a named item from the table and pushes it onto the stack
   //! \param name The name of the item to retrieve
   //! \param resolveDots If true, handles dotted notation for nested tables
   //! \return True if the item was found and pushed, false otherwise
   virtual bool getItemOnStack(const std::string& name, bool resolveDots);
 
   //! \brief Retrieves an indexed item from the table and pushes it onto the stack
   //! \param index The numeric index of the item to retrieve
   //! \return True if the item was found and pushed, false otherwise
   virtual bool getItemOnStack(int index);
 
   //! \brief Sets a table field with values already on the Lua stack
   //! \param index The stack index of the table
   //!
   //! This method expects the key and value to already be on the stack
   virtual void setTable(int index);
 
   //! \brief Reference to the Lua object
   DtLuaReference* myReference;
 
   //! \brief Pointer to the Lua state
   lua_State* myState;
};
 
} // namespace makVre
 
#include "vreUtil/luaState.h"
 
template <typename RT>
RT makVre::DtLuaObject::get()
{
   if (isValid() == false)
   {
      throw "Cannot set a field on a non-valid table";
   }
 
   DtLuaStackCleaner cleaner(*myState);
   DtLuaState state(*myState);
   push();
   return state.get<RT>(-1);
};
 
template <typename T>
void makVre::DtLuaObject::setField(const std::string& name, const T& val)
{
   if (isValid() == false)
   {
      throw "Cannot set a field on a non-valid table";
   }
 
   if (myType != SCRIPT_TABLE)
   {
      LOG_FATAL("Lua") << "Cannot set field in non-table type" << std::endl;
      return;
   }
 
   // use a stack cleaner to reset the stack after this function
   DtLuaStackCleaner cleaner(*myState);
 
   // In DtLuaState, the DtLuaState(lua_State& L) constructor (called below) doesnt actually copy, the state is pointing
   // to myState.
   //   Also in this class, there is a flag call myNeedToCloseState which actually deletes the lua state.
   //   The constructor used above sets this flag to false. So when the localstate gets deleted at the end of this
   //   function, it does not call lua_close().
   DtLuaState localState(*myState);
 
   push(); // get the table on the stack
 
   // TPC: This is a short hand way to call lua_push{boolean|string|number|...}
   // It is still pushing to the current state (myState) but we are using helper functions.
   //  see luaEncoderDecoder.h
   localState.push(name); // push the key name on the stack
   localState.push(val);  // push the value on the stack
 
   // lua_settable(state(), -3);
   setTable(-3);
};
 
template <typename T>
void makVre::DtLuaObject::setField(int index, const T& val)
{
   if (isValid() == false)
   {
      LOG_WARN("Lua") << "Cannot set a field on a non-valid table" << std::endl;
      return;
   }
 
   if (myType != SCRIPT_TABLE)
   {
      LOG_WARN("Lua") << "Cannot set field in non-table type" << std::endl;
      return;
   }
 
   // use a stack cleaner to reset the stack after this function
   DtLuaStackCleaner cleaner(*myState);
 
   // In DtLuaState, the DtLuaState(lua_State& L) constructor (called below) doesnt actually copy, the state is pointing
   // to myState.
   //   Also in this class, there is a flag call myNeedToCloseState which actually deletes the lua state.
   //   The constructor used above sets this flag to false. So when the localstate gets deleted at the end of this
   //   function, it does not call lua_close().
   DtLuaState localState(*myState);
 
   push(); // get the table on the stack
 
   // TPC: This is a short hand way to call lua_push{boolean|string|number|...}
   // It is still pushing to the current state (myState) but we are using helper functions.
   //  see luaEncoderDecoder.h
   localState.push(index); // push the key index on the stack
   localState.push(val);   // push the value on the stack
 
   // lua_settable(state(), -3);
   setTable(-3);
};