luaFunction.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file luaFunction.h
//! \ingroup vreUtil
//! \brief Provides a C++ wrapper for Lua functions
//!
//! This file defines the DtLuaFunction class which allows C++ code to easily
//! invoke Lua functions with type-safe parameter passing and return value handling.
//! It supports calling Lua functions with various numbers of parameters and
//! retrieving the result with proper type conversion.
 
#pragma once
 
#include "vreUtil/export.h"
 
#include "vreUtil/luaObject.h"
 
struct lua_State;
 
namespace makVre
{
//! \brief C++ wrapper for Lua functions
//!
//! This class provides a C++ interface to Lua functions, allowing them to be
//! called with type-safe parameter passing and return value handling.
//! It supports invoking Lua functions with up to five parameters and retrieving
//! the results with proper type conversion.
class UTIL_DLL DtLuaFunction : public DtLuaObject
{
public:
   //! \brief Default constructor
   //!
   //! Creates an empty, invalid function reference
   DtLuaFunction();
 
   //! \brief Constructor from Lua stack value
   //! \param state The Lua state containing the function
   //! \param index Index of the function on the Lua stack
   DtLuaFunction(lua_State& state, int index);
 
   //! \brief Virtual destructor
   virtual ~DtLuaFunction() override;
 
   //! \brief Construct from a Lua object
   //! \param funcObj Lua object referencing a function
   //!
   //! Constructs a function reference from a generic Lua object
   DtLuaFunction(const DtLuaObject& funcObj);
 
   //! \brief Copy constructor
   //! \param funcObj Source function to copy from
   DtLuaFunction(const DtLuaFunction& funcObj);
 
   //! \brief Assignment operator from Lua object
   //! \param funcObj Lua object referencing a function
   //! \return Reference to this function object
   DtLuaFunction& operator=(const DtLuaObject& funcObj);
 
   //! \brief Assignment operator
   //! \param func Source function to assign from
   //! \return Reference to this function object
   DtLuaFunction& operator=(const DtLuaFunction& func);
 
   //! \brief Calls the Lua function with no parameters
   //! \tparam RT Return type to convert the Lua result to
   //! \return The result of the function call converted to type RT
   //! \throw std::string if the function call fails or type conversion fails
   template <typename RT>
   RT call();
 
   //! \brief Calls the Lua function with one parameter
   //! \tparam RT Return type to convert the Lua result to
   //! \tparam P0 Type of the first parameter
   //! \param arg1 The first parameter to pass to the function
   //! \return The result of the function call converted to type RT
   //! \throw std::string if the function call fails or type conversion fails
   template <typename RT, typename P0>
   RT call(const P0& arg1);
 
   //! \brief Calls the Lua function with two parameters
   //! \tparam RT Return type to convert the Lua result to
   //! \tparam P0 Type of the first parameter
   //! \tparam P1 Type of the second parameter
   //! \param arg1 The first parameter to pass to the function
   //! \param arg2 The second parameter to pass to the function
   //! \return The result of the function call converted to type RT
   //! \throw std::string if the function call fails or type conversion fails
   template <typename RT, typename P0, typename P1>
   RT call(const P0& arg1, const P1& arg2);
 
   //! \brief Calls the Lua function with three parameters
   //! \tparam RT Return type to convert the Lua result to
   //! \tparam P0 Type of the first parameter
   //! \tparam P1 Type of the second parameter
   //! \tparam P2 Type of the third parameter
   //! \param arg1 The first parameter to pass to the function
   //! \param arg2 The second parameter to pass to the function
   //! \param arg3 The third parameter to pass to the function
   //! \return The result of the function call converted to type RT
   //! \throw std::string if the function call fails or type conversion fails
   template <typename RT, typename P0, typename P1, typename P2>
   RT call(const P0& arg1, const P1& arg2, const P2& arg3);
 
   //! \brief Calls the Lua function with four parameters
   //! \tparam RT Return type to convert the Lua result to
   //! \tparam P0 Type of the first parameter
   //! \tparam P1 Type of the second parameter
   //! \tparam P2 Type of the third parameter
   //! \tparam P3 Type of the fourth parameter
   //! \param arg1 The first parameter to pass to the function
   //! \param arg2 The second parameter to pass to the function
   //! \param arg3 The third parameter to pass to the function
   //! \param arg4 The fourth parameter to pass to the function
   //! \return The result of the function call converted to type RT
   //! \throw std::string if the function call fails or type conversion fails
   template <typename RT, typename P0, typename P1, typename P2, typename P3>
   RT call(const P0& arg1, const P1& arg2, const P2& arg3, const P3& arg4);
 
   //! \brief Calls the Lua function with five parameters
   //! \tparam RT Return type to convert the Lua result to
   //! \tparam P0 Type of the first parameter
   //! \tparam P1 Type of the second parameter
   //! \tparam P2 Type of the third parameter
   //! \tparam P3 Type of the fourth parameter
   //! \tparam P4 Type of the fifth parameter
   //! \param arg1 The first parameter to pass to the function
   //! \param arg2 The second parameter to pass to the function
   //! \param arg3 The third parameter to pass to the function
   //! \param arg4 The fourth parameter to pass to the function
   //! \param arg5 The fifth parameter to pass to the function
   //! \return The result of the function call converted to type RT
   //! \throw std::string if the function call fails or type conversion fails
   template <typename RT, typename P0, typename P1, typename P2, typename P3, typename P4>
   RT call(const P0& arg1, const P1& arg2, const P2& arg3, const P3& arg4, const P4& arg5);
 
protected:
   //! \brief Prepares the stack for a function call
   //!
   //! Sets up error handling and pushes the function onto the stack
   virtual void preFunction();
 
   //! \brief Cleans up after a function call
   //! \param argc Number of arguments that were passed to the function
   //!
   //! Removes the error handler and adjusts the stack as needed
   virtual void postFunction(int argc);
 
   //! \brief Stack index for the error handler function
   int myErrorIndex;
};
}; // namespace makVre
 
#include "vreUtil/luaFunction.inl"