// SPDX-License-Identifier: GPL-3.0-or-later WITH STruCpp-runtime-exception
// Copyright (C) 2025 Autonomy / OpenPLC Project
// This file is part of the STruC++ Runtime Library and is covered by the
// STruC++ Runtime Library Exception. See COPYING.RUNTIME for details.
/**
 * STruC++ Runtime - IEC Structure Support
 *
 * This header provides infrastructure for IEC 61131-3 STRUCT types.
 * Actual struct definitions are generated by the compiler based on user TYPE declarations.
 * This file provides the base class and conventions for generated structures.
 *
 * Structure fields use IECVar<T> wrappers to support individual field forcing.
 */

#pragma once

#include "iec_var.hpp"

namespace strucpp {

/**
 * Base class for generated IEC structures.
 * Provides a common base for RTTI and potential reflection support.
 * Generated structures inherit from this class.
 */
class IEC_STRUCT_Base {
public:
    virtual ~IEC_STRUCT_Base() = default;
    
    // Optional: type name for debugging/reflection
    // Subclasses can override to return their type name
    virtual const char* type_name() const noexcept { return "STRUCT"; }
};

/*
 * Example generated structure:
 *
 * ST Source:
 *   TYPE Point : STRUCT
 *       x : REAL;
 *       y : REAL;
 *   END_STRUCT;
 *   END_TYPE
 *
 * Generated C++:
 *   struct Point : public IEC_STRUCT_Base {
 *       IECVar<REAL_t> x;
 *       IECVar<REAL_t> y;
 *       
 *       Point() noexcept : x{}, y{} {}
 *       
 *       const char* type_name() const noexcept override { return "Point"; }
 *   };
 *
 * Usage:
 *   Point p;
 *   p.x = 10.5f;
 *   p.y = 20.5f;
 *   
 *   // Force individual field
 *   p.x.force(100.0f);
 *   p.x = 0.0f;  // Ignored while forced
 *   assert(p.x.get() == 100.0f);
 */

/*
 * Example nested structure:
 *
 * ST Source:
 *   TYPE Rectangle : STRUCT
 *       topLeft : Point;
 *       bottomRight : Point;
 *   END_STRUCT;
 *   END_TYPE
 *
 * Generated C++:
 *   struct Rectangle : public IEC_STRUCT_Base {
 *       Point topLeft;
 *       Point bottomRight;
 *       
 *       Rectangle() noexcept : topLeft{}, bottomRight{} {}
 *       
 *       const char* type_name() const noexcept override { return "Rectangle"; }
 *   };
 *
 * Usage:
 *   Rectangle rect;
 *   rect.topLeft.x = 0.0f;
 *   rect.topLeft.y = 0.0f;
 *   rect.bottomRight.x = 100.0f;
 *   rect.bottomRight.y = 50.0f;
 */

/*
 * Example structure with array:
 *
 * ST Source:
 *   TYPE Polygon : STRUCT
 *       numPoints : INT;
 *       points : ARRAY[1..10] OF Point;
 *   END_STRUCT;
 *   END_TYPE
 *
 * Generated C++:
 *   struct Polygon : public IEC_STRUCT_Base {
 *       IECVar<INT_t> numPoints;
 *       Array1D<Point, 1, 10> points;
 *       
 *       Polygon() noexcept : numPoints{}, points{} {}
 *       
 *       const char* type_name() const noexcept override { return "Polygon"; }
 *   };
 */

}  // namespace strucpp