initializer.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
******************************************************************************/
 
//! \file initializer.h
//! \ingroup vreUtil
//! \brief Provides configuration initialization for VREngage components
//!
//! This file defines the DtInitializer and DtInitTable classes that handle loading
//! and accessing configuration data from Lua scripts. These classes provide a consistent
//! interface for component initialization and configuration retrieval throughout the
//! VREngage system.
 
#pragma once
 
#include "vreUtil/export.h"
#include "vreUtil/luaState.h"
#include "vreUtil/luaStackCleaner.h"
#include "vreUtil/logger.h"
 
#include <vlutil/vlFilename.h>
 
#include <string>
 
struct lua_State;
 
namespace makVre
{
class DtInitializer;
 
//! \brief Table-based access to Lua state for configuration data
//!
//! This class provides table-based access to a Lua state, allowing for
//! retrieval of configuration values from Lua tables. It is primarily used
//! by DtInitializer to access the global '_G' table and other configuration tables.
class UTIL_DLL DtInitTable : public DtLuaObject
{
public:
   //! \brief Default constructor
   //!
   //! Creates an empty initialization table
   DtInitTable();
 
   //! \brief Constructor with existing Lua state and table
   //! \param state Reference to the Lua state containing the table
   //! \param index Index of the table on the Lua stack
   //! \param throwOnMissingField If true, throws an exception when a requested field is not found
   DtInitTable(lua_State& state, int index, bool throwOnMissingField = true);
 
   //! \brief Destructor
   virtual ~DtInitTable() override;
 
   template <typename RT>
   RT findData(const std::string& name, bool resolveDots = true);
 
   template <typename RT>
   RT findDataOr(const std::string& name, RT defaultValue, bool silent = false, bool resolveDots = true);
 
   template <typename RT>
   RT findData(int index);
 
   //! \brief Sets whether to throw exceptions for missing fields
   //! \param set If true, missing fields will cause exceptions; if false, will return default values
   virtual void setThrowOnMissingField(bool set);
 
protected:
   //! \brief Controls exception behavior for missing fields
   //!
   //! When true, missing fields will cause exceptions to be thrown
   bool myThrowOnMissingField;
};
 
//! \brief Configuration initializer for VREngage components
//!
//! This class handles loading and accessing configuration data from Lua scripts.
//! It provides a consistent interface for component initialization throughout
//! the VREngage system, supporting command-line arguments and configuration files.
class UTIL_DLL DtInitializer : public DtLuaState
{
public:
   //! \brief Constructor using command-line arguments
   //! \param argc Number of command-line arguments
   //! \param argv Array of command-line argument strings
   //! \param throwOnMissingField If true, throws exceptions for missing configuration fields
   DtInitializer(int argc, char* argv[], bool throwOnMissingField = true);
 
   //! \brief Constructor using a configuration file
   //! \param configFile Path to the Lua configuration file to load
   //! \param throwOnMissingField If true, throws exceptions for missing configuration fields
   DtInitializer(DtFilename configFile, bool throwOnMissingField = true);
 
   //! \brief Virtual destructor
   virtual ~DtInitializer() override;
 
   //! \brief Checks if a configuration field exists
   //! \param name The name of the field to check
   //! \param resolveDots If true, handles dotted notation for nested tables
   //! \return True if the field exists, false otherwise
   virtual bool hasField(const std::string& name, bool resolveDots = true);
 
   //! \brief Retrieves a configuration value by name
   //! \tparam RT The type to convert the found data to
   //! \param name The name of the field to retrieve
   //! \param resolveDots If true, handles dotted notation for nested tables
   //! \return The value converted to the requested type
   //! \throw std::string if the field is not found and throwOnMissingField is true
   //! \note Supports basic types: bool, int, float, double, string, and tables as DtInitTable*
   template <typename RT>
   RT findData(const std::string& name, bool resolveDots = true);
 
   template <typename RT>
   RT findDataOr(const std::string& name, RT defaultValue, bool silent = false, bool resolveDots = true);
 
   template <typename RT>
   RT findData(int index);
 
   //! \brief Gets the number of command-line arguments
   //! \return The number of command-line arguments
   int argc();
 
   //! \brief Gets the array of command-line arguments
   //! \return Pointer to the array of command-line argument strings
   char** argv();
 
   //! \brief Adds an additional configuration file
   //! \param filename Path to the Lua configuration file to add
   //! \return True if the file was loaded successfully, false otherwise
   //!
   //! This method can be called to load additional configuration files after initialization
   virtual bool addConfigScript(std::string filename);
 
   //! \brief Adds configuration from a string
   //! \param str Lua code string containing configuration data
   //! \return True if the string was executed successfully, false otherwise
   //!
   //! This method can be called to add configuration from a string after initialization
   virtual bool addConfigString(std::string str);
 
   //! \brief Reloads the configuration script
   //! \return True if the script was reloaded successfully, false otherwise
   //!
   //! This method can be called to reload the configuration script after modifications
   virtual bool loadConfigScript();
 
protected:
   //! \brief Initializes the 'import' function in Lua
   //!
   //! Sets up a Lua function to import other Lua scripts into the current state
   void initImportFunction();
 
   //! \brief Creates and initializes the global table
   //!
   //! Creates a wrapper around the Lua global '_G' table for configuration access
   void createGlobalTable();
 
   //! \brief Path to the main configuration file
   DtFilename myConfigFilename;
 
   //! \brief Table wrapper for the Lua global environment
   DtInitTable myGlobalTable;
 
   //! \brief Controls exception behavior for missing fields
   bool myThrowOnMissingField;
 
   //! \brief Number of command-line arguments
   int myArgc;
 
   //! \brief Array of command-line argument strings
   char** myArgv;
};
}; // namespace makVre
 
template <typename RT>
RT makVre::DtInitTable::findData(const std::string& name, bool resolveDots /* = true */)
{
   DtLuaStackCleaner cleaner(*myState);
   if (getItemOnStack(name, resolveDots) == false)
   {
      std::string err = "Cannot find field: " + name;
      LOG_WARN("Util") << err << std::endl;
 
      if (myThrowOnMissingField == true)
      {
         throw(err);
      }
   }
 
   DtLuaState state(*myState);
   return state.get<RT>(-1);
}
 
template <typename RT>
RT makVre::DtInitTable::findData(int index)
{
   DtASSERT(index > 0, "lua table indexes start at 1");
 
   DtLuaStackCleaner cleaner(*myState);
   if (getItemOnStack(index) == false)
   {
      std::string err = "Cannot find field: " + index;
      LOG_WARN("Util") << err << std::endl;
 
      if (myThrowOnMissingField == true)
      {
         throw(err);
      }
   }
 
   DtLuaState state(*myState);
   return state.get<RT>(-1);
}
 
template <typename RT>
RT makVre::DtInitTable::findDataOr(const std::string& name, RT defaultValue, bool silent, bool resolveDots /* = true */)
{
   if (hasField(name, resolveDots) == false)
   {
      if (silent == false)
      {
         LOG_VERBOSE("Util") << "Did not find requested field \"" << name << "\" using default value" << std::endl;
      }
 
      return defaultValue;
   }
 
   return findData<RT>(name, resolveDots);
}
 
template <typename RT>
RT makVre::DtInitializer::findDataOr(
   const std::string& name, RT defaultValue, bool silent, bool resolveDots /* = true */)
{
   return myGlobalTable.findDataOr<RT>(name, defaultValue, silent, resolveDots);
}
 
template <typename RT>
RT makVre::DtInitializer::findData(const std::string& name, bool resolveDots /* = true */)
{
   return myGlobalTable.findData<RT>(name, resolveDots);
};
 
template <typename RT>
RT makVre::DtInitializer::findData(int index)
{
   return myGlobalTable.findData<RT>(index);
}