SDOM - Simple SDL Document Object Model
A lightweight, extensible Document Object Model for SDL-based applications.
Loading...
Searching...
No Matches
SDOM_IDataObject.hpp
Go to the documentation of this file.
1/*** SDOM_IDataObject.hpp ****************************
2 * ___ ___ ___ __ __ ___ ___ _ ___ _ _ _ _
3 * / __| \ / _ \| \/ | |_ _| \ __ _| |_ __ _ / _ \| |__ (_)___ __| |_ | |_ _ __ _ __
4 * \__ \ |) | (_) | |\/| | | || |) / _` | _/ _` | (_) | '_ \| / -_) _| _|_| ' \| '_ \ '_ \
5 * |___/___/ \___/|_| |_|_|___|___/\__,_|\__\__,_|\___/|_.__// \___\__|\__(_)_||_| .__/ .__/
6 * |___| |__/ |_| |_|
7 *
8 * The SDOM_IDataObject class defines the core interface for all data-driven objects within
9 * the SDOM framework. It provides a flexible property and command registration system,
10 * enabling dynamic serialization, deserialization, and runtime manipulation of object state
11 * through JSON. By supporting property getters, setters, and commands, IDataObject allows for
12 * introspection, scripting, and editor integration, making it easy to extend and interact with
13 * objects in a generic way. This interface forms the foundation for resource and display object
14 * management in SDOM, facilitating robust data binding, configuration, and automation across
15 * the entire framework.
16 *
17 * This software is provided 'as-is', without any express or implied
18 * warranty. In no event will the authors be held liable for any damages
19 * arising from the use of this software.
20 *
21 * Permission is granted to anyone to use this software for any purpose,
22 * including commercial applications, and to alter it and redistribute it
23 * freely, subject to the following restrictions:
24 *
25 * 1. The origin of this software must not be misrepresented; you must not
26 * claim that you wrote the original software. If you use this software
27 * in a product, an acknowledgment in the product documentation would be
28 * appreciated but is not required.
29 * 2. Altered source versions must be plainly marked as such, and must not be
30 * misrepresented as being the original software.
31 * 3. This notice may not be removed or altered from any source distribution.
32 *
33 * Released under the ZLIB License.
34 * Original Author: Jay Faries (warte67)
35 *
36 ******************/
37
38/*
39================================================================================
40SDOM::IDataObject Contract
41
42Intent:
43 - IDataObject is the core interface for all data-driven objects in SDOM.
44 - Provides a flexible, dynamic property and command system for runtime manipulation, introspection, and automation.
45 - Enables serialization and deserialization of object state for scripting, configuration, and editor integration.
46
47Requirements:
48 1. Dynamic Properties
49 - Objects can register named properties with getter/setter functions.
50 - Properties are accessible for reading and writing at runtime.
51 - Properties can be introspected (listed, queried) for editor and scripting use.
52
53 2. Dynamic Commands
54 - Objects can register named commands (methods) callable at runtime.
55 - Commands can accept arguments and perform actions on the object.
56 - Commands are introspectable for automation and scripting.
57
58 3. Serialization/Deserialization
59 - Objects can serialize their state to a data format (now Lua tables).
60 - Objects can be initialized/deserialized from a data format (Lua tables).
61 - Serialization includes all registered properties and children (for hierarchical objects).
62
63 4. Editor/Scripting Integration
64 - Properties and commands are discoverable for external tools (editors, consoles, scripts).
65 - Supports runtime modification and automation.
66
67 5. Extensibility
68 - New properties and commands can be registered at runtime.
69 - Supports inheritance and composition for complex objects.
70
71Non-Requirements:
72 - Not responsible for rendering, event handling, or resource management (handled by other interfaces).
73 - Not tied to a specific serialization format (was JSON, now Lua; could be extended).
74`
75Summary:
76 IDataObject is a data-centric, introspectable, and extensible interface for SDOM objects, focused on:
77 - Dynamic property/command registration
78 - Runtime introspection and manipulation
79 - Serialization/deserialization for scripting, configuration, and editor integration
80================================================================================
81*/
82
83
84#ifndef __SDOM_IDataObject_HPP__
85#define __SDOM_IDataObject_HPP__
86
87// Avoid including the heavy umbrella SDOM.hpp here to prevent include cycles.
88// We still need small utilities used by this header: CLR (for colored prints)
89
90#include <sol/sol.hpp>
91#include <SDOM/SDOM_CLR.hpp>
93
94// Ensure DEBUG_REGISTER_LUA exists (normally provided by SDOM.hpp). If the
95// umbrella header is included by a TU it will override this; this definition
96// acts as a safe default when headers are included individually.
97// #ifndef DEBUG_REGISTER_LUA
98// // #define DEBUG_REGISTER_LUA 0
99// constexpr bool DEBUG_REGISTER_LUA = true;
100// #endif
101
102
103namespace SDOM
104{
105
107 {
108 public:
109
110 virtual bool onInit() = 0;
111 virtual void onQuit() = 0;
112 virtual bool onUnitTest() override { return true; }
113
114 template<typename T>
115 static T lua_value_case_insensitive(const sol::table& tbl, const std::string& key, const T& default_value)
116 {
117 for (const auto& kv : tbl)
118 {
119 std::string k = kv.first.as<std::string>();
120 if (std::equal(k.begin(), k.end(), key.begin(), key.end(),
121 [](char a, char b) { return std::tolower(a) == std::tolower(b); }))
122 {
123 return kv.second.as<T>();
124 }
125 }
126 return default_value;
127 }
128
129 std::string getName() const { return name_; }
130 void setName(const std::string& newName) { name_ = newName; }
131
132 // --- New Virtual LUA Registration for Sol2 ---
133 public:
134
135 // New preferred Lua binding path
136 void registerLuaBindings(const std::string& typeName, sol::state_view lua)
137 {
138 this->_registerLuaBindings(typeName, lua);
139 }
140
141 protected:
142
143 virtual void _registerLuaBindings(const std::string& typeName, sol::state_view lua)
144 {
145 // if (DEBUG_REGISTER_LUA)
146 if (false) // TEMP DISABLE
147 {
148 std::string typeNameLocal = "IDataObject";
149 std::cout << CLR::CYAN << "Registered " << CLR::LT_CYAN << typeNameLocal
150 << CLR::CYAN << " Lua bindings for type: " << CLR::LT_CYAN << typeName << CLR::RESET << std::endl;
151 }
152 }
153
154 sol::usertype<IDataObject> objHandleType_;
155
156 // --- End New Virtual LUA Registration for Sol2 ---
157
158 protected:
159
160 std::string name_ = "IDataObject"; // Default name, should be overridden by derived classes
161
162 };
163
164} // namespace SDOM
165
166#endif // __SDOM_IDataObject_HPP__
Static container for ANSI escape sequences for terminal text formatting and colorization.
static const std::string RESET
ANSI escape sequence to reset formatting.
Definition SDOM_CLR.hpp:245
static const std::string LT_CYAN
ANSI escape sequence for light cyan foreground.
Definition SDOM_CLR.hpp:281
static const std::string CYAN
ANSI escape sequence for cyan foreground.
Definition SDOM_CLR.hpp:273
Definition SDOM_IDataObject.hpp:107
void registerLuaBindings(const std::string &typeName, sol::state_view lua)
Definition SDOM_IDataObject.hpp:136
void setName(const std::string &newName)
Definition SDOM_IDataObject.hpp:130
virtual void _registerLuaBindings(const std::string &typeName, sol::state_view lua)
Definition SDOM_IDataObject.hpp:143
std::string getName() const
Definition SDOM_IDataObject.hpp:129
virtual void onQuit()=0
sol::usertype< IDataObject > objHandleType_
Definition SDOM_IDataObject.hpp:154
static T lua_value_case_insensitive(const sol::table &tbl, const std::string &key, const T &default_value)
Definition SDOM_IDataObject.hpp:115
virtual bool onUnitTest() override
Runs unit tests for this object.
Definition SDOM_IDataObject.hpp:112
virtual bool onInit()=0
std::string name_
Definition SDOM_IDataObject.hpp:160
Interface for unit testing objects in SDOM.
Definition SDOM_IUnitTest.hpp:31
Contains all core classes and utilities for the SDOM library.
Definition lua_BindHelpers.hpp:7